> Markdown version of https://authpi.com/docs/reference/core-api/agents/ — fetch the complete AuthPI docs index at https://authpi.com/llms.txt to discover all available pages.

# Agents — AuthPI Core API

Agent identity management endpoints. Agents are non-human identities within an Issuer, used for automated processes, bots, and machine-to-machine communication. Each agent can have wallet (CAIP-2) or secret verifiers for authentication.

## GET /v1/accounts/{account_id}/issuers/{issuer_id}/agents

**List Agents**

Lists all agents for an issuer with cursor-based pagination.

Agents are non-human identities within an issuer, used for automated processes, bots, and machine-to-machine communication. Each agent can have wallet or secret verifiers for authentication.

**Filtering:**
- `status` - Filter by agent status (active, suspended, blocked)
- `model` - Filter by model name (exact match)
- `provider` - Filter by provider name (exact match)
- `has_verifiers` - Filter by whether the agent has any verifiers configured
- `limit` - Number of results per page (1-100, default 50)
- `cursor` - Cursor from previous response for next page

Each agent in the response includes a `verifiers` array listing which verifier types are configured (e.g. `["wallet", "secret"]`).

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `issuer_id` | string | Required | The unique identifier of the issuer |

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer | Optional | Maximum number of items to return (1-100, default: 50) |
| `cursor` | string | Optional | Pagination cursor from a previous response |
| `status` | active \| suspended \| blocked | Optional | Filter by agent status |
| `model` | string | Optional | Filter by model name (exact match) |
| `provider` | string | Optional | Filter by provider name (exact match) |
| `has_verifiers` | true \| false | Optional | Filter by whether the agent has any verifiers configured |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Agents retrieved successfully | `object` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |

## POST /v1/accounts/{account_id}/issuers/{issuer_id}/agents

**Create Agent**

Creates a new agent identity under an issuer.

Agents are non-human identities used for automated processes, bots, and machine-to-machine communication. After creation, add verifiers (wallet or secret) to enable authentication.

**Agent fields:**
- `name` (required) - Human-readable name for the agent
- `description` - What the agent does
- `model` - AI model identifier (e.g., "gpt-4", "claude-3")
- `provider` - Model provider (e.g., "openai", "anthropic")
- `version` - Agent version string
- `metadata` - Arbitrary key-value metadata

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `issuer_id` | string | Required | The unique identifier of the issuer |

### Request body

Content type: `application/json`

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Required | A name for the resource. |
| `description` | string \| null | Optional | A description for the resource. Markdown supported. |
| `model` | string \| null | Optional |  |
| `provider` | string \| null | Optional |  |
| `version` | string \| null | Optional |  |
| `scopes` | string[] | Optional |  |
| `metadata` | Metadata | Optional |  |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 201 | Agent created successfully | `object` |
| 400 | **Bad Request** - The request is malformed or contains invalid data. | `ApiError` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |

## GET /v1/accounts/{account_id}/issuers/{issuer_id}/agents/{agent_id}

**Get Agent**

Retrieves a single agent by ID.

Returns the agent's profile, status, and metadata. Use the agent verifiers endpoints to manage authentication credentials.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `issuer_id` | string | Required | The unique identifier of the issuer |
| `agent_id` | string | Required | The unique identifier of the agent |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Agent retrieved successfully | `object` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |

## PATCH /v1/accounts/{account_id}/issuers/{issuer_id}/agents/{agent_id}

**Update Agent**

Updates an existing agent's profile or status.

All fields are optional — only provided fields are updated. You can update the agent's name, description, model info, metadata, or status.

**Status transitions:**
- `active` → `suspended` (requires `status_reason`)
- `active` → `blocked` (requires `status_reason`)
- `suspended` → `active`

Suspended or blocked agents cannot authenticate or have verifiers modified.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `issuer_id` | string | Required | The unique identifier of the issuer |
| `agent_id` | string | Required | The unique identifier of the agent |

