이 API를 사용하려면 read.karaoke 권한이 필요해요.
키는 한글이라 헤더에 넣기 전에 퍼센트 인코딩해야 해요. 인증 방법 →
노래방 목록 조회
GET
/api/v1/karaoke대기열(queue)과 완료 목록(completed), 오늘 통계(stats)를 함께 조회해요.
응답 필드
| 필드 | 타입 | 설명 |
|---|---|---|
data.queue | array | 현재 대기열 |
data.queue[].id | number | 신청 고유 ID (2026-08 추가, completed 항목에도 동일하게 포함) |
data.queue[].requester.name | string | 신청자 닉네임 (익명 신청이면 "익명" 고정) |
data.queue[].requester.uid | string | 신청자 UID (익명 신청이면 "anonymous" 고정) |
data.queue[].requester.isAnonymous | boolean | 익명 신청 여부 |
data.completed | array | 완료된 곡 목록(최대 150개). requester 는 대기열과 똑같이 익명 마스킹돼요 |
data.stats | object | 오늘 노래방 통계 |
data.stats.todayCompletedCount | number | 오늘 완료된 곡 수 |
data.stats.currentSongOrderToday | number|null | 현재 곡의 오늘 순번(대기열 없으면 null) |
eventTimestamp | number | 서버 이벤트 시각(ms) |
요청
curl -X GET "https://chzzk-bot.ddutto.com/api/v1/karaoke" \
-H "Authorization: DDUBOT_API %EB%AF%B8%EB%A6%AC-%EC%9D%B8%EC%BD%94%EB%94%A9%ED%95%9C-%ED%82%A4"응답
{
"success": true,
"data": {
"queue": [
{
"id": 501234,
"title": "대기 곡 A",
"requester": {
"name": "신청자1",
"uid": "4c3a50fe635854036b4dcf15c9a4d0a2",
"isAnonymous": false
},
"requestTime": 1769448705123,
"sortOrder": 1000,
"priority": 0,
"status": "queued"
}
],
"completed": [
{
"id": 501201,
"title": "완료 곡 Z",
"requester": {
"name": "신청자2",
"uid": "7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e",
"isAnonymous": false
},
"requestTime": 1769447600000,
"completedTime": 1769448600000,
"priority": 0,
"status": "completed"
}
],
"stats": {
"todayCompletedCount": 12,
"currentSongOrderToday": 13
}
},
"eventTimestamp": 1769448706000
}응답
{
"success": false,
"data": {
"error": "권한이 없습니다. 'read.karaoke' scope가 필요합니다."
}
}