Endpoint list
These are the endpoints a bot can call. The full request and response spec for each one, with examples, is behind the Spec link in the tables.
Shared rules
| Region | Base URL |
|---|---|
| Korea | https://kr-openapi.spooncast.net |
| Japan | https://jp-openapi.spooncast.net |
Use the address of the region your app is registered in. The DJ's account decides the
region. Every example below writes it as $SPOON_BASE_URL.
export SPOON_BASE_URL="https://kr-openapi.spooncast.net"
| Name | In | Required | Description |
|---|---|---|---|
Authorization | header | ✔ | Bearer {access_token}. The two OAuth endpoints are the exception — they use Basic. |
Content-Type | header | Only when there is a body. Bot APIs take application/json; the OAuth endpoints take application/x-www-form-urlencoded. |
The token decides which DJ's broadcast this is. Nothing in the path or the query points at a DJ. One token is one DJ's consent, so which token you use is which broadcast you are working with.
The format of a failure response and its detailCode are in
Error codes. Only the two OAuth endpoints differ.
Authentication
| Method | Path | What it does | Permission | Success | Spec |
|---|---|---|---|---|---|
POST | /v1/oauth/token | Exchange a code for tokens, or refresh them. | None (Client Secret auth) | 200 | Tokens |
POST | /v1/oauth/revoke | Invalidate a token you were issued. | None (Client Secret auth) | 200 | Tokens |
Broadcast read
| Method | Path | What it does | Permission | Success | Spec |
|---|---|---|---|---|---|
GET | /v1/live | Read the current broadcast's title, start and end times, and listener count. | live.read | 200 | Read the current broadcast |
GET | /v1/live/listeners | Page through the listeners currently in the room. | listeners.read | 200 | List listeners |
GET | /v1/live/fans | Read the top 30 donors of this broadcast. | fans.read | 200 | Read the fan ranking |
Real time
| Method | Path | What it does | Permission | Success | Spec |
|---|---|---|---|---|---|
GET | /v1/live/events | Receive chat, joins, hearts, and donations over SSE. | Any one of events.chat, events.presence, events.like, events.donation | 200 (text/event-stream) | Event stream |
Chat
| Method | Path | What it does | Permission | Success | Spec |
|---|---|---|---|---|---|
POST | /v1/live/chat | Post chat to the broadcast under the bot account's name. | chat.send | 204 | Send chat |
Things to know
When the DJ is not on air, every endpoint under /v1/live returns 404
(OAPI_MNGR_0301). That is a state, not an error. Because it is a 404 rather than an
empty list or an empty response, a bot can decide "is the DJ on air" from this alone.
You do not need to poll GET /v1/live to detect that a broadcast started. The event
stream returns 404 before connecting when the DJ is not on air, so retrying the
connection is enough — see the connection loop.
Calls that return 204 have no body. POST /v1/live/chat is one. Parsing the response body throws, so read the status code only.
Related documents
- Build a bot — a minimal end-to-end example.
- Choosing permissions — what each permission grants.
- Error codes — the format of a failure response and what to do.