Provider Management API

Provider Management API

The Provider Management API allows administrators to list, configure, update, and remove AI provider integrations. Providers are org-scoped — credentials configured for one org are isolated and never shared with other orgs.

All endpoints require admin authentication.

Base URL: https://api.arbitex.ai

Authentication: Authorization: Bearer $ARBITEX_API_KEY

---

Provider object

interface Provider {
  id: string;                    // Provider slug: "openai", "anthropic", "azure_openai", etc.
  name: string;                  // Human-readable name
  type: "native" | "openai_compatible" | "aws_bedrock" | "byoe";
  status: "active" | "disabled" | "kill_switched" | "unhealthy";
  credentials_configured: boolean;
  last_health_check: string;     // ISO 8601 timestamp
  health_check_status: "healthy" | "degraded" | "unreachable" | "unknown";
  models_enabled: number;        // Count of enabled models for this provider
  config: ProviderConfig;
}

interface ProviderConfig {
  // Present for azure_openai
  azure_endpoint?: string;       // e.g., "https://myorg.openai.azure.com"
  azure_api_version?: string;    // e.g., "2024-02-01"

  // Present for aws_bedrock
  aws_region?: string;           // e.g., "us-east-1"
  aws_access_key_id?: string;    // Masked: "AKIA...XXXX"

  // Present for byoe
  base_url?: string;             // Custom endpoint base URL
  format?: "openai" | "anthropic"; // Request format to use

  // Present for ollama
  ollama_base_url?: string;      // e.g., "http://ollama.internal:11434"

  // All providers
  timeout_ms?: number;           // Per-request timeout override (default: 30000)
  max_retries?: number;          // Retry attempts on 5xx (default: 2)
}

---

List providers

Returns all provider configurations for the authenticated org.

GET /api/admin/providers
Authorization: Bearer $ARBITEX_API_KEY

Response 200 OK:

{
  "providers": [
    {
      "id": "openai",
      "name": "OpenAI",
      "type": "native",
      "status": "active",
      "credentials_configured": true,
      "last_health_check": "2026-03-12T17:00:00Z",
      "health_check_status": "healthy",
      "models_enabled": 5,
      "config": {
        "timeout_ms": 30000,
        "max_retries": 2
      }
    },
    {
      "id": "anthropic",
      "name": "Anthropic",
      "type": "native",
      "status": "active",
      "credentials_configured": true,
      "last_health_check": "2026-03-12T17:00:00Z",
      "health_check_status": "healthy",
      "models_enabled": 3,
      "config": {}
    },
    {
      "id": "azure_openai",
      "name": "Azure OpenAI",
      "type": "native",
      "status": "active",
      "credentials_configured": true,
      "last_health_check": "2026-03-12T16:58:00Z",
      "health_check_status": "degraded",
      "models_enabled": 2,
      "config": {
        "azure_endpoint": "https://myorg.openai.azure.com",
        "azure_api_version": "2024-02-01"
      }
    }
  ]
}

Provider status values:

Status	Description
active	Provider is configured and available for routing
disabled	Manually disabled by an admin — no traffic routed
kill_switched	Disabled via the kill switch API — no traffic routed
unhealthy	Health monitor has marked provider unreachable

---

Get provider

GET /api/admin/providers/{provider_id}
Authorization: Bearer $ARBITEX_API_KEY

Path parameters:

Parameter	Description
provider_id	Provider slug: openai, anthropic, azure_openai, aws_bedrock, google_gemini, groq, mistral, cohere, ollama, or byoe

Response 200 OK: Single Provider object.

Returns 404 Not Found if the provider has not been configured for the org.

---

Configure provider credentials

Sets or updates the API credentials for a provider. Credentials are stored encrypted. The raw credential is accepted once and is never returned by the API.

PUT /api/admin/providers/{provider_id}/credentials
Authorization: Bearer $ARBITEX_API_KEY
Content-Type: application/json

OpenAI / Anthropic / Google Gemini / Groq / Mistral / Cohere