### Request body

Content type: `application/json`

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Optional | A name for the resource. |
| `description` | string \| null | Optional | A description for the resource. Markdown supported. |
| `model` | string \| null | Optional |  |
| `provider` | string \| null | Optional |  |
| `version` | string \| null | Optional |  |
| `status` | active \| suspended \| blocked | Optional |  |
| `status_reason` | string \| null | Optional |  |
| `scopes` | string[] | Optional |  |
| `metadata` | Metadata | Optional |  |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Agent updated successfully | `object` |
| 400 | **Bad Request** - The request is malformed or contains invalid data. | `ApiError` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |
| 412 | **Precondition Failed** - The resource has been modified since the provided ETag. | `PreconditionFailedError` |

## DELETE /v1/accounts/{account_id}/issuers/{issuer_id}/agents/{agent_id}

**Delete Agent**

Permanently deletes an agent and all its verifiers.

This action is irreversible. All associated data is removed:
- Agent profile and metadata
- All verifiers (wallet and secret)
- KV cache entries (agent and wallet reverse lookups)
- D1 listing index entry

**Before deleting:**
1. Remove the agent from any organizations it belongs to
2. Revoke any active credentials or integrations using this agent

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `issuer_id` | string | Required | The unique identifier of the issuer |
| `agent_id` | string | Required | The unique identifier of the agent |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 204 | **No Content** - The operation completed successfully with no response body. | — |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |
| 412 | **Precondition Failed** - The resource has been modified since the provided ETag. | `PreconditionFailedError` |

## GET /v1/accounts/{account_id}/issuers/{issuer_id}/agents/{agent_id}/verifiers

**List Agent Verifiers**

Lists all verifiers attached to an agent.

Returns wallet and secret verifiers. For secret verifiers, only the algorithm is shown — the hash is never exposed.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `issuer_id` | string | Required | The unique identifier of the issuer |
| `agent_id` | string | Required | The unique identifier of the agent |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Verifiers retrieved successfully | `object` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |

## POST /v1/accounts/{account_id}/issuers/{issuer_id}/agents/{agent_id}/verifiers

**Add Agent Verifier**

Adds an authentication verifier to an agent.

**Verifier types:**

- **wallet** - Links a blockchain wallet address (CAIP-2 format) for x402 payment authentication. Requires `address` and `network` fields. A KV reverse lookup is created for wallet-to-agent resolution.

- **secret** - Generates a high-entropy client secret for Client Credentials authentication. The plaintext secret is returned **once** in the response — store it securely. The secret is SHA-256 hashed before storage and cannot be retrieved again.

**Limits:** Maximum 20 verifiers per agent.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `issuer_id` | string | Required | The unique identifier of the issuer |
| `agent_id` | string | Required | The unique identifier of the agent |

### Request body

Content type: `application/json`

One of (variant 1):

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | wallet | Required |  |
| `name` | string \| null | Required | A name for the resource. |
| `address` | string | Required |  |
| `network` | string | Required |  |

One of (variant 2):

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | secret | Required |  |
| `name` | string \| null | Required | A name for the resource. |


### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 201 | Verifier added successfully | `object` |
| 400 | **Bad Request** - The request is malformed or contains invalid data. | `ApiError` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |

## DELETE /v1/accounts/{account_id}/issuers/{issuer_id}/agents/{agent_id}/verifiers/{verifier_id}

**Remove Agent Verifier**

Removes an authentication verifier from an agent.

For wallet verifiers, the KV reverse lookup entry is also cleaned up. For secret verifiers, the stored hash is deleted.

This action is immediate and irreversible.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `issuer_id` | string | Required | The unique identifier of the issuer |
| `agent_id` | string | Required | The unique identifier of the agent |
| `verifier_id` | string | Required | The unique identifier of the verifier |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 204 | **No Content** - The operation completed successfully with no response body. | — |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |