API LanaChat : démarrage rapide, authentification et erreurs

Tout ce que votre équipe fait dans la Console, votre code peut aussi le faire. L’API LanaChat lit et modifie tout votre espace de travail : créatrices, comptes Telegram, AI Brains, scripts, Vault, fans et conversations, liens de suivi, facturation et votre équipe. C’est du JSON simple sur HTTPS, une URL par ressource, avec les mêmes permissions que la Console. Les webhooks poussent les événements vers votre serveur, et le serveur MCP permet à un assistant IA comme Claude ou Cursor de travailler dans votre espace avec le même token.

Ce que vous pouvez créer #

• Un tableau de bord commercial dans vos propres outils : chiffre d’affaires du jour par créatrice, par lien, par source.
• Des alertes dans Slack ou Telegram quand un fan achète, quand une conversation nécessite une revue, ou quand un compte perd sa connexion.
• Un script d’installation qui ajoute une créatrice, connecte ses comptes, télécharge son Vault et écrit son premier script.
• Un pipeline de suivi : créer un lien par publicité, lire les clics, conversations et acheteurs toutes les heures.
• Un assistant IA qui rédige des scripts et des modifications de persona pour que vous les validiez, via MCP.

Démarrage rapide en 5 minutes #

1. Dans la Console, ouvrez Users › API & MCP et cliquez sur Create token.
2. Nommez-le (par exemple "Reporting script"), choisissez Custom permissions et cochez ce dont il a besoin, par exemple Read fans and conversations et Read sales.
3. Enregistrez, puis cliquez sur Copy token. Le token est affiché une seule fois.

4. Gardez-le dans une variable d’environnement, pour qu’il ne soit jamais dans votre code :

export LANACHAT_TOKEN="lc_live_8f2c1d0e9b7a4c6f"

5. Faites votre premier appel. Il renvoie votre espace de travail et ce que le token peut faire :

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

Voilà : tous les autres endpoints fonctionnent de la même façon. Des scripts prêts à l’emploi sont dans API quick recipes.

Toutes les ressources #

URL de base et versions #

Chaque chemin dans ces guides est relatif à :

https://api.lanachat.ai/v1

La version est dans le chemin. Un changement majeur obtient une nouvelle version (/v2) ; les nouveaux champs et endpoints sont ajoutés à /v1 sans préavis, donc ignorez les champs inconnus.

Authentification #

Chaque requête porte votre token dans l’en-tête Authorization, après le mot Bearer :

Authorization: Bearer lc_live_8f2c1d0e9b7a4c6f

• Créez, modifiez, faites tourner et révoquez les tokens dans Users › API & MCP, ou avec les endpoints token. Seul le propriétaire de l’espace et les propriétaires d’agence peuvent ouvrir cette page.
• Un token est affiché une seule fois, lors de sa création. Stockez-le comme un mot de passe ; Rotate ou Revoke depuis la même page.
• Une requête sans token valide répond 401. Un token sans la permission requise répond 403.
• Les tokens ne doivent jamais être dans une URL ou dans du code navigateur : appelez l’API depuis votre serveur.
• Utilisez un token par script ou assistant, pour pouvoir les modifier ou révoquer individuellement.

Espaces de travail #

Un token appartient à un seul espace, celui où il a été créé. Chaque requête lit et écrit uniquement cet espace ; il n’y a pas d’id d’espace dans les chemins. Un token propriétaire (l’espace qui gère plusieurs agences) peut agir sur une de ses agences avec l’en-tête LanaChat-Workspace: ws_… ; tout autre token envoyant cet en-tête reçoit un 403.

Permissions #

Chaque endpoint liste la permission requise. Ce sont celles que vous cochez lors de la création d’un token :

• Désactiver Access AI configuration (can_engine) désactive aussi la publication, Advanced AI et les rapports d’expériences.
• can_chat, can_tracking et le token owner sont planifiés : la Console ne les propose pas encore.

Requêtes et réponses #

• Les corps sont en JSON (Content-Type: application/json), en UTF-8. Les uploads passent par une URL signée, jamais par l’API elle-même.
• Les ids sont des chaînes avec un préfixe indiquant leur type : cr_ créatrice, acc_ compte Telegram, pool_, sto_ story, br_ brain, scr_ script, med_ média, fan_, conv_ conversation, msg_, lnk_ lien, px_ pixel, mem_ membre, tok_ token.
• Les temps sont en ISO 8601 UTC (2026-10-06T14:05:00Z). Les jours dans les stats sont en jours UTC.
• L’argent est en cents US (amount_cents: 1900 = $19.00). Les Telegram Stars sont des nombres entiers (stars: 250).
• PATCH modifie uniquement les champs envoyés. PUT remplace l’objet entier.
• Un POST qui crée répond 201 avec le nouvel objet ; les autres appels réussis répondent 200.

Pagination #

Chaque liste répond une page et un curseur vers la suivante :

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 est de 1 à 100, 25 par défaut.
• next_cursor est null à la dernière page. Un curseur est opaque : renvoyez-le tel quel, ne le construisez jamais.
• Les listes sont triées du plus récent au plus ancien sauf indication contraire.

Pour lire toutes les pages, bouclez jusqu’à ce que next_cursor soit 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")

Erreurs #

Une erreur répond avec un statut 4xx ou 5xx et toujours le même corps :

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

message est une phrase en anglais simple que vous pouvez afficher à une personne. Branchez votre code sur code, jamais sur message.

Limites de débit #

Chaque token peut envoyer 600 requêtes par minute. Chaque réponse porte RateLimit-Limit, RateLimit-Remaining et RateLimit-Reset (secondes avant réinitialisation). Au-delà, l’API répond 429 avec un en-tête Retry-After. Envoyer un message à un fan est aussi soumis aux limites propres à Telegram : voir les règles des pools.

Un petit helper qui attend et réessaie sur 429 et 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');
}

Utilisez-le partout : await lanachat('GET', '/creators'), await lanachat('POST', '/links', { … }).

Idempotence #

Envoyez un en-tête Idempotency-Key (n’importe quelle chaîne unique jusqu’à 255 caractères, un UUID convient) à chaque POST. Si la même clé revient dans les 24 heures, l’API renvoie le premier résultat au lieu de refaire le travail deux fois : une erreur réseau n’envoie jamais un message ou n’achète un pack deux fois.

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

La même clé avec un corps différent répond 409. Dans un shell, $(uuidgen) génère une clé fraîche pour chaque nouvelle action.

Webhooks #

Au lieu d’interroger l’API chaque minute, laissez LanaChat vous appeler. Un webhook envoie un POST HTTPS à votre serveur quand un fan écrit pour la première fois, achète, est remboursé, quand un média est prêt ou qu’un compte perd sa connexion. Chaque livraison est signée (HMAC-SHA256) et réessayée pendant 24 heures. Les événements, payloads et la vérification de signature en Node et Python sont dans Webhooks.

MCP pour assistants IA #

MCP est un standard ouvert qui permet à un assistant IA d’utiliser des outils dans une app. Le serveur MCP de LanaChat permet à Claude, Cursor ou tout client MCP de lire vos créatrices, rédiger des scripts, éditer un brouillon de brain et lire vos ventes, avec le même token d’accès et les mêmes permissions. Dans Claude Code, une commande le connecte :

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

La configuration pour chaque assistant et la liste des outils sont dans API & MCP.