# API: AI Brains, drafts and the Playground

_API · 6 min read · Updated 2026-10-22 · https://lanachat.ai/guides/api-ai-brains/_

An **AI Brain** holds how the AI sells for a creator: its sales phases, rules and settings. You change a **draft**, test it in the **Playground**, then **publish** it; the live brain only changes on publish. A brain is linked to one creator and can be reused by her accounts.

## Endpoints

| Method | Path | Description | Permission | Status |
|---|---|---|---|---|
| GET | `/brains` | List brains (`creator_id=`) | `can_engine` | Planned |
| POST | `/brains` | Create a brain for a creator, empty or copied from another (`copy_from`) | `can_engine` | Planned |
| GET | `/brains/{id}` | The live version of a brain | `can_engine` | Planned |
| PATCH | `/brains/{id}` | Rename it or link it to another creator | `can_engine` | Planned |
| DELETE | `/brains/{id}` | Delete a brain no account uses | `can_engine` | Planned |
| GET | `/brains/{id}/draft` | The current draft and what differs from live | `can_engine` | Planned |
| PATCH | `/brains/{id}/draft` | Change the draft (phases, rules, settings) | `can_engine` | Planned |
| DELETE | `/brains/{id}/draft` | Throw the draft away | `can_engine` | Planned |
| POST | `/brains/{id}/publish` | Publish the draft; it becomes live on every linked account | `can_publish` | Planned |
| GET | `/brains/{id}/versions` | Published versions, newest first | `can_engine` | Planned |
| POST | `/brains/{id}/versions/{version}/restore` | Copy an old version into the draft | `can_engine` | Planned |
| POST | `/playground/{brain_id}/message` | Send a test message to the draft and get the AI's reply | `can_engine` | Planned |
| DELETE | `/playground/{brain_id}/session` | Start the test conversation over | `can_engine` | Planned |

## The brain object

```json
{
  "id": "br_lea_main",
  "name": "Lea · main",
  "creator_id": "cr_lea",
  "version": 12,
  "published_at": "2026-10-04T21:10:00Z",
  "has_draft": true,
  "accounts": ["acc_1001", "acc_1004"],
  "phases": [
    { "key": "warm_up", "name": "Warm up", "enabled": true },
    { "key": "first_offer", "name": "First offer", "enabled": true }
  ]
}
```

| Field | Type | Description |
|---|---|---|
| `id` | string | Starts with `br_` |
| `name` | string | Its name in the Console |
| `creator_id` | string | The creator it is linked to |
| `version` | number | The live version; it goes up by one on each publish |
| `published_at` | string or null | When the live version was published, ISO 8601 UTC |
| `has_draft` | boolean | `true` when a draft differs from the live version |
| `accounts` | array of strings | Telegram accounts that answer with this brain |
| `phases` | array | Sales phases: `key`, `name` and whether each one is `enabled` |

## Brains

### List brains

