Create a persisted declarative capability.

POST

/v1/capabilities

• Production API

Request Body ^required

object

definition

required

Definition for the new declarative capability. name must be unique per org and becomes the canonical declarative:<name> capability ref.

object

Responses

201

Declarative capability created. Response id uses cap_<32-hex>; capability_id uses declarative:<unique_name>.

Wrapper that adds API and UI links to a serialized resource.

Uses self_url (not url) for the API link to avoid collision with resources that already have a url field (e.g. McpServer).

object

archived_at

string | null format: date-time

capability_id

required

Runtime capability reference. Agents and harnesses may use this or the plain unique name.

string

Example

declarative:research_pack

created_at

required

string format: date-time

definition

required

Declarative capability payload: system prompt, skills, starter files, MCP servers, and metadata.

object

deleted_at

string | null format: date-time

description

required

Short summary shown in pickers, search results, and API listings.

string

Example

Adds research instructions, starter files, and MCP tools.

display_name

Human-facing label shown in the UI. Defaults to name when omitted.

string | null

Example

Research Pack

id

required

Public resource ID for this persisted declarative capability.

string

Example

cap_01933b5a000070008000000000000001

name

required

Stable unique name used in capability refs. Lowercase letters, numbers, and underscores.

string

Example

research_pack

status

required

Lifecycle state for the resource: active, disabled, archived, or deleted.

string

Example

active

updated_at

required

string format: date-time

self_url

required

Full API endpoint URL for this resource.

string

ui_link

required

Alias for view_url, used by command and MCP outputs.

string

view_url

required

Full UI URL for viewing this resource.

string

400

Invalid declarative capability definition, name, limits, file mount, skill, or MCP server configuration.

Standard error response for API endpoints.

object

error

required

Error message describing what went wrong.

string

409

A declarative capability with the same unique name already exists.

Standard error response for API endpoints.

object

error

required

Error message describing what went wrong.

string