> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Capabilities

> Read and configure the deployment's capability domains, their provider chains, the provider catalog, credential health, org bindings and recent capability changes.

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

| Schema | Returned by | Contents |
| - | - | - |
| `CapabilitySummary` | `listCapabilities` | `domain`, `label`, `description`, `status` (`off`, `internal` or `external`), `mode` (`single` or `fanout`), `registeredProviders`, `configuredProviders` (the active chain, in dispatch order) and `primaryProvider` (`{ key, label }`, or `null` when the chain is empty). |
| `CapabilityDetail` | `getCapability` | A `CapabilitySummary` plus `fanoutEligible`, `availableProviders` (`key`, `label`, `vendor`, `kind`, `isStateless`, `isCtx`, `pinned`) and `providerHealth`: one `{ providerKey, credentialHealth }` per provider in the active chain. |
| `ProviderSummary` | `listProviders` | `key`, `label`, `description`, `vendor`, optional `vendorUrl` and `docsUrl`, `kind`, `enabled` and `capabilitiesServed` (`domain`, `label`, `pinned`, `state`). |
| `ProviderDetail` | `getProvider` | A `ProviderSummary` plus `usedBy` (`domain`, `label`, `role`, `mode`) and `credentialHealth`, one per connection target. |
| `CapabilityAuditEvent` | `listCapabilityAuditEvents` | `id`, `event`, `category` (or `null`) and `timestamp`. |
| `ProviderAuditEvent` | `listProviderAuditEvents` | `id`, `event`, `category` (or `null`) and `timestamp`. |
| `CapabilityBindingReadiness` | `getCapabilityBindingReadiness` | `orgUnitId`, `organizationName`, optional `bindingProviderKey` (the unit's own binding), `providers` (`providerKey`, `enabled`, optional `target`, `credentialReady`) and, for `typed_judgments`, `readiness` (`ready`, `reason`, optional `providerKey`). |

### Credential health

`CredentialHealth` describes one connection target (`<vendor>/<connection>`), such as `openai/inference`:

| Field | Meaning |
| - | - |
| `resolved` | `true` when the credential resolver finds an approved, unexpired credential for the target at the deployment scope — the scope a provider resolves at when no run names an organization. A credential homed at one organization counts in `approvedCount` but does not make the deployment's connection resolve. |
| `approvedCount`, `pendingCount`, `inactiveCount` | Credentials by state; expired, `rejected` and `revoked` credentials count as inactive. |
| `lastVerificationStatus` | `ok`, `invalid` or `unreachable` from the most recently verified credential, or `null` when none was ever verified. |
| `lastVerifiedAt` | When that verification ran, in epoch milliseconds, or `null`. |
| `handoff` | The person action and Console page that resolves the connection: approve a pending credential, connect one when none is pending, or rotate one whose last verification is `invalid`; `null` when no action is needed. |

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](https://docs.gloo.com/forge/reference/http-api/connections-credentials) 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](https://docs.gloo.com/forge/reference/http-api/capabilities/list.md) — every capability domain
* `GET /api/v3/capabilities/{domain}` — [getCapability](https://docs.gloo.com/forge/reference/http-api/capabilities/get.md) — one domain with provider health
* `GET /api/v3/capabilities/{domain}/audit-events?limit=` — [listCapabilityAuditEvents](https://docs.gloo.com/forge/reference/http-api/capabilities/listAuditEvents.md) — a domain's recent changes
* `GET /api/v3/providers` — [listProviders](https://docs.gloo.com/forge/reference/http-api/providers/list.md) — the provider catalog
* `GET /api/v3/providers/{providerKey}` — [getProvider](https://docs.gloo.com/forge/reference/http-api/providers/get.md) — one provider with credential health
* `GET /api/v3/providers/{providerKey}/audit-events?limit=` — [listProviderAuditEvents](https://docs.gloo.com/forge/reference/http-api/providers/listAuditEvents.md) — a provider's recent changes (`audit:read` at the platform scope)
* `GET /api/v3/capabilities/{domain}/binding-readiness?orgUnitId=` — [getCapabilityBindingReadiness](https://docs.gloo.com/forge/reference/http-api/capabilities/getBindingReadiness.md) — 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](https://docs.gloo.com/forge/reference/http-api/capabilities/setChain.md) — a domain's provider chain and binding options
* `POST /api/v3/capabilities/{domain}/disable` — [disableCapability](https://docs.gloo.com/forge/reference/http-api/capabilities/disable.md) — turn a domain off
* `POST /api/v3/providers/{providerKey}/set-options` — [setProviderOptions](https://docs.gloo.com/forge/reference/http-api/providers/setOptions.md) — a provider's global options
* `POST /api/v3/providers/{providerKey}/enable` — [enableProvider](https://docs.gloo.com/forge/reference/http-api/providers/enable.md) — a provider and its chained records on
* `POST /api/v3/providers/{providerKey}/disable` — [disableProvider](https://docs.gloo.com/forge/reference/http-api/providers/disable.md) — a provider and its records off
* `POST /api/v3/provider-records` — [createProviderRecord](https://docs.gloo.com/forge/reference/http-api/providers/createRecord.md) — a protocol-generic provider record
* `POST /api/v3/capabilities/{domain}/bind-organization` — [bindCapabilityOrganization](https://docs.gloo.com/forge/reference/http-api/capabilities/bindOrganization.md) — 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

```bash theme={null}
curl "$FORGE_BASE/api/v3/capabilities/inference" \
  -H "Authorization: Bearer $FORGE_TOKEN"
```

## Related

* [Governance](https://docs.gloo.com/forge/reference/http-api/governance) — the other reads that require `grants:read`, `policies:read` and `audit:read`
* [MCP server](https://docs.gloo.com/forge/reference/mcp-server.md) — `forge_call_operation` with operationId `listCapabilities`, `getCapability`, `listCapabilityAuditEvents`, `listProviders` or `getProvider`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.