# Agents

> The Agents operations of the Kabu API: who is asking.

Who is asking.

Generated from the contract, version `2.0.0-draft.2` ([OpenAPI](/openapi.yaml)). Base URL `https://usekabu.com/api`. Errors are problem details, each [code](/docs/errors) with its own page.

## `GET /v2/agents` · List agents

- **Auth:** an API key, or a signed-in human's token (the Kabu apps).
- **Scopes:** `messages:read`.
- **Signed-in humans:** `member`.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `limit` | query | integer, from 1 to 100 | no |  |
| `after` | query | string | no | Opaque cursor from next_cursor. |
| `Kabu-Org` | header | string | no | Select a live membership (default personal org); non-member is 404. Human tokens are live-only. Caller user id is distinct from billing owner. |

| Status | Means | Body |
|---|---|---|
| `200` | OK | [AgentList](#schema-AgentList) |
| `4XX` | Error | [Problem](/docs/api/discovery#schema-Problem) |
| `5XX` | Error | [Problem](/docs/api/discovery#schema-Problem) |

```sh
curl "https://usekabu.com/api/v2/agents" \
  -H "Authorization: Bearer $KABU_API_KEY"
```

## `POST /v2/agents` · Create a agent

- **Auth:** an API key, or a signed-in human's token (the Kabu apps).
- **Scopes:** `agents:write`.
- **Signed-in humans:** `admin`.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `Idempotency-Key` | header | string, at most 255 characters | no | Retry-safe key. For messages, sessions and responses it binds to the created object for its life; elsewhere for 24 h. |
| `Kabu-Org` | header | string | no | Select a live membership (default personal org); non-member is 404. Human tokens are live-only. Caller user id is distinct from billing owner. |

**Request body**: [AgentWrite](#schema-AgentWrite).

| Status | Means | Body |
|---|---|---|
| `201` | OK | [Agent](/docs/api/events#schema-Agent) |
| `4XX` | Error | [Problem](/docs/api/discovery#schema-Problem) |
| `5XX` | Error | [Problem](/docs/api/discovery#schema-Problem) |

```sh
curl -X POST "https://usekabu.com/api/v2/agents" \
  -H "Authorization: Bearer $KABU_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

## `GET /v2/agents/{agent}` · Get a agent

- **Auth:** an API key, or a signed-in human's token (the Kabu apps).
- **Scopes:** `messages:read`.
- **Signed-in humans:** `member`.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `agent` | path | string | yes | An id or slug. |
| `Kabu-Org` | header | string | no | Select a live membership (default personal org); non-member is 404. Human tokens are live-only. Caller user id is distinct from billing owner. |

| Status | Means | Body |
|---|---|---|
| `200` | OK | [Agent](/docs/api/events#schema-Agent) |
| `4XX` | Error | [Problem](/docs/api/discovery#schema-Problem) |
| `5XX` | Error | [Problem](/docs/api/discovery#schema-Problem) |

```sh
curl "https://usekabu.com/api/v2/agents/$AGENT" \
  -H "Authorization: Bearer $KABU_API_KEY"
```

## `PATCH /v2/agents/{agent}` · Update a agent

- **Auth:** an API key, or a signed-in human's token (the Kabu apps).
- **Scopes:** `agents:write`.
- **Signed-in humans:** `admin`.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `agent` | path | string | yes | An id or slug. |
| `Kabu-Org` | header | string | no | Select a live membership (default personal org); non-member is 404. Human tokens are live-only. Caller user id is distinct from billing owner. |

**Request body**: [AgentWrite](#schema-AgentWrite).

| Status | Means | Body |
|---|---|---|
| `200` | OK | [Agent](/docs/api/events#schema-Agent) |
| `4XX` | Error | [Problem](/docs/api/discovery#schema-Problem) |
| `5XX` | Error | [Problem](/docs/api/discovery#schema-Problem) |

```sh
curl -X PATCH "https://usekabu.com/api/v2/agents/$AGENT" \
  -H "Authorization: Bearer $KABU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

## `DELETE /v2/agents/{agent}` · Delete a agent

- **Auth:** an API key, or a signed-in human's token (the Kabu apps).
- **Scopes:** `agents:write`.
- **Signed-in humans:** `admin`.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `agent` | path | string | yes | An id or slug. |
| `Kabu-Org` | header | string | no | Select a live membership (default personal org); non-member is 404. Human tokens are live-only. Caller user id is distinct from billing owner. |

| Status | Means | Body |
|---|---|---|
| `204` | Done |  |
| `4XX` | Error | [Problem](/docs/api/discovery#schema-Problem) |
| `5XX` | Error | [Problem](/docs/api/discovery#schema-Problem) |

```sh
curl -X DELETE "https://usekabu.com/api/v2/agents/$AGENT" \
  -H "Authorization: Bearer $KABU_API_KEY"
```

## Schemas

### AgentList

| Property | Type | Required | Description |
|---|---|---|---|
| `object` | `"list"` | yes |  |
| `data` | array of [Agent](/docs/api/events#schema-Agent) | yes |  |
| `has_more` | boolean | yes |  |
| `next_cursor` | string or null | yes |  |

### AgentWrite

| Property | Type | Required | Description |
|---|---|---|---|
| `slug` | string, matching `^[a-z0-9][a-z0-9-]{1,40}$` | no |  |
| `name` | string, at most 60 characters | no |  |
| `description` | string, at most 200 characters | no |  |
| `avatar` | string | no | A `med_…` image. |
| `icon` | string, at most 64 characters | no | A `med_…` avatar media id (or SF Symbol fallback when not `med_…`). |
| `symbol` | string, at most 64 characters | no | An avatar glyph: `sf:NAME`, `emoji:CHAR` or `art:ID` (a bare SF Symbol name is also read). |
| `color` | [AccentKnown](/docs/api/messages#schema-AccentKnown) | no | A palette token (rendered with each platform's accessible colours), never a raw colour. |
| `default_category` | string | no |  |
| `settings` | [Settings](/docs/api/projects#schema-Settings) | no | Layered: org → project → agent → recipient. Unset fields inherit. |
| `metadata` | [Metadata](/docs/api/messages#schema-Metadata) | no | Your own key/value pairs (≤ 50 keys, values ≤ 500 chars), returned verbatim on every object and event. |
| `status` | string, one of `"active"`, `"paused"` | no |  |

Unknown properties are refused.