Capabilities

The contract modelCopy Anchor Link

Every capability is declared once, in the platform contract registry. A declaration says:

• The capability's name (for example, list_workspace_memories)
• Its input and output schemas (Zod)
• The surfaces it is on: api, mcp, agent, and cli, in any combination
• Its risk level, and whether a person must approve it before the in-app agent runs it
• Its default IAM roles and effects

The registry is the one source of truth. Every API route and every MCP tool reads from it, so a capability behaves the same way on every surface it declares. A capability is reachable only on the surfaces its contract lists.

Capability namingCopy Anchor Link

A capability name is verb first, snake_case: an imperative verb, then the thing it acts on, joined by underscores. Two or three words is the norm. A fourth appears only when it is the one way to keep the name unique.

Names are unique across the registry, and a capability's name is the same string everywhere: REST route dispatch, MCP tool name, model-facing tool name, IAM grants, audit records, and metering. There is no separate model-facing spelling.

Names are stable, and there is no alias layer. If a capability is renamed, the old name stops resolving. The registry carries no compatibility alias, so a rename is a breaking change. Check the current contract and release notes before upgrading.

Capability listCopy Anchor Link

Two read routes return the registry itself. Neither uses credits.

The list gives each capability's name, domain, description, mode, surfaces, sensitivity, default role grants, plugin gate, and agent approval metadata, with total and hasMore for paging. get_capability_registry adds the top-level input and output fields, and returns capability: null for a name the registry does not hold.

An organization Owner, a member with the Compliance and Billing role, or a workspace Admin can read the registry. An ordinary API key acts as a Member, so it gets 403. Read it from a signed-in session, or from an oxagen login CLI session of a person who holds one of those roles.

An MCP client's tools/list response describes the tools that server exposes. Use the returned schemas instead of assuming API, MCP, and agent expose identical sets. Capability registry explains each field a contract declares.

REST route conventionCopy Anchor Link

Each capability's path is chosen for it, not derived from the name. For example, list_agent_tools is mounted at POST /v1/{orgSlug}/{workspaceSlug}/agent/tools and revoke_api_key at DELETE /v1/{orgSlug}/{workspaceSlug}/api-keys/revoke.

• Most capability routes sit under /v1/{orgSlug}/{workspaceSlug}/. Use the org and workspace your API key belongs to, by slug or ID. A few routes act on the organization and name no workspace, such as POST /v1/{orgSlug}/workspaces (create_workspace) and POST /v1/{orgSlug}/audit/events/export (export_audit_events).
• Most capability routes are POST, including many that only read. The JSON request body is the capability's input. Send {} when there is nothing to pass.
• A GET route takes its input as query parameters, such as GET /v1/{orgSlug}/{workspaceSlug}/api-keys?scopeKind=workspace for list_api_keys.

Browser flowsCopy Anchor Link

Some operations need a browser redirect or a live approval interaction in addition to a capability call. Read the operation's contract and route reference. The presence of an API route does not imply an identical MCP interaction.