# API: AI Brains, rascunhos e o Playground

_API · Leitura de 6 min · Atualizado 2026-10-22 · https://lanachat.ai/guides/pt/api-ai-brains/_

Um **AI Brain** guarda como a IA vende para uma criadora: suas fases de venda, regras e configurações. Você altera um **rascunho**, testa no **Playground** e então **publica**; o brain ativo só muda ao publicar. Um brain está vinculado a uma criadora e pode ser reutilizado pelas contas dela.

## Endpoints

| Method | Path | Description | Permission | Status |
|---|---|---|---|---|
| GET | `/brains` | Listar brains (`creator_id=`) | `can_engine` | Planned |
| POST | `/brains` | Criar um brain para uma criadora, vazio ou copiado de outro (`copy_from`) | `can_engine` | Planned |
| GET | `/brains/{id}` | A versão ativa de um brain | `can_engine` | Planned |
| PATCH | `/brains/{id}` | Renomear ou vincular a outra criadora | `can_engine` | Planned |
| DELETE | `/brains/{id}` | Apagar um brain que nenhuma conta usa | `can_engine` | Planned |
| GET | `/brains/{id}/draft` | O rascunho atual e o que difere do ativo | `can_engine` | Planned |
| PATCH | `/brains/{id}/draft` | Alterar o rascunho (fases, regras, configurações) | `can_engine` | Planned |
| DELETE | `/brains/{id}/draft` | Descartar o rascunho | `can_engine` | Planned |
| POST | `/brains/{id}/publish` | Publicar o rascunho; vira ativo em todas as contas vinculadas | `can_publish` | Planned |
| GET | `/brains/{id}/versions` | Versões publicadas, da mais nova para a mais antiga | `can_engine` | Planned |
| POST | `/brains/{id}/versions/{version}/restore` | Copiar uma versão antiga para o rascunho | `can_engine` | Planned |
| POST | `/playground/{brain_id}/message` | Enviar mensagem de teste para o rascunho e receber resposta da IA | `can_engine` | Planned |
| DELETE | `/playground/{brain_id}/session` | Reiniciar a conversa de teste | `can_engine` | Planned |

## O objeto brain

```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 | Começa com `br_` |
| `name` | string | Nome no Console |
| `creator_id` | string | Criadora a que está vinculado |
| `version` | number | Versão ativa; incrementa em 1 a cada publicação |
| `published_at` | string ou null | Quando a versão ativa foi publicada, ISO 8601 UTC |
| `has_draft` | boolean | `true` quando o rascunho difere da versão ativa |
| `accounts` | array de strings | Contas Telegram que respondem com este brain |
| `phases` | array | Fases de venda: `key`, `name` e se cada uma está `enabled` |

## Brains

### Listar brains

`GET /brains` · `can_engine`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `creator_id` | string | Não | Apenas brains desta criadora |
| `limit`, `cursor` | number, string | Não | [Paginação](https://lanachat.ai/guides/pt/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
}
```

### Criar um brain

`POST /brains` · `can_engine`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `creator_id` | string | Sim | A criadora para quem é |
| `name` | string | Não | Nome no Console |
| `copy_from` | string | Não | Id de um brain para copiar; sem ele o brain começa vazio |

```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"}'
```

A resposta é o brain novo (`201`). Um `copy_from` que não existe neste workspace responde `404`.

### Obter um brain

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

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

A resposta é a versão ativa, como o objeto brain. O rascunho é lido com `GET /brains/{id}/draft`.

### Renomear ou vincular um brain

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

| Parameter | Type | Required | Description |
|---|---|---|---|
| `name` | string | Não | Novo nome |
| `creator_id` | string | Não | Vincular a outra criadora |

```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"}'
```

A resposta é o brain atualizado.

### Apagar um brain

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

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

Um brain que ainda é usado por alguma conta é recusado (`409`): vincule essas contas a outro brain primeiro.

## Rascunhos e publicação

### Ler o rascunho

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

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

A resposta é o rascunho atual (fases, regras e configurações) e o que difere da versão ativa.

### Alterar o rascunho

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

| Parameter | Type | Required | Description |
|---|---|---|---|
| `phases` | array | Não | Fases de venda para alterar |
| `rules` | array | Não | Regras para alterar |
| `settings` | object | Não | Configurações para alterar, por exemplo `first_offer_after_messages` ou `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}}'
```

Só os campos enviados são alterados. O brain ativo não muda até você publicar.

### Descartar o rascunho

`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"
```

O rascunho é apagado; a versão ativa permanece e `has_draft` vira `false`.

### Publicar o rascunho

`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 }
```

O rascunho vira ativo em todas as contas vinculadas. Publicar sem rascunho responde `409`. Perfis avançados de IA precisam de permissões próprias do dono, como no Console. Um [webhook](https://lanachat.ai/guides/pt/api-webhooks/) `brain.published` avisa seu servidor.

## Versões

### Listar versões

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

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

A resposta lista as versões publicadas, da mais nova para a mais antiga, [paginadas](https://lanachat.ai/guides/pt/api-overview/).

### Restaurar uma versão

`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)"
```

A versão antiga é copiada para o rascunho. Nada muda para os fãs até você publicar. Uma versão desconhecida responde `404`.

## Playground

O Playground conversa com o **rascunho**, nunca com um fã. Nada é enviado no Telegram e nada é vendido.

### Enviar mensagem de teste

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

| Parameter | Type | Required | Description |
|---|---|---|---|
| `text` | string | Sim | O que o fã de teste escreve |
| `fan` | object | Não | O fã de teste: `language` (por exemplo `en`) e `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` é o que a IA enviaria: texto e mídia.
- `phase` é a fase de venda em que a IA está.
- `explain` explica em inglês simples por que respondeu assim.

Cada chamada continua a mesma conversa de teste.

### Reiniciar a conversa de teste

`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"
```

A próxima mensagem de teste inicia uma conversa nova, como um fã novo.

## Artigos relacionados

- [API LanaChat: início rápido, autenticação e erros](https://lanachat.ai/guides/pt/api-overview/)
- [O que é um AI Brain](https://lanachat.ai/guides/pt/what-is-an-ai-brain/)
- [Playground: teste uma conversa com segurança](https://lanachat.ai/guides/pt/playground/)