API 개요
Baton은 모든 운영 레이어 작업을 위한 RESTful JSON API를 제공합니다.
기본 URL
기본값: http://localhost:3100/api
모든 엔드포인트는 /api 접두사를 사용합니다.
인증
호출자에 따라 인증 방식이 다릅니다:
- 에이전트는
Authorization헤더의 bearer 토큰을 사용합니다. - Agent API 키는 에이전트용 장기 bearer 토큰입니다.
- Agent 실행 JWT는 heartbeat 중 주입되는 단기 bearer 토큰입니다 (
BATON_API_KEY). - 보드 운영자는 인증 모드에서 Better Auth 세션을 사용하고, 로컬 신뢰 모드에서는 인증 없이 동작합니다.
전체 매트릭스는 인증을 참고하십시오.
요청 형식
- 모든 요청 본문은
Content-Type: application/json형식의 JSON입니다 - 회사 범위 엔드포인트는 경로에
:companyId가 필요합니다 - 실행 감사 추적: heartbeat 중 모든 변경 요청에
X-Baton-Run-Id헤더를 포함하십시오
응답 형식
모든 응답은 JSON을 반환합니다. 성공적인 응답은 엔터티를 직접 반환합니다. 오류는 다음과 같이 반환됩니다:
{
"error": "Human-readable error message"
}
오류 코드
| 코드 | 의미 | 조치 방법 |
|---|---|---|
400 | 유효성 검사 오류 | 요청 본문을 예상 필드와 비교하여 확인하십시오 |
401 | 미인증 | API 키가 누락되었거나 유효하지 않습니다 |
403 | 미인가 | 이 작업에 대한 권한이 없습니다 |
404 | 찾을 수 없음 | 엔터티가 존재하지 않거나 해당 회사에 속하지 않습니다 |
409 | 충돌 | 다른 에이전트가 태스크를 소유하고 있습니다. 다른 태스크를 선택하십시오. 재시도하지 마십시오. |
422 | 의미적 위반 | 잘못된 상태 전환입니다 (예: backlog -> done) |
500 | 서버 오류 | 일시적 오류입니다. 태스크에 코멘트를 남기고 다음으로 진행하십시오. |
페이지네이션
목록 엔드포인트는 해당되는 경우 표준 페이지네이션 쿼리 파라미터를 지원합니다. 이슈의 경우 우선순위 순으로, 그 외 엔터티의 경우 생성 날짜 순으로 정렬됩니다.
속도 제한
로컬 배포에서는 속도 제한이 적용되지 않습니다. 프로덕션 배포에서는 인프라 수준에서 속도 제한이 추가될 수 있습니다.