Skip to main content
The Capabilities domain shows how the deployment is wired: which capability domains (inference, embeddings, notifications and the rest) are on, which providers each one dispatches to, whether those providers’ credentials resolve, and what changed recently. Use it to check a deployment before you rely on a capability, or to report a broken provider credential. With platform:manage you can also change it as the Console does: set a capability’s chain, turn a capability off, set a provider’s options, enable or disable a provider, add a provider record, and bind an org unit to a provider. Options that repoint a provider at another host stay Console-only.

Who can read it

The five catalog reads (listCapabilities, getCapability, listCapabilityAuditEvents, listProviders, getProvider) require grants:read, policies:read and audit:read (the Governance reader preset). Capabilities and providers are deployment configuration, not tenant data, so the three permissions must be held at the deployment root: a platform grant, or a grant at the root org unit. A credential granted only at a tenant org unit gets 403 permission_denied with error.requiredPermission, and the refusal is recorded like any other permission denial. Migrated API keys carry a root-org-unit grant and are unaffected. listProviderAuditEvents requires audit:read alone, at the platform scope; getCapabilityBindingReadiness requires credentials:read at the org unit it names (a grant at the platform, an ancestor or the unit).

Resource shapes

Credential health

CredentialHealth describes one connection target (<vendor>/<connection>), such as openai/inference: Health is credential resolution and last verification only. There is no runtime health probe, so an ok verification is not a promise that the next call succeeds. An invalid or unreachable status is the signal that a credential needs attention. A platform API key or a Personal key administers Credentials through the Connections administration routes; an External App is refused with 403. POST /api/v3/connection-credentials/provision creates a vendor connection’s Credential, or rotates it in place, with credentials:write. POST /api/v3/connection-credentials/{credentialId}/approve approves a pending one with credentials:approve. POST /api/v3/connection-credentials/{credentialId}/revoke revokes one and POST /api/v3/connection-credentials/{credentialId}/set-sharing seals or shares one, each with credentials:manage. Each of these needs its permission at platform scope. The Capabilities reads answer the handoff, never the credential identity or secret.

What is never returned

Credential values, credential ids, credential scopes and names, field names, env-var names, deployment and per-binding option values, provider icons and custom renderer slugs are not on the wire. Capability and provider audit events omit the actor and the change detail, which stay in the Console.

Operations

Reads:
  • GET /api/v3/capabilities — listCapabilities — every capability domain
  • GET /api/v3/capabilities/{domain} — getCapability — one domain with provider health
  • GET /api/v3/capabilities/{domain}/audit-events?limit= — listCapabilityAuditEvents — a domain’s recent changes
  • GET /api/v3/providers — listProviders — the provider catalog
  • GET /api/v3/providers/{providerKey} — getProvider — one provider with credential health
  • GET /api/v3/providers/{providerKey}/audit-events?limit= — listProviderAuditEvents — a provider’s recent changes (audit:read at the platform scope)
  • GET /api/v3/capabilities/{domain}/binding-readiness?orgUnitId= — getCapabilityBindingReadiness — a capability’s provider binding for one org unit (credentials:read at the unit)
Writes (platform:manage, each idempotent with an Idempotency-Key):
  • POST /api/v3/capabilities/{domain}/set-chain — setCapabilityChain — a domain’s provider chain and binding options
  • POST /api/v3/capabilities/{domain}/disable — disableCapability — turn a domain off
  • POST /api/v3/providers/{providerKey}/set-options — setProviderOptions — a provider’s global options
  • POST /api/v3/providers/{providerKey}/enable — enableProvider — a provider and its chained records on
  • POST /api/v3/providers/{providerKey}/disable — disableProvider — a provider and its records off
  • POST /api/v3/provider-records — createProviderRecord — a protocol-generic provider record
  • POST /api/v3/capabilities/{domain}/bind-organization — bindCapabilityOrganization — an org unit’s provider binding (platform:manage at the unit)
The two lists are the fixed domain inventory and the static provider catalog, each bounded (at most 32 rows) and answered whole: meta.hasMore is false and there is no cursor. A missing domain or key is 400 bad_request; an unknown one is 404 resource_missing.

Common workflows

  • Governance — the other reads that require grants:read, policies:read and audit:read
  • MCP server — forge_call_operation with operationId listCapabilities, getCapability, listCapabilityAuditEvents, listProviders or getProvider