---
title: "Agents API"
description: "Registration, lifecycle control and key rotation for agent identities."
label: "Agents"
generated: "the API catalogue in apps/control-plane/src/routes/developer.ts"
---


Registration is the only moment a private key can be returned, and only when Veefore generated it. Prefer supplying your own `public_key` so the private half never crosses the network at all. Lifecycle transitions are not interchangeable: `pause` is reversible and operational, `suspend` is reversible and security-driven, `revoke` is terminal.

:::warning Step-up required
2 endpoints in this group require a fresh step-up authentication within the last few minutes, even for a session that already holds the permission. They are marked below.
:::

## Endpoints

| | Endpoint | Permission | Notes |
| --- | --- | --- | --- |
| `GET` | `/v1/agents` | `agent:read` | — |
| `POST` | `/v1/agents` | `agent:create` | accepts `Idempotency-Key` |
| `GET` | `/v1/agents/{agentId}` | `agent:read` | — |
| `PATCH` | `/v1/agents/{agentId}` | `agent:update` | — |
| `POST` | `/v1/agents/{agentId}/pause` | `agent:pause` | — |
| `POST` | `/v1/agents/{agentId}/resume` | `agent:resume` | — |
| `POST` | `/v1/agents/{agentId}/suspend` | `agent:suspend` | — |
| `POST` | `/v1/agents/{agentId}/revoke` | `agent:revoke` | step-up, high impact |
| `POST` | `/v1/agents/{agentId}/rotate-credentials` | `agent:rotate_credentials` | — |
| `GET` | `/v1/agents/{agentId}/health` | `agent:read` | — |
| `GET` | `/v1/agents/{agentId}/authority` | `delegation:read` | — |
| `POST` | `/v1/agents/bulk` | `agent:revoke` | step-up, high impact |
| `POST` | `/v1/agents/bulk/preview` | `agent:read` | — |

## What each endpoint does

### `GET /v1/agents`

List agents with operational columns.

Requires `agent:read`.

### `POST /v1/agents`

Register an agent, issue identity and passport.

Requires `agent:create`.

Request body:

```json
{
  "name": "string",
  "workspace_id": "string",
  "environment_id": "string",
  "capabilities": "string[]",
  "public_key": "base64 SPKI?"
}
```

Response:

```json
{
  "data": {
    "agent": {
      "id": "agt_…"
    },
    "private_key": "base64 PKCS8 (shown once, only if Veefore generated it)"
  }
}
```

### `GET /v1/agents/{agentId}`

Read an agent.

Requires `agent:read`.

### `PATCH /v1/agents/{agentId}`

Update agent metadata.

Requires `agent:update`.

### `POST /v1/agents/{agentId}/pause`

Stop new protected execution.

Requires `agent:pause`.

### `POST /v1/agents/{agentId}/resume`

Resume a paused agent.

Requires `agent:resume`.

### `POST /v1/agents/{agentId}/suspend`

Security-restricted state.

Requires `agent:suspend`.

Request body:

```json
{
  "reason": "string"
}
```

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

Terminal identity invalidation.

Requires `agent:revoke`. Step-up authentication is also required.

Request body:

```json
{
  "reason": "string"
}
```

### `POST /v1/agents/{agentId}/rotate-credentials`

Rotate the agent identity key.

Requires `agent:rotate_credentials`.

### `GET /v1/agents/{agentId}/health`

Operational health report.

Requires `agent:read`.

### `GET /v1/agents/{agentId}/authority`

Resolved effective authority.

Requires `delegation:read`.

### `POST /v1/agents/bulk`

Bulk lifecycle operation with per-agent results.

Requires `agent:revoke`. Step-up authentication is also required.

Request body:

```json
{
  "agent_ids": "string[]",
  "operation": "pause|resume|suspend|revoke",
  "reason": "string"
}
```

### `POST /v1/agents/bulk/preview`

Preview a bulk operation before confirming.

Requires `agent:read`.