# Agento API — full reference

Base URL: https://api.agento.host

Authentication: send your API key in the `X-Api-Key` header.
Format: `ak_live_<32 hex chars>`. Create one at https://agento.host/app/api-keys.

Example:
```
curl -H "X-Api-Key: ak_live_..." https://api.agento.host/v1/agents
```

Every endpoint requires a key with the listed scopes. 401, 403, 429 and 500
errors return `{ "error": { "code": "...", "message": "..." } }`.

## Account

### `GET /v1/account`

Get account info

Returns the account record, current plan and entitlements, plus aggregate agent usage. No specific scope required.

**Response (200):**

```json
{
  "data": {
    "id": "8b1d4a1e-1c2f-4f51-b09b-9d1ad3a1c3bc",
    "name": "Acme Inc.",
    "plan": {
      "id": "pro",
      "name": "Pro",
      "status": "active",
      "limits": {
        "maxAgents": 10,
        "maxRunningAgents": 5
      },
      "features": {
        "swarms": true,
        "api_access": true
      }
    },
    "usage": {
      "agents": 3,
      "runningAgents": 1
    }
  }
}
```

**Errors:**

- 401 `unauthorized`
- 403 `forbidden`
- 429 `rate_limit_exceeded`
- 500 `internal_error`

---

### `GET /v1/agents/{id}/personality`

Get agent personality

Returns the agent's SOUL.md and IDENTITY.md content plus the SOUL.md hash for optimistic concurrency.

**Scopes:** `agents:read`

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |

**Response (200):** _schema-only_


**Errors:**

- 401 `unauthorized`
- 403 `forbidden`
- 429 `rate_limit_exceeded`
- 500 `internal_error`

---

### `PUT /v1/agents/{id}/personality`

Update agent personality

Replaces SOUL.md with new content. Pass `expectedHash` to detect concurrent edits.

**Scopes:** `agents:write`

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |

**Response (200):** _schema-only_


**Errors:**

- 401 `unauthorized`
- 403 `forbidden`
- 429 `rate_limit_exceeded`
- 500 `internal_error`

---

### `GET /v1/agents/{id}/rules`

List agent rules

Lists all .md files in the agent's workspace `rules/` directory with their byte sizes.

**Scopes:** `agents:read`

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |

**Response (200):** _schema-only_


**Errors:**

- 401 `unauthorized`
- 403 `forbidden`
- 429 `rate_limit_exceeded`
- 500 `internal_error`

---

### `GET /v1/agents/{id}/rules/{name}`

Read agent rule

Returns the content of a single rule file by name.

**Scopes:** `agents:read`

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |
| `name` | string | yes |  |

**Response (200):** _schema-only_


**Errors:**

- 401 `unauthorized`
- 403 `forbidden`
- 429 `rate_limit_exceeded`
- 500 `internal_error`

---

### `PUT /v1/agents/{id}/rules/{name}`

Create or replace agent rule

Writes the rule file to the agent workspace under `rules/<name>.md`. Restart is required for runtime effect.

**Scopes:** `agents:write`

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |
| `name` | string | yes |  |

**Response (200):** _schema-only_


**Errors:**

- 401 `unauthorized`
- 403 `forbidden`
- 429 `rate_limit_exceeded`
- 500 `internal_error`

---

### `DELETE /v1/agents/{id}/rules/{name}`

Delete agent rule

Removes the rule file from the agent workspace.

**Scopes:** `agents:write`

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |
| `name` | string | yes |  |

**Response (200):** _schema-only_


**Errors:**

- 401 `unauthorized`
- 403 `forbidden`
- 429 `rate_limit_exceeded`
- 500 `internal_error`

---

### `PUT /v1/agents/{id}/secrets`

Update agent secrets

Set, update, or delete agent secrets (LLM API keys, channel tokens, etc.). Secrets are write-only and cannot be read back.

**Scopes:** `agents:write`

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |

**Request body:**

