Documentation / API

REST API reference

Every endpoint lives under /api/v1 and authenticates with an API key from Console → Integrations. Keys are shown once and can be read-only or read/write; revoked keys stop working immediately.

Send the key as Authorization: Bearer bfk_…. Errors come back as Problem Details JSON with a code you can switch on.

GET/api/v1/mescope: read

Which workspace and plan a key belongs to. The cheap way to check a key works.

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

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

Lists the workspace's bots with status and version.

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

One bot: status, timezone, version, last error.

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

The bot's audience, searchable by name or username.

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

Recent runtime logs; filter by level.

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

Message volume, delivery failures, and subscriber growth per day.

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

Broadcast history for the bot.

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

Live logs as Server-Sent Events. Entries arrive as data: lines of LogEntry JSON; a keepalive comment every 15s; the server closes the session after 10 minutes (reconnect). EventSource cannot send headers, so consume with fetch-based streaming.

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

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

Creates and queues a broadcast in one call. Body: { "name": "…", "text": "…", "segmentId": "…" (optional) }. Delivery happens on the same paced pipeline as console broadcasts; your plan limit applies.

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

Status codes and limits

401 UNAUTHENTICATED — missing or invalid key.
403 FORBIDDEN — the key lacks the write scope.
403 PLAN_LIMIT — broadcast quota reached; the message names the ceiling.
404 NOT_FOUND — wrong id, or a bot that belongs to another workspace.
Page sizes cap at 100; log limits at 200.