Agents

List visible agents

Changed on

List the agents the caller can see, newest first.

Visibility is scoped to the caller: org:admin sees every agent; anyone else sees the agents they own. An agent caller also sees itself, and with owner:agents:read its owner's agents. Filter by lifecycle status (pending, active, rejected, disabled, archived). Results are cursor-paginated: pass next_cursor from the previous page as cursor while has_more is true.

get/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)

Query parameters

cursorstring nullable

Cursor from a previous page's next_cursor; omit for the first page.

Example:eyJ0IjogIjIwMjYtMDEtMTVUMDk6MzA6MDArMDA6MDAiLCAiaWQiOiAiM2YyYjhjMWUtN2Q0YS00ZTliLWE2YzUtMWQyZTNmNGE1YjZjIn0=
limitinteger

Maximum number of agents to return (1-200, default 50).

Example:25
statusstring nullable

Only return agents in this lifecycle status: pending, active, rejected, disabled or archived.

Example:active

Response

Successful Response

has_moreboolean required

Whether more results exist after this page.

next_cursorstring nullable

Cursor for the next page; null when there are no more results.

Example response

{
  "data": [
    {
      "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"
    }
  ],
  "has_more": true,
  "next_cursor": "eyJ0IjogIjIwMjYtMDEtMTVUMDk6MzA6MDArMDA6MDAiLCAiaWQiOiAiM2YyYjhjMWUtN2Q0YS00ZTliLWE2YzUtMWQyZTNmNGE1YjZjIn0="
}

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

    • warning

      deleted the query request parameter view

    • info

      api operation id list_agents_agents_get removed and replaced with listAgents

    • 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

      added the new optional query request parameter cursor

    • info

      added the new optional query request parameter limit

    • 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

      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