# API: AI Brains, bozze e il Playground

_API · 6 min di lettura · Aggiornato 2026-10-22 · https://lanachat.ai/guides/it/api-ai-brains/_

Un **AI Brain** contiene come l'AI vende per una creator: le sue fasi di vendita, regole e impostazioni. Modifichi una **bozza**, la testi nel **Playground**, poi la **pubblichi**; il brain live cambia solo alla pubblicazione. Un brain è collegato a una sola creator e può essere riutilizzato dai suoi account.

## Endpoints

| Method | Path | Descrizione | Permesso | Stato |
|---|---|---|---|---|
| GET | `/brains` | Elenca i brain (`creator_id=`) | `can_engine` | Planned |
| POST | `/brains` | Crea un brain per una creator, vuoto o copiato da un altro (`copy_from`) | `can_engine` | Planned |
| GET | `/brains/{id}` | La versione live di un brain | `can_engine` | Planned |
| PATCH | `/brains/{id}` | Rinomina o collega a un'altra creator | `can_engine` | Planned |
| DELETE | `/brains/{id}` | Elimina un brain non usato da nessun account | `can_engine` | Planned |
| GET | `/brains/{id}/draft` | La bozza corrente e cosa differisce dal live | `can_engine` | Planned |
| PATCH | `/brains/{id}/draft` | Modifica la bozza (fasi, regole, impostazioni) | `can_engine` | Planned |
| DELETE | `/brains/{id}/draft` | Elimina la bozza | `can_engine` | Planned |
| POST | `/brains/{id}/publish` | Pubblica la bozza; diventa live su tutti gli account collegati | `can_publish` | Planned |
| GET | `/brains/{id}/versions` | Versioni pubblicate, dalla più recente | `can_engine` | Planned |
| POST | `/brains/{id}/versions/{version}/restore` | Copia una vecchia versione nella bozza | `can_engine` | Planned |
| POST | `/playground/{brain_id}/message` | Invia un messaggio di test alla bozza e ricevi la risposta AI | `can_engine` | Planned |
| DELETE | `/playground/{brain_id}/session` | Ricomincia la conversazione di test | `can_engine` | Planned |

## L'oggetto 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 }
  ]
}
```

| Campo | Tipo | Descrizione |
|---|---|---|
| `id` | string | Inizia con `br_` |
| `name` | string | Il suo nome nella Console |
| `creator_id` | string | La creator a cui è collegato |
| `version` | number | La versione live; aumenta di uno a ogni pubblicazione |
| `published_at` | string o null | Quando la versione live è stata pubblicata, ISO 8601 UTC |
| `has_draft` | boolean | `true` se esiste una bozza diversa dalla versione live |
| `accounts` | array di stringhe | Account Telegram che rispondono con questo brain |
| `phases` | array | Fasi di vendita: `key`, `name` e se ciascuna è `enabled` |

## Brain

### Elenca brain

`GET /brains` · `can_engine`

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `creator_id` | string | No | Solo i brain di questa creator |
| `limit`, `cursor` | number, string | No | [Paginazione](https://lanachat.ai/guides/it/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
}
```

### Crea un brain

`POST /brains` · `can_engine`

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `creator_id` | string | Sì | La creator per cui è |
| `name` | string | No | Il suo nome nella Console |
| `copy_from` | string | No | Id di un brain da copiare; senza di esso il brain parte vuoto |

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

La risposta è il nuovo brain (`201`). Un `copy_from` che non esiste in questo workspace risponde `404`.

### Ottieni un brain

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

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

La risposta è la versione live, come l'oggetto brain. La bozza si legge con `GET /brains/{id}/draft`.

### Rinomina o ricollega un brain

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

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `name` | string | No | Nuovo nome |
| `creator_id` | string | No | Collegalo a un'altra 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"}'
```

La risposta è il brain aggiornato.

### Elimina un brain

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

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

Un brain ancora usato da un account viene rifiutato (`409`): collega prima quegli account a un altro brain.

## Bozze e pubblicazione

### Leggi la bozza

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

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

La risposta è la bozza corrente (fasi, regole e impostazioni) e cosa differisce dalla versione live.

### Modifica la bozza

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

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `phases` | array | No | Fasi di vendita da modificare |
| `rules` | array | No | Regole da modificare |
| `settings` | object | No | Impostazioni da modificare, per esempio `first_offer_after_messages` o `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}}'
```

Cambiano solo i campi che invii. Il brain live non si modifica finché non pubblichi.

### Elimina la bozza

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

La bozza viene eliminata; la versione live resta com'è e `has_draft` diventa `false`.

### Pubblica la bozza

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

La bozza diventa live su ogni account collegato. Pubblicare senza bozza risponde `409`. I profili AI avanzati richiedono permessi proprietario, come nella Console. Un [webhook](https://lanachat.ai/guides/it/api-webhooks/) `brain.published` avvisa il tuo server.

## Versioni

### Elenca versioni

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

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

La risposta elenca le versioni pubblicate, dalla più recente, [paginata](https://lanachat.ai/guides/it/api-overview/).

### Ripristina una versione

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

La vecchia versione viene copiata nella bozza. Per i fan non cambia nulla finché non pubblichi. Una versione sconosciuta risponde `404`.

## Playground

Il Playground parla con la **bozza**, mai con un fan. Nulla viene inviato su Telegram e nulla viene venduto.

### Invia un messaggio di test

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

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `text` | string | Sì | Cosa scrive il fan di test |
| `fan` | object | No | Il fan di test: `language` (per esempio `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` è ciò che l'AI invierebbe: testo e media.
- `phase` è la fase di vendita in cui si trova l'AI.
- `explain` spiega in parole semplici perché ha risposto così.

Ogni chiamata continua la stessa conversazione di test.

### Ricomincia la conversazione di test

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

Il prossimo messaggio di test inizia una nuova conversazione, come un fan nuovo.

## Articoli correlati

- [API LanaChat: avvio rapido, autenticazione ed errori](https://lanachat.ai/guides/it/api-overview/)
- [Cos'è un AI Brain](https://lanachat.ai/guides/it/what-is-an-ai-brain/)
- [Playground: prova una conversazione in sicurezza](https://lanachat.ai/guides/it/playground/)