> For AI agents: the complete documentation index is available at /en/llms.txt, the full documentation bundle is available at /en/llms-full.txt.

# 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

| Method   | Path                         | Auth        | Description                               |
| -------- | ---------------------------- | ----------- | ----------------------------------------- |
| `GET`    | `/providers`                 | user        | List providers (read-only)                |
| `GET`    | `/providers/resolved`        | user        | List enabled models the caller may select |
| `GET`    | `/providers/active-model`    | user        | Get the global default model              |
| `PUT`    | `/providers/active-model`    | `providers` | Set the global default model              |
| `POST`   | `/admin/providers`           | `providers` | Create a provider                         |
| `PATCH`  | `/admin/providers/{id}`      | `providers` | Update a provider                         |
| `DELETE` | `/admin/providers/{id}`      | `providers` | Delete a provider                         |
| `POST`   | `/admin/providers/{id}/test` | `providers` | Probe a saved provider                    |

## Create a provider

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


```bash 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-..."
  }'
```
```bash Ollama (local)
curl -X POST http://127.0.0.1:8088/api/admin/providers \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "local-ollama",
    "kind": "ollama",
    "base_url": "http://127.0.0.1:11434"
  }'
```
```bash DashScope
curl -X POST http://127.0.0.1:8088/api/admin/providers \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "dashscope",
    "kind": "dashscope",
    "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.


```bash cURL
curl -X POST http://127.0.0.1:8088/api/admin/providers/1/test \
  -H 'Authorization: Bearer $TOKEN'
```
```json Response (success)
{"ok": true, "latency_ms": 312}
```
```json Response (failure)
{"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 /providers/resolved` returns the enabled models the caller may select. Each item includes `provider_name` and `model`.


```bash 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.


```bash 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.

| Method   | Path                 | Auth  | Description                                             |
| -------- | -------------------- | ----- | ------------------------------------------------------- |
| `GET`    | `/acp`               | user  | List your global runners                                |
| `PUT`    | `/acp`               | user  | Replace the global runner list                          |
| `GET`    | `/acp/{runner_name}` | user  | Get a specific runner                                   |
| `PUT`    | `/acp/{runner_name}` | user  | Upsert a runner                                         |
| `DELETE` | `/acp/{runner_name}` | user  | Delete a custom runner                                  |
| `GET`    | `/agents/{aid}/acp`  | owner | Global runners + per-agent tool-enabled flag            |
| `PUT`    | `/agents/{aid}/acp`  | owner | Update tool-enabled flag and optionally the global list |


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