`GET /brains` · `can_engine`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `creator_id` | string | No | Only this creator's brains |
| `limit`, `cursor` | number, string | No | [Pagination](https://lanachat.ai/guides/api-overview/) |

```bash
curl "https://api.lanachat.ai/v1/brains?creator_id=cr_lea" \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

```json
{
  "data": [
    { "id": "br_lea_main", "name": "Lea · main", "creator_id": "cr_lea", "version": 12, "published_at": "2026-10-04T21:10:00Z", "has_draft": true, "accounts": ["acc_1001", "acc_1004"], "phases": [ { "key": "warm_up", "name": "Warm up", "enabled": true }, { "key": "first_offer", "name": "First offer", "enabled": true } ] }
  ],
  "next_cursor": null
}
```

### Create a brain

`POST /brains` · `can_engine`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `creator_id` | string | Yes | The creator it is for |
| `name` | string | No | Its name in the Console |
| `copy_from` | string | No | Id of a brain to copy; without it the brain starts empty |

```bash
curl -X POST https://api.lanachat.ai/v1/brains \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"creator_id": "cr_lea", "name": "Lea · TikTok test", "copy_from": "br_lea_main"}'
```

The answer is the new brain (`201`). A `copy_from` brain that does not exist in this workspace answers `404`.

### Get a brain

`GET /brains/{id}` · `can_engine`

```bash
curl https://api.lanachat.ai/v1/brains/br_lea_main \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

The answer is the live version, as the brain object. The draft is read with `GET /brains/{id}/draft`.

### Rename or relink a brain

`PATCH /brains/{id}` · `can_engine`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `name` | string | No | New name |
| `creator_id` | string | No | Link it to another creator |

```bash
curl -X PATCH https://api.lanachat.ai/v1/brains/br_lea_main \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Lea · main FR"}'
```

The answer is the updated brain.

### Delete a brain

`DELETE /brains/{id}` · `can_engine`

```bash
curl -X DELETE https://api.lanachat.ai/v1/brains/br_lea_old \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

A brain that an account still uses is refused (`409`): link those accounts to another brain first.

## Drafts and publishing

### Read the draft

`GET /brains/{id}/draft` · `can_engine`

```bash
curl https://api.lanachat.ai/v1/brains/br_lea_main/draft \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

The answer is the current draft (phases, rules and settings) and what differs from the live version.

### Change the draft

`PATCH /brains/{id}/draft` · `can_engine`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `phases` | array | No | Sales phases to change |
| `rules` | array | No | Rules to change |
| `settings` | object | No | Settings to change, for example `first_offer_after_messages` or `max_discount_percent` |

```bash
curl -X PATCH https://api.lanachat.ai/v1/brains/br_lea_main/draft \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"settings": {"first_offer_after_messages": 6, "max_discount_percent": 20}}'
```

Only the fields you send change. The live brain does not move until you publish.

### Throw the draft away

`DELETE /brains/{id}/draft` · `can_engine`

```bash
curl -X DELETE https://api.lanachat.ai/v1/brains/br_lea_main/draft \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

The draft is deleted; the live version stays as it is and `has_draft` becomes `false`.

### Publish the draft

`POST /brains/{id}/publish` · `can_publish`

```bash
curl -X POST https://api.lanachat.ai/v1/brains/br_lea_main/publish \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
```

```json
{ "id": "br_lea_main", "version": 13, "published_at": "2026-10-06T14:20:03Z", "has_draft": false }
```

The draft becomes live on every linked account. Publishing without a draft answers `409`. Advanced AI profiles need their own owner permissions, as in the Console. A [webhook](https://lanachat.ai/guides/api-webhooks/) `brain.published` tells your server.

## Versions

### List versions

`GET /brains/{id}/versions` · `can_engine`

```bash
curl https://api.lanachat.ai/v1/brains/br_lea_main/versions \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

The answer lists the published versions, newest first, [paginated](https://lanachat.ai/guides/api-overview/).

### Restore a version

`POST /brains/{id}/versions/{version}/restore` · `can_engine`

```bash
curl -X POST https://api.lanachat.ai/v1/brains/br_lea_main/versions/11/restore \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
```

The old version is copied into the draft. Nothing changes for fans until you publish. An unknown version answers `404`.

## Playground

The Playground talks to the **draft**, never to a fan. Nothing is sent on Telegram and nothing is sold.

### Send a test message

`POST /playground/{brain_id}/message` · `can_engine`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `text` | string | Yes | What the test fan writes |
| `fan` | object | No | The test fan: `language` (for example `en`) and `is_new` |

```bash
curl -X POST https://api.lanachat.ai/v1/playground/br_lea_main/message \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"text": "hey, are you real?", "fan": {"language": "en", "is_new": true}}'
```

```json
{
  "reply": { "text": "Haha very real, just slow at typing 🙈 where are you from?", "media": [] },
  "phase": "warm_up",
  "explain": "Phrase bank answer for \"Are you a bot?\", then a question to keep the fan talking."
}
```

- `reply` is what the AI would send: text and media.
- `phase` is the sales phase the AI is in.
- `explain` says in plain English why it answered that way.

Each call continues the same test conversation.

### Start the test conversation over

`DELETE /playground/{brain_id}/session` · `can_engine`

```bash
curl -X DELETE https://api.lanachat.ai/v1/playground/br_lea_main/session \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

The next test message starts a new conversation, as a new fan.

## Related

- [LanaChat API: quick start, authentication and errors](https://lanachat.ai/guides/api-overview/)
- [What an AI Brain is](https://lanachat.ai/guides/what-is-an-ai-brain/)
- [Playground: test a conversation safely](https://lanachat.ai/guides/playground/)