Agents

Get an agent

Changed on

Get one agent's profile and lifecycle state.

Returns the agent's name, description, owner, status, approval or denial details, and whether it currently has an API key (has_api_key). Readable by the agent itself, its owner, and org:admin; an agent outside the caller's visibility answers 404.

get/agents/{agent_id}

Request

  • Base URL: / (relative, and the document was published on a file host, not at the API’s origin)
  • URL: /agents/{agent_id}
  • 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

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.

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

  • c516481e6ed8Revision changes
    • info

      the endpoint scheme security OAuth2 was added to the API

  • d65fcba0d25aRevision changes
    • breaking

      the response's body type changed from no type to object for status

    • breaking

      the response's property type changed from array to string for status

    • info

      api operation id get_agent_agents__agent_id__get removed and replaced with getAgent

    • info

      the endpoint scheme security BearerAuth was added to the API

    • info

      the endpoint scheme security HumanLogin was removed from the API

    • info

      api tag Agents added

    • info

      api tag agents removed

    • info

      media type application/json was changed to a more specific media type application/problem+json for the response status

    • info

      media type application/json was changed to a more specific media type application/problem+json for the response status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      removed the non-success response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      the response property became required for the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status