```json
{
  "secrets": {
    "anthropicApiKey": "sk-ant-api03-..."
  },
  "deleteSecrets": [
    "openaiApiKey"
  ]
}
```

**Response (200):**

```json
{
  "data": {
    "updated": true,
    "needsRestart": true
  }
}
```

**Errors:**

- 401 `unauthorized`
- 403 `forbidden`
- 429 `rate_limit_exceeded`
- 500 `internal_error`

---

### `GET /v1/agents/{id}/workflow`

Get agent workflow

Reads WORKFLOW.md from the agent workspace and lists rule files. Live data is only available while the agent is running.

**Scopes:** `agents:read`

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |

**Response (200):**

```json
{
  "data": {
    "workflowMd": "# Workflow\n\n## Role\n\nYou are a customer support agent...",
    "rules": [
      "greeting.md",
      "escalation.md"
    ]
  }
}
```

**Errors:**

- 401 `unauthorized`
- 403 `forbidden`
- 429 `rate_limit_exceeded`
- 500 `internal_error`

---

### `PUT /v1/agents/{id}/workflow`

Update agent workflow

Writes WORKFLOW.md to the agent workspace. Agent restart is required for changes to take effect.

**Scopes:** `agents:write`

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |

**Request body:**

```json
{
  "workflowMd": "# Workflow\n\n## Role\n\nYou are a customer support agent."
}
```

**Response (200):** _schema-only_


**Errors:**

- 401 `unauthorized`
- 403 `forbidden`
- 429 `rate_limit_exceeded`
- 500 `internal_error`

---

## Agents

### `GET /v1/agents`

List agents

Returns all agents in your account, ordered by creation date (newest first). Deleted agents are excluded.

**Scopes:** `agents:read`

**Response (200):**

```json
{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "My Assistant",
      "status": "running",
      "region": "eu",
      "image": "openclaw/openclaw:latest",
      "swarm": null,
      "createdAt": "2026-01-15T10:30:00.000Z",
      "startedAt": "2026-01-15T10:31:00.000Z",
      "stoppedAt": null
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 1,
    "offset": 0
  }
}
```

**Errors:**

- 401 `unauthorized`
- 403 `forbidden`
- 429 `rate_limit_exceeded`
- 500 `internal_error`

---

### `POST /v1/agents`

Create agent

Creates a new agent, provisions a container on an available server, and starts it. Requires at least one LLM API key in secrets.

**Scopes:** `agents:write`

**Request body:**

```json
{
  "name": "My Assistant",
  "region": "eu",
  "secrets": {
    "anthropicApiKey": "sk-ant-api03-..."
  },
  "soulMd": "# SOUL.md\n\nYou are a helpful assistant.",
  "workflowMd": "# Workflow\n\n## Role\n\nDescribe your agent's role here."
}
```

**Response (200):**

```json
{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "My Assistant",
    "status": "running",
    "region": "eu",
    "createdAt": "2026-02-10T14:00:00.000Z",
    "startedAt": "2026-02-10T14:00:05.000Z"
  }
}
```

**Errors:**

- 401 `unauthorized`
- 403 `forbidden`
- 429 `rate_limit_exceeded`
- 500 `internal_error`

---

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

Get agent

Returns full details for a single agent, including config, error state, and restart status.

**Scopes:** `agents:read`

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |

**Response (200):** _schema-only_


**Errors:**

- 401 `unauthorized`
- 403 `forbidden`
- 429 `rate_limit_exceeded`
- 500 `internal_error`

---

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

Update agent

Update an agent. Returns the updated record. Setting `needsRestart` may be required for changes to take effect.

**Scopes:** `agents:write`

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |

**Request body:**

```json
{
  "name": "Renamed Assistant",
  "config": {
    "personalityStyle": "concise"
  }
}
```

**Response (200):** _schema-only_


**Errors:**

- 401 `unauthorized`
- 403 `forbidden`
- 429 `rate_limit_exceeded`
- 500 `internal_error`

