ドキュメント / API

REST APIリファレンス

すべてのエンドポイントは /api/v1 の下にあり、コンソール → インテグレーションから取得したAPIキーで認証します。キーは作成時に一度だけ表示され、読み取り専用または読み書き両方に設定できます。取り消されたキーは直ちに使用できなくなります。

キーは Authorization: Bearer bfk_…として送信してください。エラーはProblem Details形式のJSONで返され、 code で分岐処理できます。

GET/api/v1/meスコープ: read

キーがどのワークスペースとプランに属しているか。キーが機能するかを手軽に確認する方法です。

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

GET/api/v1/bots?page=1&pageSize=50スコープ: read

ワークスペースのボットをステータスとバージョンとともに一覧表示します。

GET/api/v1/bots/{botId}スコープ: read

1つのボット:ステータス、タイムゾーン、バージョン、最終エラー。

GET/api/v1/bots/{botId}/subscribers?q=&page=1&pageSize=50スコープ: read

ボットの購読者一覧。名前またはユーザー名で検索可能です。

GET/api/v1/bots/{botId}/logs?level=error&limit=50スコープ: read

最近のランタイムログ。レベルでフィルター可能です。

GET/api/v1/bots/{botId}/analytics?days=30スコープ: read

1日ごとのメッセージ量、配信失敗数、購読者の増加数。

GET/api/v1/bots/{botId}/broadcastsスコープ: read

ボットの配信履歴。

GET/api/v1/bots/{botId}/logs/streamスコープ: read

サーバー送信イベント(SSE)としてのライブログ。エントリはLogEntry形式のJSONのdata:行として届きます。15秒ごとにキープアライブのコメントが送られ、サーバーは10分後にセッションを閉じます(再接続してください)。EventSourceはヘッダーを送信できないため、fetchベースのストリーミングで受信してください。

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

POST/api/v1/bots/{botId}/broadcastsスコープ: write

1回の呼び出しで配信を作成しキューに追加します。ボディ: { "name": "…", "text": "…", "segmentId": "…"(任意) }。配信はコンソールの配信と同じペース配分のパイプラインで行われ、プランの上限が適用されます。

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

ステータスコードと上限

401 UNAUTHENTICATED — キーが存在しないか無効です。
403 FORBIDDEN — キーに書き込みスコープがありません。
403 PLAN_LIMIT — 配信のクォータに達しました。メッセージに上限値が記載されます。
404 NOT_FOUND — IDが間違っているか、別のワークスペースに属するボットです。
ページサイズは最大100件、ログは最大200件です。

REST APIリファレンス

ステータスコードと上限

さらに詳しく

バージョン、べき等性、エラー