Skip to main content
POST
Set a capability's provider chain
Sets the ordered provider chain of one capability domain, and optionally each provider’s binding options, as the Console’s capability editor does. The provider records that runtime resolution reads follow the chain: providers in it are enabled in chain order, and the domain’s other records are disabled. A pinned foundation provider (for example forge for notifications) cannot be removed and is stored at the head of the chain, but resolution orders it last. A single-provider domain uses the first enabled provider in that order, so an enabled non-pinned provider is used in place of the pinned one, and a failed call is not retried on another provider. A fan-out domain (notifications, human_interaction) calls every enabled provider, the pinned one included. An empty providers list turns off a capability that has no pinned provider; for one with a pinned provider it is refused. Switching the embeddings provider re-embeds knowledge and app vectors. The response is the chain after the write and changed, which is false (and nothing is recorded) when neither the chain nor the options changed. An option that would repoint the provider at another host (apiUrl, baseUrl, or any *Url key or URL field in the provider’s options schema) can only be set in the Console: over the API it is 400 bad_request, and the message names the option. Options never hold a secret: a secret-shaped key or value is 400 too; store a secret as a Credential on the vendor’s Connection.

Authority and retries

Requires platform:manage at the platform scope. Capability and provider configuration is deployment-wide, so a credential granted platform:manage only at an org unit is refused with 403 and nothing is written. A Forge agent can never hold platform:manage. The write is recorded in the audit log under the calling key or External App, never a person. Send an Idempotency-Key to make a retry safe. The same key and the same body within 24 hours return the recorded 200 only while you still hold platform:manage at the platform scope; otherwise the answer is 409 idempotency_result_unavailable, and the write never runs twice. The same key with a different body is 422.

Errors

Authorizations

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Headers

Idempotency-Key
string

Optional logical intent key. A same-key retry within 24 hours returns the recorded result without writing again.

Required string length: 1 - 255

Path Parameters

domain
string
required

The capability domain, as listCapabilities returns it (e.g. notifications)

Minimum string length: 1

Body

application/json

The capability domain, its ordered providers (pinned foundation providers are kept at the head and cannot be removed; an empty list turns the capability off) and optional per-provider options bags, validated against each provider's options schema. Options never hold a secret, and an option that repoints a provider at another host (apiUrl, baseUrl, any *Url) is Console-only.

providers
string[]
required

The provider keys in order. Pinned foundation providers are stored at the head but resolved last: a single-provider domain uses the first enabled non-pinned provider, and a fan-out domain calls every enabled provider. Empty turns off a capability with no pinned provider.

Minimum string length: 1
options
object

Per-provider binding options, keyed by provider key

Response

Set a capability's provider chain

data
object
required

A capability's provider chain after the write (providers, pinned foundation providers first; empty when disabled) and whether the write changed the chain or its options.

meta
object
required