# Live API 가이드

Kollus Live는 외부 시스템과의 데이터 연동을 위해 RESTful API를 제공합니다.
이 가이드에서는 요청 규격과 인증 방식을 설명합니다. 예제를 참고하여 개발 환경을 구성할 수 있습니다.

## 요청 규격

### 호출 제한

1분당 최대 60회 호출 가능합니다. 연속 호출 시 최소 1초 이상의 간격을 유지해 주세요.

### 요청 헤더

HTTP Method에 따라 Accept 헤더와 Content-Type을 지정해야 합니다.

| HTTP Method | Accept 헤더 | Content-Type |
|  --- | --- | --- |
| **`GET` / `DELETE`** | `application/json` | - |
| **`POST` / `PUT`** | `application/json` | `application/x-www-form-urlencoded` |


### 인증 방식

모든 API 요청은 OAuth2 사양을 준수하며, 요청 헤더에 Bearer Token을 포함해야 합니다.

1. Kollus Live 콘솔에서 [설정] > [기본 정보] > [서비스 계정] 탭으로 이동합니다.
2. 하단 `[Personal Access Tokens]` 섹션에서 `[Create New Token]`을 클릭합니다.

3. 토큰 이름을 입력하고 필요한 Scopes를 체크한 뒤 `[저장]`을 클릭합니다.

각 API의 필요 Scope는 API 레퍼런스의 Security 항목에서 확인할 수 있습니다.

4. 생성된 토큰은 보안상 이후 다시 조회할 수 없습니다. 토큰을 즉시 복사하여 안전한 곳에 저장하세요.



### 요청 예시

#### 채널 정보 조회


```curl
curl -X GET "https://api-live-kr.kollus.com/api/v1/live/service-accounts/{SERVICE_ACCOUNT_KEY}/channels/{CHANNEL_KEY}/broadcasts?order=id_desc&page=1&per_page=10" -H "accept: application/json" -H "Authorization: Bearer accesstoken...."
```

### 서비스 계정 역할 및 권한

서비스 계정에 부여된 역할에 따라 사용 가능한 기능과 접근 범위가 달라집니다. 역할별 상세 권한은 서비스 계정 역할 및 권한 문서를 참고하세요.

### 키(Key) 정보

요청 URL에 포함되는 키 정보는 인증 및 주요 키 문서를 참고하세요.

## 예제

### 채널 생성 (POST)


```js
// Implementation using axios

import axios from "axios";

const url =
  "https://api-live-kr.kollus.com/api/v1/live/service-accounts/{SERVICE_ACCOUNT_KEY}/channels";

const body = new URLSearchParams({
  title: "test-channel",
  customer_code: "catenoidtest",
  concurrently_viewer_limit: 100,
  is_shared: 1,
  live_media_profile_group_key: "{ENCODING_PROFILE_KEY}"
});

axios.post(url, body.toString(), {
  headers: {
    Accept: "application/json",
    "Content-Type": "application/x-www-form-urlencoded",
    Authorization: "Bearer {ACCESS_TOKEN}"
  }
})
.then(response => {
  console.log("Channel created successfully:", response.data);
})
.catch(error => {
  console.error(
    "Failed to create channel:",
    error.response?.data || error.message
  );
});
```

### 채널 내 방송 조회 (GET)


```js
// Implementation using fetch API

const url = "https://api-live-kr.kollus.com/api"
+ "/v1/live/service-accounts/{SERVICE_ACCOUNT_KEY}/channels/{CHANNEL_KEY}/broadcasts?order=id_desc&page=1&per_page=10";

fetch(url, {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer {ACCESS_TOKEN}"
  }
})
  .then(response => {
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    return response.json();
  })
  .then(data => {
    console.log("Response Data:", data);
  })
  .catch(error => {
    console.error("Request failed:", error);
  });
```