API 사용

CastLine 의 스트림·공유 링크·외부 송출은 /api/v1 REST API 로도 다룰 수 있습니다. 요청·응답은 JSON 이고 필드 이름은 camelCase 입니다.

API 키 인증

1. 콘솔 관리 → API 키(/console/api-keys)에서 소유자가 키를 발급합니다. 키 역할은 manager(스트림·링크·송출 생성·수정·켜기·끄기) 또는 viewer(조회만) 중에서 고릅니다.
2. 키(ck_…)는 발급할 때 한 번만 보입니다. 잃어버리면 폐기하고 새로 발급하세요.
3. 모든 요청에 Authorization 헤더를 붙입니다.

• 키는 자기 고객사 자원만 다룹니다. 다른 고객사 자원은 404 NOT_FOUND 입니다.
• 등급의 API 키 한도가 0 이면 키를 발급할 수 없습니다(403 FEATURE_NOT_ALLOWED).
• 비밀번호 변경·로그인 세션 관리·탈퇴·콘솔 미리보기처럼 사람 계정이 필요한 작업은 API 키로 할 수 없습니다.
• 해지된 고객사의 키는 410 CUSTOMER_TERMINATED, 정지된 고객사의 변경 요청은 423 CUSTOMER_SUSPENDED 를 받습니다.

예약 켜기·끄기 (cron)

영업시간에만 송출하려면 서버의 스케줄러(cron 등)가 manager 역할 키로 일괄 켜기·끄기를 부르게 합니다(한 번에 최대 50개).

# manager 역할 API 키로 평일 09:00 켜기, 18:00 끄기
CASTLINE_KEY=ck_…
0 9 * * 1-5  curl -fsS -X POST -H "Authorization: Bearer $CASTLINE_KEY" -H "Content-Type: application/json" -d '{"ids":["<streamId>"],"action":"on"}' https://castline.dotoritos.net/api/v1/streams/bulk
0 18 * * 1-5 curl -fsS -X POST -H "Authorization: Bearer $CASTLINE_KEY" -H "Content-Type: application/json" -d '{"ids":["<streamId>"],"action":"off"}' https://castline.dotoritos.net/api/v1/streams/bulk

일괄 요청은 항목별 결과를 207 Multi-Status 로 돌려줍니다. 일부만 실패할 수 있으니 ok 가 false 인 항목의 error.code 를 확인하세요.

{
  "data": {
    "results": [
      { "id": "<streamId>", "ok": true },
      { "id": "<streamId2>", "ok": false, "error": { "code": "RESOURCE_LOCKED", "message": "관리자가 잠근 자원입니다." } }
    ]
  }
}

응답과 오류 형식

성공하면 {"data": …, "meta": {…}} 를, 실패하면 아래 형식을 돌려줍니다. message 는 사람이 읽는 한국어 문구이고, 프로그램은 code 로만 분기하세요. 모든 응답에는 X-CastLine-Request-Id 헤더가 있으며, 문의할 때 이 값(requestId)을 알려 주면 빠르게 찾을 수 있습니다.

{
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "동시 활성 스트림 한도(5개)를 초과했습니다.",
    "details": { "limitKey": "max_active_streams", "limit": 5, "current": 5, "requested": 1 },
    "requestId": "req_…"
  }
}

• 수정 가능한 자원은 version 을 돌려줍니다. PATCH 에 If-Match: <version> 을 보내면 그 사이 다른 사람이 바꿨을 때 409 VERSION_CONFLICT 로 알려 줍니다.
• 목록의 알 수 없는 쿼리 파라미터와 본문 필드는 422 VALIDATION_FAILED(rule=unknown_field) 입니다.

오류 코드

속도 제한

한도를 넘으면 429 RATE_LIMITED 와 Retry-After 헤더(초)를 받습니다. 그 시간만큼 기다린 뒤 다시 시도하세요. 같은 스트림의 “다시 연결”(POST /streams/{id}/resync)은 30초에 한 번입니다.

페이지네이션과 정렬

목록은 커서 방식입니다. limit 은 기본 20, 최대 100 이고, 응답의 meta.nextCursor 를 다음 요청의 cursor 로 넘깁니다. nextCursor 가 null 이면 마지막 페이지입니다. 커서는 그 목록 전용이라 다른 목록이나 조건에 쓰면 422(rule=invalid_cursor)입니다.

정렬은 sort=<필드>:asc 또는 sort=<필드>:desc 로 지정합니다(예: sort=name:asc). 목록마다 정렬할 수 있는 필드가 정해져 있고, 그 밖의 값은 422 입니다.