Agents

Create an agent

Changed on

Create an agent owned by the caller.

The agent is active immediately and owned by the caller. Supply name (required), an optional description, and optional permissions. When permissions is omitted the agent gets the default agent permission set. When supplied, every permission must be one the caller may grant (see grantable_by_caller on GET /permissions); otherwise the request fails with 403 (agent_permission_not_grantable). Returns the created agent.

The agent has no way to authenticate yet. Follow up with POST /agents/{agent_id}:generate-api-key (or PUT /agents/{agent_id}/jwks for JWT-bearer), and bind credentials with POST /agents/{agent_id}/credentials.

post/agents

Request

  • Base URL: / (relative, and the document was published on a file host, not at the API’s origin)
  • URL: /agents
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL /authorize, token URL /oauth/token)

Request body

descriptionstring nullable

Optional free-text description of the agent.

namestring required

Human-readable name of the agent.

permissionsstring[] nullable

Permissions to grant the agent; each must be grantable by the caller. Omit to grant the default agent permission set.

Example request

{
  "description": "Reconciles Stripe invoices against the ledger every night.",
  "name": "invoice-reconciler",
  "permissions": [
    "apis:read",
    "capabilities:execute"
  ]
}

Response

Successful Response

approved_atstring date-time nullable

When the agent was approved (RFC 3339); null if not approved.

approved_bystring nullable

ID of the user who approved the agent; null if not approved.

created_atstring date-time required

When the agent was created (RFC 3339).

denial_reasonstring nullable

Reason given when the agent was denied; null if not denied.

denied_bystring nullable

ID of the actor that denied the agent; null if not denied.

descriptionstring nullable

Free-text description of the agent; null if not set.

has_api_keyboolean

Whether the agent currently has an active API key; only populated by GET /agents/{agent_id}, and false in other responses.

idstring required

Unique ID of the agent.

namestring required

Human-readable name of the agent.

owner_idstring nullable

ID of the user who owns the agent; null for an unclaimed self-registration.

parent_agent_idstring nullable

ID of the parent agent; null when the agent has no parent.

registered_bystring required

ID of the actor that registered the agent, or self for a self-registration.

statusstring required

Lifecycle status of the agent: pending, active, rejected, disabled or archived.

Example response

{
  "approved_at": "2026-01-15T09:45:00Z",
  "approved_by": "usr_6968b3987ee4c3ec0b4ee3b9",
  "created_at": "2026-01-15T09:30:00Z",
  "denial_reason": "Requested permissions exceed the agent's stated purpose.",
  "denied_by": "usr_6968b3987ee4c3ec0b4ee3b9",
  "description": "Reconciles Stripe invoices against the ledger every night.",
  "has_api_key": true,
  "id": "agnt_6968b3984d1c238dbe7e2e29",
  "name": "invoice-reconciler",
  "owner_id": "usr_6968b3987ee4c3ec0b4ee3b9",
  "parent_agent_id": "agnt_6968b3984d1c238dbe7e2e29",
  "registered_by": "usr_6968b3987ee4c3ec0b4ee3b9",
  "status": "active"
}

Changes