Paginated List of Published Agents — GET /v1/agents

Retrieve a paginated list of published agents. Supports limit and offset query parameters. Returns items, count, next_offset, has_more.

Returns a paginated list of all published agents on this node. Only agents with an approved, suspended, or revoked status appear here — draft and in-review submissions do not.

Request

curl 'http://your-node:8042/v1/agents?limit=20&offset=0'

Query parameters

limit · integer

Number of agents to return per page. Must be between 1 and 100. Defaults to 50.

offset · integer

Zero-based index of the first record to return. Defaults to 0.

Response

items · PublishedAgentRecord[]

Array of published agent records for the requested page.

Show PublishedAgentRecord fields

agent_id · string

Unique identifier for the agent (e.g. "stripe-agent").

provider_id · string

Identifier of the provider that submitted this agent.

version · string

Semantic version string of this agent release (e.g. "1.2.0").

status · string

One of "approved", "suspended", or "revoked".

agent_card · object

Full A2A agent card object describing the agent’s capabilities, skills, and security schemes.

deployment · object

Deployment configuration including runtime and endpoint (with url, protocol_binding, protocol_version, and interaction_protocol).

review · AgentReviewProfile

Review profile containing risk_level, data_classes, destructive_actions, human_approval_required, allowed_regions, and cost_per_call_units.

approved_at · string

ISO 8601 timestamp of when the agent was approved.

updated_at · string

ISO 8601 timestamp of the most recent update to this record.

reviewed_by · string

Identity of the reviewer or "auto-approve" for auto-approved submissions.

review_notes · string

Optional notes left by the reviewer.

count · integer

Number of items returned in this page.

limit · integer

The effective page size used for this request.

offset · integer

The offset used for this request.

next_offset · integer

The offset to use in your next request to retrieve the following page. Omitted when has_more is false.

has_more · boolean

true if there are additional records beyond this page.

known_count · integer

Total number of published agents known to this node at the time of the query.

Status codes

Code	Meaning
200 OK	Request succeeded. Returns the paginated result. The items array is empty when no agents are published.

Example response

{
  "items": [
    {
      "agent_id": "stripe-agent",
      "provider_id": "acme-labs",
      "version": "1.2.0",
      "status": "approved",
      "agent_card": {
        "name": "Stripe Agent",
        "description": "Handles Stripe payment flows",
        "url": "https://stripe-agent.example.com",
        "preferredTransport": "JSONRPC",
        "protocolVersion": "1.0",
        "supportsTask": false,
        "skills": [
          { "id": "payments.create_link", "name": "Create Payment Link" }
        ],
        "securitySchemes": { "oauth2": { "type": "oauth2" } },
        "security": [{ "oauth2": ["payments:write"] }]
      },
      "deployment": {
        "runtime": "remote_http",
        "endpoint": {
          "url": "https://stripe-agent.example.com/a2a",
          "protocol_binding": "JSONRPC",
          "protocol_version": "1.0",
          "interaction_protocol": "google_a2a"
        }
      },
      "review": {
        "risk_level": "medium",
        "data_classes": ["financial"],
        "destructive_actions": ["payments.refund"],
        "human_approval_required": true,
        "allowed_regions": ["AU", "US"],
        "cost_per_call_units": 10
      },
      "approved_at": "2025-01-16T08:00:00Z",
      "updated_at": "2025-01-16T08:00:00Z",
      "reviewed_by": "auto-approve"
    }
  ],
  "count": 1,
  "limit": 20,
  "offset": 0,
  "has_more": false,
  "known_count": 1
}