> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getpioneer.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Providers API

> Listing workspace providers, listing provider models, and managing workspace-scoped API keys through the gateway.

Provider methods are deliberately small. The gateway owns API provider configuration, stores credentials in its keystore, discovers models, and normalizes model metadata for clients. Configuration is workspace-scoped: every provider method takes `workspace_id`, and API keys use workspace-specific secret ids. Clients do not need to contact each model provider directly to build a model picker.

CLI-backed agent runtimes are not provider adapters. Use [CLI Runtime API](/protocol/cli-runtime) for runtime listing, runtime model catalogs, approvals, and `cliAgentRuntime` turn execution.

Use these methods when a client needs to show available providers for a workspace, fetch model catalogs, or update the API key used by that workspace.

## Methods

| Method                               | Params                       | Result                         | Purpose                                                      |
| ------------------------------------ | ---------------------------- | ------------------------------ | ------------------------------------------------------------ |
| `provider/list`                      | `ProviderListParams`         | `ProviderListResponse`         | Return configured provider adapters for a workspace.         |
| `provider/models/list`               | `ProviderListModelsParams`   | `ProviderListModelsResponse`   | Return models known for one provider in a workspace.         |
| `provider/embedding_models/list`     | `ProviderListModelsParams`   | `ProviderListModelsResponse`   | Return embedding models supported by one provider.           |
| `provider/transcription_models/list` | `ProviderListModelsParams`   | `ProviderListModelsResponse`   | Return transcription models supported by one provider.       |
| `provider/configure`                 | `ProviderConfigureParams`    | `ProviderConfigureResponse`    | Update a provider API key and/or its workspace-scoped proxy. |
| `provider/set_api_key`               | `ProviderSetApiKeyParams`    | `ProviderSetApiKeyResponse`    | Store or replace a workspace provider API key.               |
| `provider/delete_api_key`            | `ProviderDeleteApiKeyParams` | `ProviderDeleteApiKeyResponse` | Remove a workspace provider API key.                         |

## Listing providers

`provider/list` requires the workspace id because provider configuration belongs to a workspace on the gateway.

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": "aaaaaaaaaaaaaaaaaaaaa",
  "method": "provider/list",
  "params": {
    "workspace_id": "ws_000000000000000001"
  }
}
```

Response:

```json theme={null}
{
  "providers": [
    { "name": "openai" },
    { "name": "anthropic" },
    { "name": "openrouter" },
    { "name": "ollama" }
  ]
}
```

The `name` is the stable provider identifier used in `model_provider`, `provider/models/list`, and provider configuration methods. `proxy_url`, when present, is the gateway-side network route for that provider; clients should display it as configuration state, not as a secret-bearing URL.

## Listing models

Use `provider/models/list` after the user selects a provider. The gateway returns normalized metadata that a client can use for filtering, badges, warnings, or default selection.

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": "bbbbbbbbbbbbbbbbbbbbb",
  "method": "provider/models/list",
  "params": {
    "workspace_id": "ws_000000000000000001",
    "provider": "openai"
  }
}
```

Response shape:

```json theme={null}
{
  "provider": "openai",
  "models": [
    {
      "id": "gpt-5.1",
      "name": "GPT-5.1",
      "description": null,
      "created": null,
      "provider": "openai",
      "owned_by": null,
      "limits": {
        "max_input_tokens": null,
        "max_output_tokens": null,
        "context_window": null
      },
      "capabilities": {
        "vision": true,
        "tool_calling": true,
        "json_output": true,
        "streaming": true,
        "thinking": true,
        "reasoning": {
          "supported": true,
          "effort_options": ["low", "medium", "high"],
          "default_effort": "medium",
          "mandatory": false,
          "supports_token_budget": true,
          "source": "provider_metadata"
        },
        "fine_tuning": null,
        "input_modalities": ["text", "image"],
        "output_modalities": ["text"]
      },
      "pricing": null,
      "active": true,
      "family": "gpt",
      "lifecycle_status": null
    }
  ]
}
```

Model metadata is advisory. Providers differ in how much information they expose, so clients must tolerate `null` for limits, pricing, lifecycle state, and individual capabilities.

Embedding and transcription catalogs use the same normalized model shape, but are separate methods because these models serve gateway services rather than ordinary chat selection. Use the embedding catalog for thread-context/vector-search configuration and the transcription catalog for voice input settings.

