Documentation / API

Référence de l'API REST

Chaque point de terminaison se trouve sous /api/v1 et s'authentifie avec une clé API depuis Console → Intégrations. Les clés ne sont affichées qu'une seule fois et peuvent être en lecture seule ou en lecture/écriture ; les clés révoquées cessent immédiatement de fonctionner.

Envoyez la clé sous la forme Authorization: Bearer bfk_…. Les erreurs reviennent sous forme de JSON Problem Details avec un code sur lequel vous pouvez brancher votre logique.

GET/api/v1/meportée : read

À quel espace de travail et forfait appartient une clé. Le moyen simple de vérifier qu'une clé fonctionne.

curl -H "Authorization: Bearer bfk_…" \
  https://your-domain/api/v1/me

GET/api/v1/bots?page=1&pageSize=50portée : read

Liste les bots de l'espace de travail avec leur statut et leur version.

GET/api/v1/bots/{botId}portée : read

Un bot : statut, fuseau horaire, version, dernière erreur.

GET/api/v1/bots/{botId}/subscribers?q=&page=1&pageSize=50portée : read

L'audience du bot, consultable par nom ou nom d'utilisateur.

GET/api/v1/bots/{botId}/logs?level=error&limit=50portée : read

Journaux d'exécution récents ; filtrables par niveau.

GET/api/v1/bots/{botId}/analytics?days=30portée : read

Volume de messages, échecs de livraison et croissance des abonnés par jour.

GET/api/v1/bots/{botId}/broadcastsportée : read

Historique des diffusions du bot.

GET/api/v1/bots/{botId}/logs/streamportée : read

Journaux en direct sous forme d'événements envoyés par le serveur (SSE). Les entrées arrivent sous forme de lignes data: en JSON LogEntry ; un commentaire keepalive toutes les 15 s ; le serveur ferme la session après 10 minutes (reconnexion). EventSource ne peut pas envoyer d'en-têtes, il faut donc consommer via un flux basé sur fetch.

curl -N -H "Authorization: Bearer bfk_…"   https://your-domain/api/v1/bots/{botId}/logs/stream

POST/api/v1/bots/{botId}/broadcastsportée : write

Crée et met en file d'attente une diffusion en un seul appel. Corps : { "name": "…", "text": "…", "segmentId": "…" (facultatif) }. La livraison suit le même pipeline cadencé que les diffusions de la console ; la limite de votre forfait s'applique.

curl -X POST -H "Authorization: Bearer bfk_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"June promo","text":"20% off until Friday"}' \
  https://your-domain/api/v1/bots/{botId}/broadcasts

Codes de statut et limites

401 UNAUTHENTICATED — clé manquante ou invalide.
403 FORBIDDEN — la clé n'a pas la portée d'écriture.
403 PLAN_LIMIT — quota de diffusion atteint ; le message indique le plafond.
404 NOT_FOUND — identifiant erroné, ou bot appartenant à un autre espace de travail.
La taille de page est plafonnée à 100 ; les limites de journaux à 200.

Référence de l'API REST

Codes de statut et limites

Aller plus loin

Versions, idempotence et erreurs