# API: criadoras, identidade e persona

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

Uma **creator** é uma pessoa que sua agência gerencia no Telegram. Ela tem uma **identity** (quem ela é), uma **persona** (como ela fala, em oito páginas) e links para suas contas do Telegram, seu AI Brain, seu Vault e seus scripts. Esses endpoints correspondem à página **Creators** do Console.

## Endpoints

| Method | Path | Description | Permission | Status |
|---|---|---|---|---|
| GET | `/creators` | Lista as creators (`status=active,paused,archived`, `q=` busca por nome) | `can_setup` ou `can_fan_read` | Planned |
| POST | `/creators` | Cria uma creator (nome obrigatório) | `can_setup` | Planned |
| GET | `/creators/{id}` | Uma creator com o progresso do setup | `can_setup` ou `can_fan_read` | Planned |
| PATCH | `/creators/{id}` | Renomeia, troca a foto, fuso horário ou brain vinculado | `can_setup` | Planned |
| POST | `/creators/{id}/pause` | Pausa a creator: a IA para de responder em todas as contas dela | `can_setup` | Planned |
| POST | `/creators/{id}/resume` | Retoma uma creator pausada | `can_setup` | Planned |
| DELETE | `/creators/{id}` | Arquiva a creator (os fãs e vendas são mantidos) | `can_setup` | Planned |
| GET | `/creators/{id}/identity` | O cartão de identidade dela | `can_setup` | Planned |
| PUT | `/creators/{id}/identity` | Substitui o cartão de identidade dela | `can_setup` | Planned |
| GET | `/creators/{id}/persona` | As oito páginas da persona e o quanto estão completas | `can_engine` | Planned |
| PATCH | `/creators/{id}/persona` | Altera uma ou mais páginas da persona | `can_engine` | Planned |
| GET | `/creators/{id}/setup` | O cartão Setup: cada etapa e se está concluída | `can_setup` | Planned |

## O objeto creator

```json
{
  "id": "cr_lea",
  "name": "Lea",
  "status": "active",
  "photo_url": "https://cdn.lanachat.ai/w/7Hq2/cr_lea/photo.jpg",
  "timezone": "Europe/Paris",
  "brain_id": "br_lea_main",
  "accounts": { "total": 3, "connected": 2 },
  "setup": { "done": 5, "total": 7 },
  "created_at": "2026-08-14T09:12:00Z",
  "updated_at": "2026-10-05T18:40:11Z"
}
```

| Field | Type | Description |
|---|---|---|
| `id` | string | Começa com `cr_` |
| `name` | string | Nome dela no Console |
| `status` | string | `active`, `paused` ou `archived` |
| `photo_url` | string ou null | Foto dela |
| `timezone` | string | Fuso horário IANA, por exemplo `Europe/Paris` |
| `brain_id` | string ou null | O AI Brain vinculado a ela |
| `accounts` | object | Contagem das contas Telegram dela: `total`, `connected` |
| `setup` | object | Etapas do cartão Setup `done` de `total` |
| `created_at`, `updated_at` | string | ISO 8601, UTC |

Uma creator pausada mantém as contas conectadas, mas a IA não responde; scripts em andamento param no próximo passo.

## Creators

### Listar creators

