엔드포인트 목록
봇이 호출할 수 있는 엔드포인트예요. 각 엔드포인트의 요청·응답 전문과 예제는 표의 명세 링크에 있어요.
공통 규칙
| 지역 | 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 한 명이라, 어느 토큰을 쓰느냐가 곧 어느 방송을 다루느냐예요.
토큰이 어느 DJ 를 가리키는지는 GET /v1/me 로 확인할 수 있어요.
응답이 실패일 때의 형식과 detailCode 는 에러 코드 에 있어요.
OAuth 엔드포인트 둘만 형식이 달라요.
인증
| 메서드 | 경로 | 하는 일 | 필요한 권한 | 성공 | 명세 |
|---|---|---|---|---|---|
POST | /v1/oauth/token | code 를 토큰으로 바꾸거나 토큰을 갱신해요. | 없음 (Client Secret 인증) | 200 | 토큰 |
POST | /v1/oauth/revoke | 발급받은 토큰을 무효화해요. | 없음 (Client Secret 인증) | 200 | 토큰 |
내 정보
| 메서드 | 경로 | 하는 일 | 필요한 권한 | 성공 | 명세 |
|---|---|---|---|---|---|
GET | /v1/me | 이 토큰이 가리키는 DJ 의 식별자를 조회해요. 방송 중이 아니어도 돼요. | me.read | 200 | DJ 식별자 조회 |
방송 조회
| 메서드 | 경로 | 하는 일 | 필요한 권한 | 성공 | 명세 |
|---|---|---|---|---|---|
GET | /v1/live | 현재 방송의 제목 · 시작/종료 시각 · 청취자 수를 조회해요. | live.read | 200 | 현재 방송 조회 |
GET | /v1/live/listeners | 지금 방에 있는 청취자를 커서로 나눠 조회해요. | listeners.read | 200 | 청취자 목록 조회 |
GET | /v1/live/fans | 이 방송의 후원 랭킹 상위 30명을 조회해요. | fans.read | 200 | 팬 랭킹 조회 |
GET | /v1/live/donations | 현재 방송에서 받은 후원 스티커 내역을 커서로 나눠 조회해요. | donations.read | 200 | 후원 내역 조회 |
실시간
| 메서드 | 경로 | 하는 일 | 필요한 권한 | 성공 | 명세 |
|---|---|---|---|---|---|
GET | /v1/live/events | 채팅 · 입장 · 하트 · 후원 · 팔로우를 SSE 로 받아요. | events.chat · events.presence · events.like · events.donation · events.follow 중 하나 이상 (presence · follow 는 DJ 의 매니저 지정도 필요) | 200 (text/event-stream) | 이벤트 스트림 |
채팅
| 메서드 | 경로 | 하는 일 | 필요한 권한 | 성공 | 명세 |
|---|---|---|---|---|---|
POST | /v1/live/chat | 봇 계정 이름으로 방송에 채팅을 보내요. | chat.send | 204 | 채팅 보내기 |
팔로우
| 메서드 | 경로 | 하는 일 | 필요한 권한 | 성공 | 명세 |
|---|---|---|---|---|---|
POST | /v1/live/follow | 봇 계정으로 이 DJ 를 팔로우해요. 봇을 고정 매니저로 받으려면 먼저 필요해요. | dj.follow | 204 | DJ 팔로우 |
알아둘 것
방송 중이 아니면 /v1/live 로 시작하는 엔드포인트는 전부 404 (OAPI_MNGR_0301) 예요.
오류가 아니라 상태예요. 빈 목록이나 빈 응답이 아니라 404 라서, 봇은 이 값 하나로
"지금 방송 중인가" 를 판단할 수 있어요.
방송 켜짐을 확인하려고 GET /v1/live 를 폴링하지 않아도 돼요. 이벤트 스트림이 방송 중이
아니면 연결 전에 404 를 주니, 스트림 연결을 재시도하는 것만으로 충분해요 —
연결 루프를 보세요.
이벤트 스트림은 같은 앱이 DJ 한 명에 하나만 열 수 있어요. 새로 연결하면 앞 연결이 end DUPLICATE_CONNECTION 으로 닫혀요 —
연결을 하나만 유지해요를 보세요.
204 를 주는 호출은 본문이 없어요. POST /v1/live/chat · POST /v1/live/follow 가 그래요.
응답 본문을 파싱하면 터지니 상태 코드만 보세요.