문서 / 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

봇 하나: 상태, 시간대, 버전, 마지막 오류.

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

일별 메시지 볼륨, 전달 실패, 구독자 증가 수치.

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

한 번의 호출로 브로드캐스트를 생성하고 대기열에 추가합니다. 본문: { "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 참조

상태 코드 및 한도

더 깊이 알아보기

버전, 멱등성, 오류