Agents

Deny Agent

Changed on

Deny a pending agent.

Same authorization as approve: the agent's owner or an org:admin, and only an org:admin for an agent with no owner. Any other caller gets a 404.

post/agents/{agent_id}:deny

Request

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

Path parameters

agent_idstring required

ID of the agent.

Example:agnt_6968b3984d1c238dbe7e2e29

Request body

reasonstring required

Why the agent is being denied.

Example request

{
  "reason": "Requested permissions exceed the agent's stated purpose."
}

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