---

### `DELETE /v1/agents/{id}`

Delete agent

Stops the agent container, removes its data, and marks the agent as deleted. Irreversible.

**Scopes:** `agents:write`

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |

**Response (200):**

```json
{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "deleted": true
  }
}
```

**Errors:**

- 401 `unauthorized`
- 403 `forbidden`
- 429 `rate_limit_exceeded`
- 500 `internal_error`

---

### `POST /v1/agents/{id}/restart`

Restart agent

Removes the running container and starts it again with current secrets and config.

**Scopes:** `agents:write`

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |

**Response (200):** _schema-only_


**Errors:**

- 401 `unauthorized`
- 403 `forbidden`
- 429 `rate_limit_exceeded`
- 500 `internal_error`

---

### `POST /v1/agents/{id}/start`

Start agent

Starts a stopped agent container, or recreates it if necessary.

**Scopes:** `agents:write`

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |

**Response (200):** _schema-only_


**Errors:**

- 401 `unauthorized`
- 403 `forbidden`
- 429 `rate_limit_exceeded`
- 500 `internal_error`

---

### `GET /v1/agents/{id}/status`

Get live agent status

Returns the current container status, prefering a recent Redis heartbeat and falling back to SSH inspection.

**Scopes:** `agents:read`

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |

**Response (200):**

```json
{
  "data": {
    "status": "running",
    "containerStatus": "running",
    "live": true,
    "source": "redis"
  }
}
```

**Errors:**

- 401 `unauthorized`
- 403 `forbidden`
- 429 `rate_limit_exceeded`
- 500 `internal_error`

---

### `POST /v1/agents/{id}/stop`

Stop agent

Stops a running agent container. Workspace is synced to storage.

**Scopes:** `agents:write`

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |

**Response (200):** _schema-only_


**Errors:**

- 401 `unauthorized`
- 403 `forbidden`
- 429 `rate_limit_exceeded`
- 500 `internal_error`

---

## Chat

### `GET /v1/agents/{id}/chat/messages`

Get chat message history

Reads the most recent assistant/user messages from the agent session transcript. Returns at most `limit` messages (default 50, max 200).

**Scopes:** `chat`

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `sessionId` | string | no |  |
| `limit` | integer | no |  |
| `since` | string | no |  |

**Response (200):**

```json
{
  "data": [
    {
      "role": "user",
      "content": "What is our refund policy?",
      "timestamp": "2026-05-02T10:30:00.000Z"
    },
    {
      "role": "assistant",
      "content": "Refunds are accepted within 30 days of purchase.",
      "timestamp": "2026-05-02T10:30:01.500Z"
    }
  ],
  "pagination": {
    "total": 2,
    "limit": 50,
    "offset": 0
  }
}
```

**Errors:**

- 401 `unauthorized`
- 403 `forbidden`
- 429 `rate_limit_exceeded`
- 500 `internal_error`

---

### `POST /v1/agents/{id}/chat/messages`

Send chat message (SSE)

Sends a user message and streams the agent response as Server-Sent Events. Response is `text/event-stream`. Pass `peerId` to scope session memory per end-user when one API key fronts multiple customers.

**Scopes:** `chat`

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |

**Request body:**

```json
{
  "message": "What is our refund policy?",
  "peerId": "customer-12345"
}
```

**Errors:**

- 401 `unauthorized`
- 403 `forbidden`
- 429 `rate_limit_exceeded`
- 500 `internal_error`

---

### `GET /v1/agents/{id}/chat/sessions`

List chat sessions

Returns the most recent 100 sessions for the agent (across all channels).

**Scopes:** `chat`

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |

**Response (200):** _schema-only_


**Errors:**

- 401 `unauthorized`
- 403 `forbidden`
- 429 `rate_limit_exceeded`
- 500 `internal_error`

---

### `POST /v1/agents/{id}/chat/sessions`

Create chat session

Resets the per-key default session for this agent and returns a new session id.