{
  "api_key": "sk-proj-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

Azure OpenAI

{
  "api_key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "azure_endpoint": "https://myorg.openai.azure.com",
  "azure_api_version": "2024-02-01"
}

azure_api_version defaults to "2024-02-01" if not specified.

AWS Bedrock

{
  "aws_access_key_id": "AKIAIOSFODNN7EXAMPLE",
  "aws_secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
  "aws_region": "us-east-1"
}

For IAM role-based authentication (recommended for EC2/EKS deployments), omit credentials entirely and set use_instance_role: true:

{
  "use_instance_role": true,
  "aws_region": "us-east-1"
}

Ollama

{
  "ollama_base_url": "http://ollama.internal:11434"
}

No API key is required for Ollama; authentication is network-level.

Response 200 OK:

{
  "provider_id": "openai",
  "credentials_configured": true,
  "updated_at": "2026-03-12T17:00:00Z"
}

Errors:

Code	Detail
400	Missing required fields for the provider type
422	Credential validation failed (e.g., API key format invalid)

---

Update provider configuration

Updates non-credential configuration for a provider (timeout, retry behavior).

PATCH /api/admin/providers/{provider_id}/config
Authorization: Bearer $ARBITEX_API_KEY
Content-Type: application/json

{
  "timeout_ms": 60000,
  "max_retries": 3
}

Request body:

Field	Type	Description
timeout_ms	integer	Per-request timeout in milliseconds (100–300000)
max_retries	integer	Retry attempts on provider 5xx errors (0–5)

Response 200 OK:

{
  "provider_id": "openai",
  "config": {
    "timeout_ms": 60000,
    "max_retries": 3
  },
  "updated_at": "2026-03-12T17:00:00Z"
}

---

Enable / disable a provider

Enables or disables a provider for routing. Disabling a provider stops all traffic without activating the kill switch (disabling is reversible in the admin panel; kill switch is the emergency override).

PUT /api/admin/providers/{provider_id}/status
Authorization: Bearer $ARBITEX_API_KEY
Content-Type: application/json

{
  "enabled": false,
  "reason": "Rotating credentials"
}

Request body:

Field	Type	Required	Description
enabled	boolean	Yes	true to enable, false to disable
reason	string	No	Audit log annotation

Response 200 OK:

{
  "provider_id": "openai",
  "status": "disabled",
  "changed_by": "admin@example.com",
  "reason": "Rotating credentials",
  "changed_at": "2026-03-12T17:00:00Z"
}

---

Run health check

Triggers an immediate health check for a provider. Normally health checks run on a 30-second schedule; this endpoint forces an immediate check.

POST /api/admin/providers/{provider_id}/health-check
Authorization: Bearer $ARBITEX_API_KEY

Response 200 OK:

{
  "provider_id": "openai",
  "health_check_status": "healthy",
  "response_time_ms": 142,
  "checked_at": "2026-03-12T17:00:00Z",
  "error": null
}

On failure:

{
  "provider_id": "azure_openai",
  "health_check_status": "unreachable",
  "response_time_ms": null,
  "checked_at": "2026-03-12T17:00:00Z",
  "error": "Connection timeout after 5000ms"
}

---

BYOE (Bring Your Own Endpoint) provider

Registers a custom OpenAI-compatible or Anthropic-compatible endpoint as a provider.

POST /api/admin/providers/byoe
Authorization: Bearer $ARBITEX_API_KEY
Content-Type: application/json

{
  "id": "my-azure-proxy",
  "name": "My Azure Proxy",
  "base_url": "https://proxy.internal/v1",
  "format": "openai",
  "api_key": "optional-bearer-token",
  "timeout_ms": 45000,
  "models": [
    {
      "model_id": "gpt-4o-via-proxy",
      "display_name": "GPT-4o via Proxy",
      "context_window": 128000,
      "input_cost_per_1k": 0.005,
      "output_cost_per_1k": 0.015
    }
  ]
}

Request body:

Field	Type	Required	Description
id	string	Yes	Unique slug for this BYOE provider (alphanumeric, hyphens)
name	string	Yes	Display name
base_url	string	Yes	Base URL of the custom endpoint
format	"openai" | "anthropic"	Yes	API format of the endpoint
api_key	string	No	Bearer token for the endpoint (stored encrypted)
timeout_ms	integer	No	Request timeout override
models	array	Yes	One or more model definitions to register

Response 201 Created: Provider object.

To update a BYOE provider’s models or config, use PATCH /api/admin/providers/byoe/{id}.

To delete a BYOE provider:

DELETE /api/admin/providers/byoe/{id}
Authorization: Bearer $ARBITEX_API_KEY

Returns 204 No Content. Deleting a BYOE provider disables all its models in the catalog but does not delete routing rules or fallback chains that reference it (they will fail validation until updated).

---

Provider health check configuration

Configure the health check schedule and behavior for a provider.

PUT /api/admin/providers/{provider_id}/health-check-config
Authorization: Bearer $ARBITEX_API_KEY
Content-Type: application/json

{
  "enabled": true,
  "interval_seconds": 30,
  "timeout_ms": 5000,
  "failure_threshold": 3,
  "recovery_threshold": 2
}

Fields:

Field	Default	Description
enabled	true	Enable or disable automated health checks
interval_seconds	30	How often to probe the provider (10–300)
timeout_ms	5000	Health check request timeout
failure_threshold	3	Consecutive failures before marking unhealthy
recovery_threshold	2	Consecutive successes before marking healthy

---

Supported provider IDs

provider_id	Provider
openai	OpenAI
anthropic	Anthropic
google_gemini	Google Gemini
azure_openai	Azure OpenAI
aws_bedrock	AWS Bedrock
groq	Groq
mistral	Mistral AI
cohere	Cohere
ollama	Ollama (self-hosted)
byoe	Bring Your Own Endpoint

---

See also

• Provider Management Guide — Admin guide for provider configuration
• Routing — Routing modes, fallback chains, health monitor
• Kill Switch API — Emergency provider disable
• Routing Rules API — Routing strategy configuration
• Model Catalog API — Model registration and discovery