# API LanaChat: início rápido, autenticação e erros

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

Tudo o que sua equipe faz no Console, seu código também pode fazer. A API LanaChat lê e altera todo o seu workspace: criadoras, contas do Telegram, AI Brains, scripts, o Vault, fãs e conversas, links de rastreamento, faturamento e sua equipe. É JSON puro sobre HTTPS, uma URL por recurso, com as mesmas permissões do Console. Webhooks enviam eventos para seu servidor, e o servidor MCP permite que um assistente de IA como Claude ou Cursor trabalhe no seu workspace com o mesmo token.

> Note: Esta é a referência pública da API. Endpoints marcados como **Planned** são o contrato publicado a partir do qual o backend é construído: eles ainda não respondem. A [conexão MCP](https://lanachat.ai/guides/pt/api-mcp/) usa os mesmos tokens de acesso.

## O que você pode construir

- Um painel de vendas nas suas próprias ferramentas: receita do dia por criadora, por link, por fonte.
- Alertas no Slack ou Telegram quando um fã compra, quando uma conversa precisa de revisão ou quando uma conta perde a conexão.
- Um script de configuração que adiciona uma criadora, conecta suas contas, envia seu Vault e escreve seu primeiro script.
- Um pipeline de rastreamento: crie um link por anúncio, leia cliques, conversas e compradores a cada hora.
- Um assistente de IA que elabora scripts e mudanças de persona para você revisar, via [MCP](https://lanachat.ai/guides/pt/api-mcp/).

## Início rápido em 5 minutos

1. No Console, abra **Users › API & MCP** e clique em **Create token**.
2. Dê um nome (por exemplo "Reporting script"), escolha **Custom permissions** e marque o que for necessário, por exemplo **Read fans and conversations** e **Read sales**.
3. Salve, depois clique em **Copy token**. O token é mostrado uma única vez.

**4. Guarde-o em uma variável de ambiente**, para que nunca fique no seu código:

```bash
export LANACHAT_TOKEN="lc_live_8f2c1d0e9b7a4c6f"
```

**5. Faça sua primeira chamada.** Ela retorna seu workspace e o que o token pode fazer:

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

```js
const res = await fetch('https://api.lanachat.ai/v1/workspace', {
  headers: { Authorization: `Bearer ${process.env.LANACHAT_TOKEN}` },
});
if (!res.ok) throw new Error((await res.json()).error.message);
const workspace = await res.json();
console.log(workspace.name, workspace.token.permissions);
```

```python
import os
import requests

r = requests.get(
    "https://api.lanachat.ai/v1/workspace",
    headers={"Authorization": f"Bearer {os.environ['LANACHAT_TOKEN']}"},
    timeout=30,
)
r.raise_for_status()
print(r.json()["name"])
```

```json
{
  "id": "ws_7Hq2",
  "name": "Mia Agency",
  "kind": "agency",
  "timezone": "Europe/Paris",
  "token": { "id": "tok_31", "name": "Reporting script", "permissions": ["can_fan_read", "can_sales_read"], "expires_at": "2027-01-06T00:00:00Z" }
}
```

É isso: todos os outros endpoints funcionam da mesma forma. Scripts prontos estão em [API quick recipes](https://lanachat.ai/guides/pt/api-recipes/).

## Todos os recursos

| Resource | O que cobre | Guia |
|---|---|---|
| Workspace | `GET /workspace`: o workspace e as permissões do token | Esta página |
| Creators | Criadoras, identidade, persona e progresso da configuração | [Creators](https://lanachat.ai/guides/pt/api-creators/) |
| Telegram accounts | Contas, pools, configurações de pool e stories | [Telegram accounts](https://lanachat.ai/guides/pt/api-telegram-accounts/) |
| AI Brains | Brains, rascunhos, publicação, versões e Playground | [AI Brains](https://lanachat.ai/guides/pt/api-ai-brains/) |
| Scripts | Scripts, etapas e pastas | [Scripts](https://lanachat.ai/guides/pt/api-scripts/) |
| Vault | Mídia, pastas e uploads assinados | [Vault](https://lanachat.ai/guides/pt/api-vault/) |
| Fans and conversations | Fãs, listas, vendas de um fã, mensagens, takeover | [Conversations](https://lanachat.ai/guides/pt/api-conversations/) |
| Tracking | Links, domínios, pixels, eventos e estatísticas | [Tracking](https://lanachat.ai/guides/pt/api-tracking/) |
| Billing | Saldo, extrato, depósitos, licenças, retiradas, faturas | [Billing](https://lanachat.ai/guides/pt/api-billing/) |
| Team | Membros, funções e tokens de acesso | [Team](https://lanachat.ai/guides/pt/api-team/) |
| Webhooks | Eventos enviados para seu servidor, assinaturas e tentativas | [Webhooks](https://lanachat.ai/guides/pt/api-webhooks/) |
| MCP | O servidor para assistentes de IA e suas ferramentas | [MCP](https://lanachat.ai/guides/pt/api-mcp/) |

## URL base e versões

Todo caminho nestes guias é relativo a:

```text
https://api.lanachat.ai/v1
```

A versão está no caminho. Uma mudança que quebra compatibilidade recebe uma nova versão (`/v2`); novos campos e endpoints são adicionados ao `/v1` sem aviso, então ignore os campos que você não conhece.

## Autenticação

Cada requisição carrega seu token no cabeçalho `Authorization`, após a palavra `Bearer`:

```text
Authorization: Bearer lc_live_8f2c1d0e9b7a4c6f
```

- Crie, edite, rotacione e revogue tokens em **Users › API & MCP**, ou com os [endpoints de token](https://lanachat.ai/guides/pt/api-team/). Apenas o dono do workspace e donos de agências podem abrir essa página.
- Um token é mostrado uma única vez, quando você o cria. Armazene-o como uma senha; **Rotate** ou **Revoke** ele na mesma página.
- Uma requisição sem token válido responde `401`. Um token sem a permissão que o endpoint precisa responde `403`.
- Tokens nunca vão em URLs ou código no navegador: chame a API do seu servidor.
- Use um token por script ou assistente, para que cada um possa ser alterado ou revogado individualmente.

## Workspaces

Um token pertence a um workspace, aquele em que foi criado. Cada requisição lê e escreve apenas nesse workspace; não há id de workspace nos caminhos. Um token de owner (o workspace que gerencia várias agências) pode agir em uma de suas agências com o cabeçalho `LanaChat-Workspace: ws_…`; qualquer outro token que enviar esse cabeçalho recebe `403`.

## Permissões

Cada endpoint lista a permissão que precisa. São as que você marca ao criar um token:

| Permission | No Console | Dá acesso a |
|---|---|---|
| `can_setup` | Gerenciar configuração do workspace | Criadoras, mídia, contas do Telegram, scripts e membros da equipe |
| `can_engine` | Acessar configuração de IA | Rascunhos do AI Brain, configurações e testes de IA dos scripts |
| `can_publish` | Publicar rascunhos do AI Brain | Publicar um rascunho de brain (precisa de `can_engine`) |
| `can_ai_test` | Testar rascunhos de IA Avançada | Testar rascunhos que usam IA Avançada (só workspace owner) |
| `can_ai_tune` | Ajustar configurações de IA Avançada | Alterar sensibilidade da IA Avançada (só workspace owner) |
| `can_ai_publish` | Publicar perfis de IA Avançada | Publicar perfis que usam IA Avançada (só workspace owner) |
| `can_commercial_reports` | Ler relatórios de experimentos comerciais | Experimentos e seus relatórios de revisão (só workspace owner) |
| `can_fan_read` | Ler fãs e conversas | Fãs, conversas e mensagens, somente leitura |
| `can_fan_import` | Importar histórico de fãs | Importar fãs e mensagens antigas |
| `can_sales_read` | Ler vendas | Vendas, estatísticas e números do painel |
| `can_chat` | Novo: Conversar com fãs | Enviar mensagens, reações e assumir conversas |
| `can_tracking` | Novo: Gerenciar rastreamento | Links, domínios, pools, pixels e eventos |
| `owner` | Token owner | Faturamento, funções, webhooks e tokens de acesso; só o dono do workspace pode criar |

- Desativar **Access AI configuration** (`can_engine`) também desativa publicação, IA Avançada e relatórios de experimentos.
- `can_chat`, `can_tracking` e o token `owner` são planejados: o Console ainda não os oferece.

## Requisições e respostas

- Corpos são JSON (`Content-Type: application/json`), em UTF-8. Uploads passam por uma [URL assinada](https://lanachat.ai/guides/pt/api-vault/), nunca pela API diretamente.
- Ids são strings com prefixo que indica o tipo: `cr_` criadora, `acc_` conta Telegram, `pool_`, `sto_` story, `br_` brain, `scr_` script, `med_` mídia, `fan_`, `conv_` conversa, `msg_`, `lnk_` link, `px_` pixel, `mem_` membro, `tok_` token.
- Horários são ISO 8601 em UTC (`2026-10-06T14:05:00Z`). Dias em estatísticas são dias UTC.
- Dinheiro está em centavos de dólar (`amount_cents: 1900` é $19,00). Telegram Stars são números inteiros (`stars: 250`).
- `PATCH` altera apenas os campos enviados. `PUT` substitui o objeto inteiro.
- Um `POST` que cria algo responde `201` com o novo objeto; outras chamadas bem-sucedidas respondem `200`.

## Paginação

Cada lista responde uma página e um cursor para a próxima:

```bash
curl "https://api.lanachat.ai/v1/fans?limit=50&cursor=eyJpZCI6ImZhbl85MjAifQ" \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

```json
{
  "data": [ { "id": "fan_921", "display_name": "Marco", "creator_id": "cr_lea" } ],
  "next_cursor": "eyJpZCI6ImZhbl85NzAifQ"
}
```

- `limit` é de 1 a 100, 25 por padrão.
- `next_cursor` é `null` na última página. Um cursor é opaco: passe-o de volta como está, nunca crie um.
- Listas são ordenadas do mais novo para o mais antigo, salvo indicação contrária.

Para ler todas as páginas, faça um loop até `next_cursor` ser `null`:

```js
async function all(path) {
  const items = [];
  let cursor = null;
  do {
    const url = new URL('https://api.lanachat.ai/v1' + path);
    url.searchParams.set('limit', '100');
    if (cursor) url.searchParams.set('cursor', cursor);
    const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.LANACHAT_TOKEN}` } });
    if (!res.ok) throw new Error((await res.json()).error.message);
    const page = await res.json();
    items.push(...page.data);
    cursor = page.next_cursor;
  } while (cursor);
  return items;
}

const fans = await all('/fans?creator_id=cr_lea');
```

```python
import os
import requests

def all_items(path, **params):
    items, cursor = [], None
    while True:
        r = requests.get(
            "https://api.lanachat.ai/v1" + path,
            params={**params, "limit": 100, **({"cursor": cursor} if cursor else {})},
            headers={"Authorization": f"Bearer {os.environ['LANACHAT_TOKEN']}"},
            timeout=30,
        )
        r.raise_for_status()
        page = r.json()
        items += page["data"]
        cursor = page["next_cursor"]
        if not cursor:
            return items

fans = all_items("/fans", creator_id="cr_lea")
```

## Erros

Um erro responde com status 4xx ou 5xx e sempre o mesmo corpo:

```json
{
  "error": {
    "code": "insufficient_balance",
    "message": "Your balance is $12.40 and this pack costs $170.00. Top up first."
  }
}
```

| Status | `code` | Quando |
|---|---|---|
| 400 | `invalid_request` | Um campo está faltando ou com formato errado; `message` diz qual |
| 401 | `unauthorized` | Sem token, ou token revogado ou expirado |
| 402 | `insufficient_balance` | Saldo insuficiente para uma compra |
| 403 | `forbidden` | Token sem permissão necessária para o endpoint |
| 404 | `not_found` | O id não existe neste workspace |
| 409 | `conflict` | A mudança violaria uma regra (slug duplicado, última conta de envio de uma criadora) |
| 429 | `rate_limited` | Muitas requisições; aguarde os segundos indicados em `Retry-After` |
| 500 | `server_error` | Falha do nosso lado; tente novamente depois com a mesma `Idempotency-Key` |

`message` é uma frase em inglês simples que você pode mostrar para uma pessoa. Faça seu código agir conforme `code`, nunca conforme `message`.

## Limites de taxa

Cada token pode enviar **600 requisições por minuto**. Cada resposta traz `RateLimit-Limit`, `RateLimit-Remaining` e `RateLimit-Reset` (segundos até a janela reiniciar). Acima do limite, a API responde `429` com o cabeçalho `Retry-After`. Enviar mensagem para um fã também está sujeito aos limites do Telegram: veja as [regras dos pools](https://lanachat.ai/guides/pt/api-telegram-accounts/).

Um pequeno helper que espera e tenta novamente em `429` e `5xx`:

```js
async function lanachat(method, path, body) {
  const key = crypto.randomUUID();   // one key per action: a retry never does the work twice
  for (let attempt = 0; attempt < 5; attempt++) {
    const res = await fetch('https://api.lanachat.ai/v1' + path, {
      method,
      headers: {
        Authorization: `Bearer ${process.env.LANACHAT_TOKEN}`,
        'Content-Type': 'application/json',
        ...(method === 'POST' ? { 'Idempotency-Key': key } : {}),
      },
      body: body ? JSON.stringify(body) : undefined,
    });
    if (res.status === 429 || res.status >= 500) {
      const wait = Number(res.headers.get('Retry-After')) || 2 ** attempt;
      await new Promise((r) => setTimeout(r, wait * 1000));
      continue;
    }
    const data = await res.json();
    if (!res.ok) throw Object.assign(new Error(data.error.message), { code: data.error.code, status: res.status });
    return data;
  }
  throw new Error('LanaChat API: too many retries');
}
```

Use em todo lugar: `await lanachat('GET', '/creators')`, `await lanachat('POST', '/links', { … })`.

## Idempotência

Envie o cabeçalho `Idempotency-Key` (qualquer string única até 255 caracteres, um UUID serve) em todo `POST`. Se a mesma chave chegar dentro de 24 horas, a API responde o primeiro resultado novamente em vez de fazer o trabalho duas vezes: um erro de rede nunca envia uma mensagem ou compra um pacote duas vezes.

```bash
curl -X POST https://api.lanachat.ai/v1/billing/licences/buy \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: 4b7f2a8e-1c3d-4e5f-9a0b-6c7d8e9f0a1b" \
  -H "Content-Type: application/json" \
  -d '{"pack": 10, "qty": 1}'
```

A mesma chave com corpo diferente responde `409`. No shell, `$(uuidgen)` gera uma chave nova para cada ação.

## Webhooks

Em vez de perguntar à API a cada minuto, deixe LanaChat chamar você. Um webhook envia um `POST` HTTPS para seu servidor quando um fã escreve pela primeira vez, compra, é reembolsado, quando uma mídia está pronta ou uma conta perde conexão. Cada entrega é assinada (HMAC-SHA256) e tentada por 24 horas. Os eventos, payloads e a verificação da assinatura em Node e Python estão em [Webhooks](https://lanachat.ai/guides/pt/api-webhooks/).

## MCP para assistentes de IA

MCP é um padrão aberto que permite que um assistente de IA use ferramentas em um app. O servidor MCP da LanaChat permite que Claude, Cursor ou qualquer cliente MCP leiam suas criadoras, elaborem scripts, editem um rascunho de brain e leiam suas vendas, com o mesmo token de acesso e as mesmas permissões. No Claude Code, um comando conecta:

```bash
claude mcp add --transport http lanachat https://app.lanachat.ai/mcp \
  --header "Authorization: Bearer $LANACHAT_TOKEN"
```

A configuração para cada assistente e a lista de ferramentas estão em [API & MCP](https://lanachat.ai/guides/pt/api-mcp/).

## Artigos relacionados

- [Receitas rápidas da API: copiar, colar, executar](https://lanachat.ai/guides/pt/api-recipes/)
- [API & MCP: conecte um assistente de IA](https://lanachat.ai/guides/pt/api-mcp/)
- [API: webhooks, eventos e assinaturas](https://lanachat.ai/guides/pt/api-webhooks/)