## Model metadata

`ProviderModelInfo` is the normalized model object.

| Field              | Meaning                                        |
| ------------------ | ---------------------------------------------- |
| `id`               | Provider model id. Send this value as `model`. |
| `name`             | Optional display name.                         |
| `description`      | Optional model description.                    |
| `created`          | Optional provider-created timestamp.           |
| `provider`         | Provider id that owns the model entry.         |
| `owned_by`         | Optional provider owner string.                |
| `limits`           | Optional input/output/context-window limits.   |
| `capabilities`     | Optional capability flags and modality lists.  |
| `pricing`          | Optional token/image/request pricing metadata. |
| `active`           | Whether the model should be treated as active. |
| `family`           | Optional family/group label.                   |
| `lifecycle_status` | Optional provider-specific lifecycle marker.   |

Clients should select by `id`, display `name` when present, and tolerate metadata fields that are `null`.

## Reasoning metadata

`ProviderModelCapabilities.reasoning` describes model-level reasoning controls when the provider or runtime can report them.

| Field                   | Meaning                                                                                                   |
| ----------------------- | --------------------------------------------------------------------------------------------------------- |
| `supported`             | Whether reasoning/effort control is supported. `null` means unknown.                                      |
| `effort_options`        | Canonical effort values the UI may offer, such as `low`, `medium`, or `high`.                             |
| `default_effort`        | Provider/runtime default when known.                                                                      |
| `mandatory`             | Whether a client should choose an effort explicitly.                                                      |
| `supports_token_budget` | Whether a separate reasoning token budget is supported.                                                   |
| `source`                | Metadata source: `provider_metadata`, `cli_metadata`, `static_registry`, `config_override`, or `unknown`. |

Shared client helpers normalize effort labels and order known values for model selectors. Clients should only show a reasoning effort picker when `supported` is true and `effort_options` is non-empty. If the user changes provider or model, clear the selected effort unless a resolved thread selection explicitly carries one.

## Setting an API key

API keys are stored in the gateway keystore under the workspace id and provider name. If the desktop app connects to a remote gateway, the key is stored on that remote gateway, not in the desktop process.

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": "ccccccccccccccccccccc",
  "method": "provider/set_api_key",
  "params": {
    "workspace_id": "ws_000000000000000001",
    "provider": "anthropic",
    "api_key": "sk-ant-..."
  }
}
```

Response:

```json theme={null}
{
  "provider": "anthropic",
  "updated": true
}
```

After updating a key, clients usually refresh `provider/models/list` for that provider because a newly valid credential can change what the gateway can discover.

## Configuring a provider proxy

`provider/configure` can update a workspace provider proxy without changing its API key. Pioneer validates HTTP and SOCKS proxy URLs before storing them in the gateway keystore. The proxy is applied by the gateway when it creates the provider HTTP client, so it affects model discovery and provider requests from that gateway.

Send `clear_proxy: true` to remove the proxy. Do not send `proxy_url` and `clear_proxy` together. The response reports whether the proxy changed or was deleted and returns the current URL when one is configured.

## Deleting an API key

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": "ddddddddddddddddddddd",
  "method": "provider/delete_api_key",
  "params": {
    "workspace_id": "ws_000000000000000001",
    "provider": "anthropic"
  }
}
```

Response:

```json theme={null}
{
  "provider": "anthropic",
  "deleted": true
}
```

Deleting a key does not delete threads or turns that already used that provider. It only affects future provider calls and model discovery in that workspace.

## Client behavior

Provider setup is workspace-local inside a gateway. A client connected to three gateways should show provider status for the selected workspace on the selected gateway, because each workspace may have different keys and each gateway may have different local runtime availability and network access.

For ordinary API-provider thread creation and turn execution, pass the selected provider id through `model_provider` and the selected model id through `model`. For CLI-backed turns, pass the selected runtime through `execution_backend` instead. See [Threads API](/protocol/threads), [Turns API](/protocol/turns), and [CLI Runtime API](/protocol/cli-runtime).

When a client has a selected reasoning effort, include it in the thread or turn model selection path that supports reasoning effort. Do not invent effort values: use the canonical values returned in model metadata or normalized by shared client helpers.