Providers API

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

{
  "jsonrpc": "2.0",
  "id": "aaaaaaaaaaaaaaaaaaaaa",
  "method": "provider/list",
  "params": {
    "workspace_id": "ws_000000000000000001"
  }
}

Response:

{
  "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.

{
  "jsonrpc": "2.0",
  "id": "bbbbbbbbbbbbbbbbbbbbb",
  "method": "provider/models/list",
  "params": {
    "workspace_id": "ws_000000000000000001",
    "provider": "openai"
  }
}

Response shape:

{
  "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.

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

Response:

{
  "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

{
  "jsonrpc": "2.0",
  "id": "ddddddddddddddddddddd",
  "method": "provider/delete_api_key",
  "params": {
    "workspace_id": "ws_000000000000000001",
    "provider": "anthropic"
  }
}

Response:

{
  "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, Turns API, and CLI Runtime API. 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.

Introduction

Workspace & Threads

Features

Methods

Listing providers

Listing models

Model metadata

Reasoning metadata

Setting an API key

Configuring a provider proxy

Deleting an API key

Client behavior

​Methods

​Listing providers

​Listing models

​Model metadata

​Reasoning metadata

​Setting an API key

​Configuring a provider proxy

​Deleting an API key

​Client behavior

Methods

Listing providers

Listing models

Model metadata

Reasoning metadata

Setting an API key

Configuring a provider proxy

Deleting an API key

Client behavior