**Scopes:** `chat`

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |

**Response (200):**

```json
{
  "data": {
    "id": "sess_2026-05-02_8b1d4a1e",
    "startedAt": "2026-05-02T10:31:00.000Z"
  }
}
```

**Errors:**

- 401 `unauthorized`
- 403 `forbidden`
- 429 `rate_limit_exceeded`
- 500 `internal_error`

---

## Knowledge

### `GET /v1/knowledge`

List knowledge entries

Returns stored KB entries for a target. Use `nextOffset` to paginate.

**Scopes:** `knowledge:read`

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `swarmId` | string | no |  |
| `agentId` | string | no |  |
| `source` | string | no |  |
| `limit` | integer | no |  |
| `offset` | string | no |  |

**Response (200):**

```json
{
  "data": [
    {
      "id": "8b1d4a1e-1c2f-4f51-b09b-9d1ad3a1c3bc",
      "text": "Our refund policy allows returns within 30 days of purchase.",
      "source": "support/refund-policy.md",
      "type": "text",
      "createdAt": "2026-05-01T10:00:00.000Z",
      "updatedAt": "2026-05-01T10:00:00.000Z"
    }
  ],
  "pagination": {
    "nextOffset": null,
    "hasMore": false
  }
}
```

**Errors:**

- 401 `unauthorized`
- 403 `forbidden`
- 429 `rate_limit_exceeded`
- 500 `internal_error`

---

### `DELETE /v1/knowledge`

Delete knowledge entries

Delete by `id` (single entry), by `source` (all entries from that source), or `all=true&confirm=true` (entire target).

**Scopes:** `knowledge:write`

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `swarmId` | string | no |  |
| `agentId` | string | no |  |
| `source` | string | no |  |
| `id` | string | no |  |
| `all` | string | no |  |
| `confirm` | string | no |  |

**Response (200):**

```json
{
  "data": {
    "deleted": true
  }
}
```

**Errors:**

- 401 `unauthorized`
- 403 `forbidden`
- 429 `rate_limit_exceeded`
- 500 `internal_error`

---

### `POST /v1/knowledge/ingest`

Ingest knowledge chunks

Embed and store up to 100 text chunks for the target swarm or agent. Duplicates (cosine similarity > 0.95) are skipped.

**Scopes:** `knowledge:write`

**Request body:**

```json
{
  "agentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "chunks": [
    {
      "text": "Our refund policy allows returns within 30 days of purchase.",
      "source": "support/refund-policy.md"
    },
    {
      "text": "Shipping is free for orders over $50.",
      "source": "support/shipping.md",
      "metadata": {
        "type": "policy"
      }
    }
  ]
}
```

**Response (200):**

```json
{
  "data": {
    "stored": 2,
    "skipped": 0,
    "total": 2
  }
}
```

**Errors:**

- 401 `unauthorized`
- 403 `forbidden`
- 429 `rate_limit_exceeded`
- 500 `internal_error`

---

## Logs

### `GET /v1/agents/{id}/logs`

Get recent agent logs

Returns the most recent log lines from the agent container, concatenated as a single string.

**Scopes:** `logs`

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `tail` | integer | no |  |

**Response (200):**

```json
{
  "data": {
    "logs": "2026-05-02T10:30:00.000Z [info] Agent started\n2026-05-02T10:30:01.500Z [info] Connected to Telegram\n"
  }
}
```

**Errors:**

- 401 `unauthorized`
- 403 `forbidden`
- 429 `rate_limit_exceeded`
- 500 `internal_error`

---

### `GET /v1/agents/{id}/logs/stream`

Stream live agent logs (SSE)

Server-Sent Events stream of live log lines. Response is `text/event-stream`. Connect with an EventSource or a streaming HTTP client and consume `data:` frames until the client closes the connection.

**Scopes:** `logs`

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `tail` | integer | no |  |

**Errors:**

