For AI agents: the complete documentation index is available at /en/llms.txt, the full documentation bundle is available at /en/llms-full.txt, and this page is available as Markdown at /en/api/providers.md.
  • English
  • 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

    MethodPathAuthDescription
    GET/providersuserList providers (read-only)
    GET/providers/resolveduserList enabled models the caller may select
    GET/providers/active-modeluserGet the global default model
    PUT/providers/active-modelprovidersSet the global default model
    POST/admin/providersprovidersCreate a provider
    PATCH/admin/providers/{id}providersUpdate a provider
    DELETE/admin/providers/{id}providersDelete a provider
    POST/admin/providers/{id}/testprovidersProbe a saved provider

    Create a provider

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

    OpenAI
    Ollama (local)
    DashScope
    OpenAI
    curl -X POST http://127.0.0.1:8088/api/admin/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-..."
      }'
    NOTE

    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.

    cURL
    Response (success)
    Response (failure)
    cURL
    curl -X POST http://127.0.0.1:8088/api/admin/providers/1/test \
      -H 'Authorization: Bearer $TOKEN'

    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.

    cURL
    cURL
    curl http://127.0.0.1:8088/api/providers/resolved \
      -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. Changing it requires the providers permission.

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

    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.

    MethodPathAuthDescription
    GET/acpuserList your global runners
    PUT/acpuserReplace the global runner list
    GET/acp/{runner_name}userGet a specific runner
    PUT/acp/{runner_name}userUpsert a runner
    DELETE/acp/{runner_name}userDelete a custom runner
    GET/agents/{aid}/acpownerGlobal runners + per-agent tool-enabled flag
    PUT/agents/{aid}/acpownerUpdate tool-enabled flag and optionally the global list
    TIP

    See the ACP integration guide for the full runner object schema and setup examples.