> ## Documentation Index
> Fetch the complete documentation index at: https://hs-df36fa00.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
curl 'http://your-node:8042/v1/agents?limit=20&offset=0'
```

### Query parameters

<ParamField query="limit" type="integer">
  Number of agents to return per page. Must be between `1` and `100`. Defaults to `50`.
</ParamField>

<ParamField query="offset" type="integer">
  Zero-based index of the first record to return. Defaults to `0`.
</ParamField>

## Response

<ResponseField name="items" type="PublishedAgentRecord[]">
  Array of published agent records for the requested page.

  <Expandable title="PublishedAgentRecord fields">
    <ResponseField name="agent_id" type="string">
      Unique identifier for the agent (e.g. `"stripe-agent"`).
    </ResponseField>

    <ResponseField name="provider_id" type="string">
      Identifier of the provider that submitted this agent.
    </ResponseField>

    <ResponseField name="version" type="string">
      Semantic version string of this agent release (e.g. `"1.2.0"`).
    </ResponseField>

    <ResponseField name="status" type="string">
      One of `"approved"`, `"suspended"`, or `"revoked"`.
    </ResponseField>

    <ResponseField name="agent_card" type="object">
      Full A2A agent card object describing the agent's capabilities, skills, and security schemes.
    </ResponseField>

    <ResponseField name="deployment" type="object">
      Deployment configuration including `runtime` and `endpoint` (with `url`, `protocol_binding`, `protocol_version`, and `interaction_protocol`).
    </ResponseField>

    <ResponseField name="review" type="AgentReviewProfile">
      Review profile containing `risk_level`, `data_classes`, `destructive_actions`, `human_approval_required`, `allowed_regions`, and `cost_per_call_units`.
    </ResponseField>

    <ResponseField name="approved_at" type="string">
      ISO 8601 timestamp of when the agent was approved.
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 timestamp of the most recent update to this record.
    </ResponseField>

    <ResponseField name="reviewed_by" type="string">
      Identity of the reviewer or `"auto-approve"` for auto-approved submissions.
    </ResponseField>

    <ResponseField name="review_notes" type="string">
      Optional notes left by the reviewer.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="count" type="integer">
  Number of items returned in this page.
</ResponseField>

<ResponseField name="limit" type="integer">
  The effective page size used for this request.
</ResponseField>

<ResponseField name="offset" type="integer">
  The offset used for this request.
</ResponseField>

<ResponseField name="next_offset" type="integer">
  The offset to use in your next request to retrieve the following page. Omitted when `has_more` is `false`.
</ResponseField>

<ResponseField name="has_more" type="boolean">
  `true` if there are additional records beyond this page.
</ResponseField>

<ResponseField name="known_count" type="integer">
  Total number of published agents known to this node at the time of the query.
</ResponseField>

## Status codes

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

## Example response

```json theme={null}
{
  "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
}
```