- 401 `unauthorized`
- 403 `forbidden`
- 429 `rate_limit_exceeded`
- 500 `internal_error`

---

## Skills

### `GET /v1/agents/{id}/skills`

List installed skills

Returns the skills currently installed on the agent, ordered by install date (newest first).

**Scopes:** `skills`

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |

**Response (200):** _schema-only_


**Errors:**

- 401 `unauthorized`
- 403 `forbidden`
- 429 `rate_limit_exceeded`
- 500 `internal_error`

---

### `POST /v1/agents/{id}/skills`

Install a skill on an agent

Adds a marketplace skill to the agent. The agent will need a restart for the skill to load.

**Scopes:** `skills`

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |

**Request body:**

```json
{
  "skillId": "web-search",
  "trustLevel": "verified"
}
```

**Response (200):** _schema-only_


**Errors:**

- 401 `unauthorized`
- 403 `forbidden`
- 429 `rate_limit_exceeded`
- 500 `internal_error`

---

### `DELETE /v1/agents/{id}/skills/{skillId}`

Uninstall a skill from an agent

Removes the installed skill. The agent needs a restart to fully unload it.

**Scopes:** `skills`

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |
| `skillId` | string | yes |  |

**Response (200):**

```json
{
  "data": {
    "skillId": "web-search",
    "uninstalled": true,
    "needsRestart": true
  }
}
```

**Errors:**

- 401 `unauthorized`
- 403 `forbidden`
- 429 `rate_limit_exceeded`
- 500 `internal_error`

---

### `GET /v1/skills`

Browse skill marketplace

Search verified skills available in the marketplace. Use `category` and `search` to narrow.

**Scopes:** `skills`

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `search` | string | no |  |
| `category` | string | no |  |
| `page` | integer | no |  |
| `pageSize` | integer | no |  |

**Response (200):** _schema-only_


**Errors:**

- 401 `unauthorized`
- 403 `forbidden`
- 429 `rate_limit_exceeded`
- 500 `internal_error`

---

### `POST /v1/skills`

Create a custom skill

Author a SKILL.md (and optional helper files) and store it as an account-private skill. Install it on any agent in the account via `POST /v1/agents/:id/skills` with `trustLevel: "custom"`.

**Scopes:** `skills`

**Request body:**

```json
{
  "name": "my-trello-helper",
  "description": "Manage Trello boards, lists, and cards via the REST API.",
  "version": "1.0.0",
  "files": {
    "SKILL.md": "---\nname: my-trello-helper\ndescription: Manage Trello boards.\n---\n\n# Trello\n\nUse `$TRELLO_API_KEY` and `$TRELLO_TOKEN`.\n",
    "scripts/list-cards.sh": "#!/bin/bash\ncurl -s \"https://api.trello.com/1/boards/$1/cards?key=$TRELLO_API_KEY&token=$TRELLO_TOKEN\"\n"
  }
}
```

**Response (200):** _schema-only_


**Errors:**

- 401 `unauthorized`
- 403 `forbidden`
- 429 `rate_limit_exceeded`
- 500 `internal_error`

---

### `GET /v1/skills/custom`

List custom skills

Returns custom skills authored by the authenticated account.

**Scopes:** `skills`

**Response (200):** _schema-only_


**Errors:**

- 401 `unauthorized`
- 403 `forbidden`
- 429 `rate_limit_exceeded`
- 500 `internal_error`

---

### `GET /v1/skills/custom/{id}`

Get a custom skill

Returns the skill manifest plus its file list (paths and sizes, not content).

**Scopes:** `skills`

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |

**Response (200):** _schema-only_


**Errors:**

- 401 `unauthorized`
- 403 `forbidden`
- 429 `rate_limit_exceeded`
- 500 `internal_error`

---

### `PATCH /v1/skills/custom/{id}`

Update a custom skill

Update the description, files, and/or version. If `version` is omitted but `files` change, the patch number is auto-bumped. Any agents currently running this skill must be restarted to pick up the new content.

