Set a capability's provider chain
Sets the ordered provider chain of a capability domain and, optionally, each provider’s binding options, as the Console’s capability editor does. Requires permission platform:manage at the platform scope.
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
Requiresplatform: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
Headers
Path Parameters
Body
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.
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.
1
