Documentación / API

Referencia de la API REST

Cada endpoint se encuentra bajo /api/v1 y se autentica con una clave de API desde Consola → Integraciones. Las claves se muestran una sola vez y pueden ser de solo lectura o de lectura/escritura; las claves revocadas dejan de funcionar de inmediato.

Envía la clave como Authorization: Bearer bfk_…. Los errores se devuelven como JSON de Problem Details con un code sobre el que puedes decidir según el caso.

GET/api/v1/mealcance: read

A qué espacio de trabajo y plan pertenece una clave. La forma económica de comprobar que una clave funciona.

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

GET/api/v1/bots?page=1&pageSize=50alcance: read

Lista los bots del espacio de trabajo con su estado y versión.

GET/api/v1/bots/{botId}alcance: read

Un bot: estado, zona horaria, versión, último error.

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

La audiencia del bot, buscable por nombre o nombre de usuario.

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

Registros de ejecución recientes; filtrables por nivel.

GET/api/v1/bots/{botId}/analytics?days=30alcance: read

Volumen de mensajes, fallos de entrega y crecimiento de suscriptores por día.

GET/api/v1/bots/{botId}/broadcastsalcance: read

Historial de difusiones del bot.

GET/api/v1/bots/{botId}/logs/streamalcance: read

Registros en vivo como eventos enviados por el servidor (SSE). Las entradas llegan como líneas data: en JSON de LogEntry; un comentario keepalive cada 15 s; el servidor cierra la sesión tras 10 minutos (reconectar). EventSource no puede enviar cabeceras, así que consume con streaming basado en fetch.

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

POST/api/v1/bots/{botId}/broadcastsalcance: write

Crea y encola una difusión en una sola llamada. Cuerpo: { "name": "…", "text": "…", "segmentId": "…" (opcional) }. La entrega ocurre en la misma canalización con ritmo controlado que las difusiones de la consola; se aplica el límite de tu plan.

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

Códigos de estado y límites

401 UNAUTHENTICATED — clave ausente o no válida.
403 FORBIDDEN — a la clave le falta el alcance de escritura.
403 PLAN_LIMIT — se alcanzó la cuota de difusiones; el mensaje indica el límite.
404 NOT_FOUND — id incorrecto, o un bot que pertenece a otro espacio de trabajo.
El tamaño de página tiene un límite de 100; los registros, de 200.

Referencia de la API REST

Códigos de estado y límites

Ir más profundo

Versiones, idempotencia y errores