**Scopes:** `skills`

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |

**Response (200):** _schema-only_


**Errors:**

- 401 `unauthorized`
- 403 `forbidden`
- 429 `rate_limit_exceeded`
- 500 `internal_error`

---

### `DELETE /v1/skills/custom/{id}`

Delete a custom skill

Deletes the skill and its files. If the skill is installed on any agents, returns 409 unless `force=true`.

**Scopes:** `skills`

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `force` | boolean | no |  |

**Response (200):** _schema-only_


**Errors:**

- 401 `unauthorized`
- 403 `forbidden`
- 429 `rate_limit_exceeded`
- 500 `internal_error`

---

### `GET /v1/skills/custom/{id}/files/{*}`

Read a custom skill file

Returns the raw content of a single file inside the skill, useful for round-tripping a skill back into Claude Code or another editor.

**Scopes:** `skills`

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |
| `path` | string | yes |  |

**Response (200):** _schema-only_


**Errors:**

- 401 `unauthorized`
- 403 `forbidden`
- 429 `rate_limit_exceeded`
- 500 `internal_error`

---

### `GET /v1/skills/{id}`

Get skill details

Returns the verified skill record with full description, tags, use cases, and security score.

**Scopes:** `skills`

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |

**Response (200):** _schema-only_


**Errors:**

- 401 `unauthorized`
- 403 `forbidden`
- 429 `rate_limit_exceeded`
- 500 `internal_error`

---

## Swarms

### `GET /v1/swarms`

List swarms

Returns all swarms in your account. Requires the swarms feature on your plan.

**Scopes:** `swarms:read`

**Response (200):**

```json
{
  "data": [
    {
      "id": "8b1d4a1e-1c2f-4f51-b09b-9d1ad3a1c3bc",
      "name": "Customer Support",
      "slug": "customer-support",
      "description": "Frontline support agents",
      "icon": "headset",
      "agentCount": 3,
      "memberCount": 2,
      "createdAt": "2026-04-01T10:00:00.000Z",
      "updatedAt": "2026-04-15T14:30:00.000Z"
    }
  ]
}
```

**Errors:**

- 401 `unauthorized`
- 403 `forbidden`
- 429 `rate_limit_exceeded`
- 500 `internal_error`

---

### `POST /v1/swarms`

Create swarm

Creates a new swarm. The slug is generated from the name and de-duplicated within your account.

**Scopes:** `swarms:write`

**Request body:**

```json
{
  "name": "Customer Support",
  "description": "Frontline support agents",
  "icon": "headset"
}
```

**Response (200):** _schema-only_


**Errors:**

- 401 `unauthorized`
- 403 `forbidden`
- 429 `rate_limit_exceeded`
- 500 `internal_error`

---

### `GET /v1/swarms/{id}`

Get swarm details

Returns the swarm record plus its non-deleted agents.

**Scopes:** `swarms:read`

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |

**Response (200):** _schema-only_


**Errors:**

- 401 `unauthorized`
- 403 `forbidden`
- 429 `rate_limit_exceeded`
- 500 `internal_error`

---

### `PATCH /v1/swarms/{id}`

Update swarm

Updates name, description, or icon. Slug is not updatable.

**Scopes:** `swarms:write`

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |

**Response (200):** _schema-only_


**Errors:**

- 401 `unauthorized`
- 403 `forbidden`
- 429 `rate_limit_exceeded`
- 500 `internal_error`

---

### `DELETE /v1/swarms/{id}`

Delete swarm

Removes the swarm. Members and providers cascade; assigned agents are unlinked (SetNull).

**Scopes:** `swarms:write`

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |

**Response (200):**

```json
{
  "data": {
    "id": "8b1d4a1e-1c2f-4f51-b09b-9d1ad3a1c3bc",
    "deleted": true
  }
}
```

**Errors:**

- 401 `unauthorized`
- 403 `forbidden`
- 429 `rate_limit_exceeded`
- 500 `internal_error`

---