`GET /creators` · `can_setup` ou `can_fan_read`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `status` | string | Não | `active`, `paused` ou `archived`; vários separados por vírgula |
| `q` | string | Não | Parte do nome dela |
| `limit`, `cursor` | number, string | Não | [Paginação](https://lanachat.ai/guides/pt/api-overview/) |

```bash
curl "https://api.lanachat.ai/v1/creators?status=active,paused" \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

```json
{
  "data": [
    { "id": "cr_lea", "name": "Lea", "status": "active", "photo_url": "https://cdn.lanachat.ai/w/7Hq2/cr_lea/photo.jpg", "timezone": "Europe/Paris", "brain_id": "br_lea_main", "accounts": { "total": 3, "connected": 2 }, "setup": { "done": 5, "total": 7 }, "created_at": "2026-08-14T09:12:00Z", "updated_at": "2026-10-05T18:40:11Z" },
    { "id": "cr_mia", "name": "Mia", "status": "paused", "photo_url": null, "timezone": "Europe/Rome", "brain_id": "br_mia_main", "accounts": { "total": 2, "connected": 2 }, "setup": { "done": 7, "total": 7 }, "created_at": "2026-07-02T11:00:00Z", "updated_at": "2026-10-01T08:15:00Z" }
  ],
  "next_cursor": null
}
```

### Criar uma creator

`POST /creators` · `can_setup`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `name` | string | Sim | Nome dela no Console |
| `timezone` | string | Não | Fuso horário IANA |

```bash
curl -X POST https://api.lanachat.ai/v1/creators \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name": "Lea", "timezone": "Europe/Paris"}'
```

```json
{
  "id": "cr_lea",
  "name": "Lea",
  "status": "active",
  "photo_url": null,
  "timezone": "Europe/Paris",
  "brain_id": null,
  "accounts": { "total": 0, "connected": 0 },
  "setup": { "done": 0, "total": 7 },
  "created_at": "2026-10-06T14:00:00Z",
  "updated_at": "2026-10-06T14:00:00Z"
}
```

A resposta é a nova creator (`201`). Ela começa com identidade e persona vazias, sem conta e sem brain: o contador `setup` mostra o que falta, igual ao cartão Setup no Console. Se faltar o `name`, retorna `400`.

### Buscar uma creator

`GET /creators/{id}` · `can_setup` ou `can_fan_read`

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

A resposta é o objeto creator. Um id desconhecido retorna `404`.

### Atualizar uma creator

`PATCH /creators/{id}` · `can_setup`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `name` | string | Não | Novo nome |
| `timezone` | string | Não | Fuso horário IANA |
| `brain_id` | string ou null | Não | O brain para vincular; `null` desvincula |

```bash
curl -X PATCH https://api.lanachat.ai/v1/creators/cr_lea \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"timezone": "Europe/Madrid", "brain_id": "br_lea_main"}'
```

A resposta é a creator atualizada. Um `brain_id` de outro workspace retorna `404`.

### Pausar e retomar

`POST /creators/{id}/pause` e `POST /creators/{id}/resume` · `can_setup`

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

Pausar desativa a IA em todas as contas dela de uma vez; `resume` ativa novamente. Ambos retornam o objeto creator com o novo status.

### Arquivar uma creator

`DELETE /creators/{id}` · `can_setup`

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

A resposta é a creator com `status: "archived"`. Os fãs e vendas dela são mantidos e continuam contando nas suas estatísticas.

## Identity

### Buscar a identidade

`GET /creators/{id}/identity` · `can_setup`

```bash
curl https://api.lanachat.ai/v1/creators/cr_lea/identity \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

A resposta tem os mesmos campos da identidade abaixo.

### Substituir a identidade

`PUT /creators/{id}/identity` · `can_setup`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `first_name` | string | Não | Primeiro nome dela, como os fãs conhecem |
| `nicknames` | array of strings | Não | Apelidos que ela responde |
| `date_of_birth` | string | Não | `YYYY-MM-DD`; ela deve ter 18 anos ou mais |
| `nationality` | string | Não | Código de país com duas letras, por exemplo `FR` |
| `languages` | array of strings | Não | Idiomas que ela fala, por exemplo `["fr", "en"]` |

```bash
curl -X PUT https://api.lanachat.ai/v1/creators/cr_lea/identity \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"first_name": "Lea", "nicknames": ["Lele"], "date_of_birth": "2001-04-12", "nationality": "FR", "languages": ["fr", "en"]}'
```

```json
{
  "first_name": "Lea",
  "nicknames": ["Lele"],
  "date_of_birth": "2001-04-12",
  "zodiac_sign": "aries",
  "nationality": "FR",
  "languages": ["fr", "en"]
}
```

`zodiac_sign` é calculado a partir da data de nascimento. Uma creator menor de 18 anos é recusada (`400`). O `PUT` substitui todo o cartão: um campo que você omitir será esvaziado.

## Persona

A persona tem as mesmas oito páginas do Console: `appearance`, `life`, `voice`, `mimic`, `personality`, `memory`, `boundaries`, `examples`. Cada página é um objeto com campos de texto; o `PATCH` altera só as páginas enviadas.

### Buscar a persona

`GET /creators/{id}/persona` · `can_engine`

```bash
curl https://api.lanachat.ai/v1/creators/cr_lea/persona \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

A resposta tem o mesmo formato abaixo, com todas as oito páginas.

### Alterar páginas da persona

`PATCH /creators/{id}/persona` · `can_engine`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `appearance`, `life`, `voice`, `mimic`, `personality`, `memory`, `boundaries`, `examples` | object | Pelo menos uma | As páginas a alterar; as outras permanecem |

```bash
curl -X PATCH https://api.lanachat.ai/v1/creators/cr_lea/persona \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"voice": {"style": "Short, warm, a few emojis, never formal.", "phrase_bank": [{"trigger": "Are you a bot?", "reply": "Haha no, just slow at typing"}]}}'
```

```json
{
  "complete_percent": 64,
  "pages": {
    "voice": { "style": "Short, warm, a few emojis, never formal.", "phrase_bank": [ { "trigger": "Are you a bot?", "reply": "Haha no, just slow at typing" } ], "complete": true },
    "mimic": { "enabled": false, "lines": [], "complete": false }
  },
  "reply_language": "fr"
}
```

> Tip: A persona alimenta todos os brains vinculados à creator. Altere em um horário tranquilo e teste o brain no [Playground](https://lanachat.ai/guides/pt/api-ai-brains/) antes do pico.

## Progresso do setup

### Buscar o cartão Setup

`GET /creators/{id}/setup` · `can_setup`

```bash
curl https://api.lanachat.ai/v1/creators/cr_lea/setup \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

A resposta lista cada etapa do cartão Setup do Console e se está concluída. O `setup` no objeto creator mostra o mesmo progresso como contador (`done` de `total`).

## Artigos relacionados

- [API LanaChat: início rápido, autenticação e erros](https://lanachat.ai/guides/pt/api-overview/)
- [Adicionar uma criadora](https://lanachat.ai/guides/pt/add-a-creator/)
- [Configurações da criadora (persona, preços, idioma)](https://lanachat.ai/guides/pt/creator-settings/)