엔드포인트 목록
봇이 호출할 수 있는 엔드포인트예요. 각 엔드포인트의 요청·응답 전문과 예제는 표의 명세 링크에 있어요.
공통 규칙
| 지역 | base URL |
|---|---|
| 한국 | https://kr-openapi.spooncast.net |
| 일본 | https://jp-openapi.spooncast.net |
내 앱이 등록된 지역의 주소를 써요. 어느 지역인지는 DJ 계정이 정해요.
아래 예제는 모두 $SPOON_BASE_URL 로 적었어요.
export SPOON_BASE_URL="https://kr-openapi.spooncast.net"
| 이름 | 위치 | 필수 | 설명 |
|---|---|---|---|
Authorization | header | ✔ | Bearer {access_token} 이에요. OAuth 엔드포인트 둘만 예외로 Basic 을 써요. |
Content-Type | header | 본문이 있을 때만 붙여요. 봇 API 는 application/json, OAuth 엔드포인트는 application/x-www-form-urlencoded 예요. |
어느 DJ 의 방송인지는 토큰이 정해요. 경로에도 쿼리에도 DJ 를 지목하는 자리가 없어요. 토큰 하나가 동의한 DJ 한 명이라, 어느 토큰을 쓰느냐가 곧 어느 방송을 다루느냐예요.
응답이 실패일 때의 형식과 detailCode 는 에러 코드 에 있어요.
OAuth 엔드포인트 둘만 형식이 달라요.
인증
| 메서드 | 경로 | 하는 일 | 필요한 권한 | 성공 | 명세 |
|---|---|---|---|---|---|
POST | /v1/oauth/token | code 를 토큰으로 바꾸거나 토큰을 갱신해요. | 없음 (Client Secret 인증) | 200 | 토큰 |
POST | /v1/oauth/revoke | 발급받은 토큰을 무효화해요. | 없음 (Client Secret 인증) | 200 | 토큰 |
방송 조회
| 메서드 | 경로 | 하는 일 | 필요한 권한 | 성공 | 명세 |
|---|---|---|---|---|---|
GET | /v1/live | 현재 방송의 제목 · 시작/종료 시각 · 청취자 수를 조회해요. | live.read | 200 | 현재 방송 조회 |
GET | /v1/live/listeners | 지금 방에 있는 청취자를 커서로 나눠 조회해요. | listeners.read | 200 | 청취자 목록 조회 |
GET | /v1/live/fans | 이 방송의 후원 랭킹 상위 30명을 조회해요. | fans.read | 200 | 팬 랭킹 조회 |
실시간
| 메서드 | 경로 | 하는 일 | 필요한 권한 | 성공 | 명세 |
|---|---|---|---|---|---|
GET | /v1/live/events | 채팅 · 입장 · 하트 · 후원을 SSE 로 받아요. | events.chat · events.presence · events.like · events.donation 중 하나 이상 | 200 (text/event-stream) | 이벤트 스트림 |
채팅
| 메서드 | 경로 | 하는 일 | 필요한 권한 | 성공 | 명세 |
|---|---|---|---|---|---|
POST | /v1/live/chat | 봇 계정 이름으로 방송에 채팅을 보내요. | chat.send | 204 | 채팅 보내기 |
알아둘 것
방송 중이 아니면 /v1/live 로 시작하는 엔드포인트는 전부 404 (OAPI_MNGR_0301) 예요.
오류가 아니라 상태예요. 빈 목록이나 빈 응답이 아니라 404 라서, 봇은 이 값 하나로
"지금 방송 중인가" 를 판단할 수 있어요.
방송 켜짐을 확인하려고 GET /v1/live 를 폴링하지 않아도 돼요. 이벤트 스트림이 방송 중이
아니면 연결 전에 404 를 주니, 스트림 연결을 재시도하는 것만으로 충분해요 —
연결 루프를 보세요.
204 를 주는 호출은 본문이 없어요. POST /v1/live/chat 이 그래요.
응답 본문을 파싱하면 터지니 상태 코드만 보세요.