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

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.

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.

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:

export LANACHAT_TOKEN="lc_live_8f2c1d0e9b7a4c6f"

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

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

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);

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

{
  "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.

Todos os recursos #

URL base e versões #

Todo caminho nestes guias é relativo a:

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:

Authorization: Bearer lc_live_8f2c1d0e9b7a4c6f

• Crie, edite, rotacione e revogue tokens em Users › API & MCP, ou com os endpoints de token. 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:

• 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, 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:

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

{
  "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:

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');

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:

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

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.

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

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.

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.

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:

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.