> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usecadence.gg/llms.txt
> Use this file to discover all available pages before exploring further.

# Bots

> List, create, update and archive bots.

All bot procedures act in the current [space](https://docs.usecadence.gg/api/introduction.md#spaces).

## bots/list

`POST /rpc/bots/list` returns the bots you can see in the space. No input.

```bash theme={null}
curl -s "$CADENCE_URL/rpc/bots/list" \
  -H "Authorization: Bearer $CADENCE_TOKEN" \
  -H "Content-Type: application/json" -d '{}'
```

`bots/listArchived` returns archived bots the same way.

## bots/get

`POST /rpc/bots/get` returns one bot.

**botId** `string` *required*

The bot's id.

### The bot object

**id** `string`

The bot's id.

**spaceId** `string`

The space it belongs to.

**name** `string`

Display name.

**title** `string`

The short label under the name.

**instructions** `string`

The bot's instructions.

**threadId** `string`

The id of the bot's own chat.

**status** `string`

What the bot is doing now.

**pinned** `boolean`

Whether it is pinned in the sidebar.

**computerMode** `"team" | "dedicated"`

Shared team computer, or its own.

**modelProvider** `string | null`

Its own model provider, or null for the space default.

**modelId** `string | null`

Its own model, or null for the space default.

**thinkingLevel** `string | null`

`off`, `minimal`, `low`, `medium`, `high`, `xhigh` or `max`.

**archivedAt** `string | null`

When it was archived.

**createdAt** `string`

ISO timestamp.

**updatedAt** `string`

ISO timestamp.

## bots/create

`POST /rpc/bots/create` creates a bot and returns it.

**name** `string` *required*

Up to 80 characters.

**title** `string`

Up to 500 characters.

**instructions** `string`

Up to 100,000 characters.

**computerMode** `"team" | "dedicated"` (default: team)

Which computer it uses.

**notifyOnFinish** `boolean` (default: true)

Notify when it finishes a task.

**spawnKey** `string`

An idempotency key. Creating twice with the same key in a space returns the same bot.

```bash theme={null}
curl -s "$CADENCE_URL/rpc/bots/create" \
  -H "Authorization: Bearer $CADENCE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"json": {"name": "Ada", "instructions": "You answer customer questions for Example Co."}}'
```

## bots/update

`POST /rpc/bots/update` changes any of a bot's settings and returns the bot. Send only the fields you want to change.

**botId** `string` *required*

The bot to change.

**name** `string`

Up to 80 characters.

**title** `string`

Up to 500 characters.

**instructions** `string`

Up to 100,000 characters.

**expectedInstructions** `string`

The instructions you started from. If they changed since, the call fails with `CONFLICT`.

**pinned** `boolean`

Pin or unpin.

**modelProvider** `string | null`

Set together with `modelId`. Both null returns the bot to the space default.

**modelId** `string | null`

Set together with `modelProvider`.

**thinkingLevel** `string | null`

`off` to `max`, or null for the default.

**notifyOnFinish** `boolean`

Notify when it finishes a task.

```bash theme={null}
curl -s "$CADENCE_URL/rpc/bots/update" \
  -H "Authorization: Bearer $CADENCE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"json": {"botId": "YOUR_BOT_ID", "pinned": true}}'
```

## bots/setComputer

`POST /rpc/bots/setComputer` switches the bot between the team computer and its own.

**botId** `string` *required*

The bot.

**mode** `"team" | "dedicated"` *required*

`dedicated` is a private computer.

## bots/visibility and bots/setVisibility

Who else in the space can use the bot. Only the bot's creator and space admins can change it.

**visibility** `"everyone" | "admins" | \{ people: string[] \}` *required*

`everyone`, `admins`, or a list of emails and `@domain` entries (up to 500).

## Archive, restore, duplicate, remove

| Procedure | Input | Effect |
| - | - | - |
| `bots/archive` | `{ botId }` | Hides the bot. |
| `bots/restore` | `{ botId }` | Brings an archived bot back. |
| `bots/duplicate` | `{ botId }` | Creates a copy and returns it. |
| `bots/remove` | `{ botId, deleteMemories }` | Deletes the bot. `deleteMemories` (default `false`) also deletes its memory. |
| `bots/restoreInstructions` | `{ botId, versionId, expectedInstructions }` | Restores an earlier version of the instructions. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.