---
title: Agents
description: Generated HTTP reference for the 4 operations the published OpenAPI document describes under agents.
---

# Agents

This page is generated from the published OpenAPI document. It is complete with respect to that document and says nothing about surfaces the document does not describe yet. See [what is generated here](/docs/api/reference) for what that means.

Base URL: `https://api.codespar.dev`

Every operation below requires a Bearer token. See [Authentication](/docs/concepts/authentication).

### POST `/v1/agents`

Register an agent identity and mint its first signing key

**Request body**

| Field | Type | Required | Description |
|---|---|---|---|
| `agent_id` | `string` | yes | — |
| `display_name` | `string` | no | — |
| `principal_ref` | `string` | yes | — |

**Responses**

| Status | Body | Description |
|---|---|---|
| `201` | object | OK |
| `400` | object | Bad Request — schema failure, or a DID segment outside the URL-safe alphabet. |
| `409` | object | Conflict — the handle or the derived DID is taken. |

**Response `201`**

| Field | Type | Required | Description |
|---|---|---|---|
| `agent_did` | `string` | yes | — |
| `kid` | `string` | yes | `\<did\>#\<n\>`, where n is the key's ordinal. |
| `pubkey` | `string` | yes | base64. |
| `status` | `"active"` | yes | — |

**Example response**

```json
{
  "agent_did": "did:web:codespar.dev:org:agent",
  "kid": "string",
  "pubkey": "string",
  "status": "active"
}
```

**Example request**

```bash
curl -X POST https://api.codespar.dev/v1/agents \
  -H "Authorization: Bearer $CODESPAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "agent_id": "agt_0000000000000000",
       "display_name": "Example",
       "principal_ref": "string"
     }'
```

### POST `/v1/agents/{agentId}/keys/rotate`

Mint a new signing key and retire the current one

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `agentId` | `string` | yes | — |

**Responses**

| Status | Body | Description |
|---|---|---|
| `201` | object | OK |
| `404` | object | Not Found — no such agent in this org. |
| `409` | object | Conflict — the agent has no active key to rotate. |

**Response `201`**

| Field | Type | Required | Description |
|---|---|---|---|
| `agent_did` | `string` | yes | — |
| `kid` | `string` | yes | — |
| `pubkey` | `string` | yes | base64. |
| `retired_kid` | `string` | yes | — |
| `status` | `"active"` | yes | — |

**Example response**

```json
{
  "agent_did": "did:web:codespar.dev:org:agent",
  "kid": "string",
  "pubkey": "string",
  "retired_kid": "string",
  "status": "active"
}
```

**Example request**

```bash
curl -X POST https://api.codespar.dev/v1/agents/{agentId}/keys/rotate \
  -H "Authorization: Bearer $CODESPAR_API_KEY"
```

### POST `/v1/agents/{agentId}/keys/{kid}/revoke`

Revoke one signing key

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `agentId` | `string` | yes | — |
| `kid` | `string` | yes | A full kid; the `#` must be sent as `%23`. |

**Responses**

| Status | Body | Description |
|---|---|---|
| `200` | object | OK |
| `404` | object | Not Found — no such key on this org's agent. |
| `409` | object | Conflict — the key is already revoked. |

**Response `200`**

| Field | Type | Required | Description |
|---|---|---|---|
| `kid` | `string` | yes | — |
| `revoked_at` | `string` | yes | — |
| `status` | `"revoked"` | yes | — |

**Example response**

```json
{
  "kid": "string",
  "status": "revoked",
  "revoked_at": "string"
}
```

**Example request**

```bash
curl -X POST https://api.codespar.dev/v1/agents/{agentId}/keys/{kid}/revoke \
  -H "Authorization: Bearer $CODESPAR_API_KEY"
```

### POST `/v1/agents/{did}/revoke`

Revoke an agent identity

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `did` | `string` | yes | — |

**Responses**

| Status | Body | Description |
|---|---|---|
| `200` | object | OK |
| `404` | object | Not Found |
| `409` | object | Conflict — the agent is already revoked. |

**Response `200`**

| Field | Type | Required | Description |
|---|---|---|---|
| `did` | `string` | yes | — |
| `limits` | object | yes | What this verb reaches and what it does not. Served with every 200 so the limit travels with the act. |
| `revoked_at` | `string` | yes | — |
| `revoked_kids` | array of `string` | yes | The signing keys the cascade revoked, in creation order. |
| `status` | `"revoked"` | yes | — |

**Example response**

```json
{
  "did": "did:web:codespar.dev:org:agent",
  "status": "revoked",
  "revoked_at": "string",
  "revoked_kids": [
    "string"
  ],
  "limits": {
    "stops": [
      "string"
    ],
    "does_not_stop": "string",
    "issue": "string"
  }
}
```

**Example request**

```bash
curl -X POST https://api.codespar.dev/v1/agents/{did}/revoke \
  -H "Authorization: Bearer $CODESPAR_API_KEY"
```