Octop Providers API: Configure LLM Providers and Models#

The Providers API lets you configure which LLM providers and models your agents use. Providers can be per-user (created by any authenticated user and visible only to them) or admin-global (created under /api/admin/providers and shared across all accounts). All agents reference providers by name when selecting a model.

#Endpoints

#Create a provider

Provide a name, a kind, and the connection details for your chosen LLM service.

curl -X POST http://127.0.0.1:8088/api/providers \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "openai",
    "kind": "openai",
    "base_url": "https://api.openai.com/v1",
    "api_key": "sk-..."
  }'

curl -X POST http://127.0.0.1:8088/api/providers \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "local-ollama",
    "kind": "ollama",
    "base_url": "http://127.0.0.1:11434"
  }'

curl -X POST http://127.0.0.1:8088/api/providers \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "dashscope",
    "kind": "dashscope",
    "api_key": "sk-..."
  }'

#Test a provider

After creating a provider, verify the connection is healthy by calling its test endpoint. Octop sends a minimal model request with a timeout. For embedding providers, it probes the embeddings endpoint instead. Common authentication, quota, rate-limit, and provider-outage failures are returned as localized guidance when Octop can classify the upstream error.

curl -X POST http://127.0.0.1:8088/api/providers/openai/test \
  -H 'Authorization: Bearer $TOKEN'

{"ok": true, "latency_ms": 312}

{"ok": false, "error": "Authentication failed: invalid API key"}

Pass model_id or embedding: true in the JSON body when you want to test a specific chat or embedding model.

#List resolved models

GET /models returns the combined list of models available across all providers enabled for your account. Use the model values from this list when creating or updating agents.

curl http://127.0.0.1:8088/api/models \
  -H 'Authorization: Bearer $TOKEN'

#Set the active model

The active model is the system-wide default used when an agent does not specify a default_model. Only admins can change it.

curl -X PUT http://127.0.0.1:8088/api/models/active \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"provider_name": "openai", "model": "gpt-4o"}'

#ACP (Agent Client Protocol)

The ACP endpoints let you configure external runner connections that agents can invoke as tools. These endpoints are separate from provider configuration but live in the same authentication context.