Octop Providers API: Configure LLM Providers and Models
The Providers API lets you configure which LLM providers and models your agents use. Signed-in users can list providers and the models they may select. Creating, updating, deleting, and testing a provider, and setting the global default model, require the providers permission. Write operations use /api/admin/providers. Agents reference providers by name when selecting a model.
An OpenAI-compatible provider can select Responses (/v1/responses) or Chat Completions. New preset models, including Hunyuan HY4 on the Tencent Cloud channel, are synced when the server starts.
Endpoints
Create a provider
Provide a name, a kind, and the connection details for your chosen LLM service.
API keys are stored encrypted at rest. To replace a key, send PATCH /api/admin/providers/{id} with the new api_key.
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.
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 /providers/resolved returns the enabled models the caller may select. Each item includes provider_name and model.
Set the active model
The active model is the system-wide default used when an agent does not specify a default_model. Changing it requires the providers permission.
Deleting a provider that is still referenced by one or more agents returns 409 PROVIDER_REFERENCED. Update or delete the dependent agents before removing the provider.
Admin-managed shared providers
Users with the providers permission manage providers at /api/admin/providers. Signed-in users can list those providers. They cannot create, update, delete, or test them.
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.
See the ACP integration guide for the full runner object schema and setup examples.

