Skip to main content
POST
Turn a capability off
Turns one capability domain off: its chain becomes empty and its provider records are disabled, so nothing resolves for it. Per-provider options are kept, so setting a chain again restores them. A capability that is already off answers changed: false and records nothing. A domain with a pinned foundation provider cannot be turned off.

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

Response

Turn a capability off

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