> ## 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.

# Instruction files

> Manage the documents a bot reads on every run.

These procedures manage a bot's [instruction files](https://docs.usecadence.gg/bots/instruction-files.md). Anyone who can edit the bot can use them. Every change keeps the replaced version in the permanent archive.

### The file object

**id** `string`

The file's id.

**botId** `string`

The bot it belongs to.

**name** `string`

Up to 80 characters, unique per bot.

**content** `string`

Up to 100,000 characters.

**position** `number`

Its place in the reading order.

**history** `array`

Recent versions, each with `id`, `name`, `content`, `reason` and `createdAt`.

## botFiles/list

`POST /rpc/botFiles/list` returns a bot's files in order.

**botId** `string` *required*

The bot.

## botFiles/create

`POST /rpc/botFiles/create` adds a file at the end.

**botId** `string` *required*

The bot.

**name** `string` *required*

Up to 80 characters.

**content** `string` (default: "")

Up to 100,000 characters.

```bash theme={null}
curl -s "$CADENCE_URL/rpc/botFiles/create" \
  -H "Authorization: Bearer $CADENCE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"json": {"botId": "YOUR_BOT_ID", "name": "Prices", "content": "Standard delivery: $5\nExpress delivery: $12"}}'
```

A bot holds up to 30 files and 300,000 characters across all of them.

## botFiles/update

`POST /rpc/botFiles/update` renames a file, changes its content, or both.

**fileId** `string` *required*

The file.

**name** `string`

A new name.

**content** `string`

The new content.

**expectedContent** `string`

The content you started from. If someone saved first, the call fails with `CONFLICT`.

## botFiles/move

`POST /rpc/botFiles/move` changes the reading order and returns all the bot's files.

**fileId** `string` *required*

The file.

**position** `number` *required*

The new position, from 0.

## botFiles/restore

`POST /rpc/botFiles/restore` brings back an earlier version from the file's `history`.

**fileId** `string` *required*

The file.

**versionId** `string` *required*

The version's id.

## botFiles/remove

`POST /rpc/botFiles/remove` deletes a file. Its content stays in the archive, where the bot can still read it with `instruction_file_history`.

**fileId** `string` *required*

The file.


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