개발자를 위한 명료한 길잡이.

1.1 먼저 API 키를 준비하세요

작업 공간의 API 키 화면에서 키를 만든 뒤, 토큰 발급 경로를 호출합니다. 키는 발급할 때 한 번만 보입니다.

1. 앱의 /app/w/{워크스페이스}/api-keys 화면에서 API 키를 발급받습니다. 평문은 발급하는 순간에 한 번만 보이므로 그때 안전한 곳에 옮겨 두십시오.
2. 서버에서 POST /auth/token 를 호출해 1시간짜리 토큰을 받습니다.
3. 이후 요청의 Authorization: Bearer <ACCESS_TOKEN> 헤더에 받은 토큰을 싣습니다.

기준 주소 · v1

https://moacast.com/api/moacast/v1

아래 엔드포인트 절에서는 기준 주소를 생략해 적습니다.

2.1 키에서 토큰으로

1. API 키 만들기
2. 토큰 발급
3. Bearer로 호출

API 키를 요청 헤더에 직접 싣지 않습니다. 키로 한 번 토큰을 받고, 그 토큰으로 호출합니다. 키는 오래 사는 비밀이라 매 요청에 실으면 프록시 기록과 디버그 출력에 계속 남지만, 토큰은 새어 나가도 1시간이면 죽습니다.

키를 폐기하면 그 키로 만든 토큰도 다음 호출부터 막힙니다. 만료를 기다릴 필요가 없습니다.

키가 새어 나간 것으로 의심되면 앱의 API 키 화면에서 즉시 폐기하고 새 키를 발급받으십시오. 폐기한 키는 되살릴 수 없습니다.

3.1 첫 요청을 따라가 보세요

아래 값은 형식을 보여 주는 가짜 예시입니다. 실제 키와 토큰은 넣지 않았습니다.

REQUEST · bash — POST /auth/token

curl -X POST https://moacast.com/api/moacast/v1/auth/token \
  -H 'Content-Type: application/json' \
  -d '{"api_key":"mc_live_xxxxxxxxxxxx","workspace":"a1b2c3d4"}'

RESPONSE · JSON — 200 OK

{
  "result": "SUCCESS",
  "result_code": 0,
  "origin_time": 1790385521,
  "message": "토큰을 발급했습니다.",
  "data": {
    "access_token": "<ACCESS_TOKEN>",
    "token_type": "Bearer",
    "expires_in": 3600,
    "workspace": "a1b2c3d4"
  },
  "elapsed_time": "0.0291"
}

이후 요청은 Authorization: Bearer <ACCESS_TOKEN> 헤더를 사용합니다. 토큰은 한 워크스페이스에만 유효하며 1시간 뒤 만료됩니다.

curl https://moacast.com/api/moacast/v1/workspaces \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

3.2 응답 형식

모든 응답은 같은 봉투에 담깁니다. 성공과 실패를 가르는 값은 두 가지입니다 — HTTP 상태 코드와 봉투의 result 입니다.

성공

{
  "result": "SUCCESS",
  "result_code": 0,
  "origin_time": 1790385521,
  "data": {},
  "elapsed_time": "0.0291"
}

실패

{
  "result": "FAILED",
  "result_code": 1001,
  "origin_time": 1790385678,
  "message": "...",
  "elapsed_time": "0.0240"
}

실패 응답에는 data 가 없습니다. 어느 칸이 문제였는지 알려 줄 수 있을 때는 field 나 missing_params 가 봉투 맨 위에 함께 실립니다.

목록의 페이징

여러 건을 돌려주는 엔드포인트는 pagination 를 함께 줍니다. has_more 가 true 이면 다음 쪽이 있습니다.

"pagination": {
  "mode": "page",
  "page": 1,
  "limit": 20,
  "total": 1,
  "total_pages": 1,
  "has_more": false
}

4.1 요청에 필요한 값

토큰 발급을 예로 든 파라미터입니다. 각 경로의 실제 규격은 연결된 상세 문서를 확인하세요.

토큰 발급 파라미터

토큰 발급 상세 문서

5.1 실패도 읽기 쉽게

응답의 HTTP 상태와 result_code를 함께 확인합니다. 호출 한도를 넘으면 Retry-After 헤더를 따라 재시도합니다.

대표 오류

아래 표는 그 밖에 처리 중 만날 수 있는 오류와 대응 방법입니다.

4013 는 HTTP 상태 코드에 따라 뜻이 갈립니다 — 401 이면 토큰 만료이고, 409 이면 채널을 다시 연결해야 한다는 뜻입니다.

없는 대상과 권한이 없는 대상을 가려 알려 주지 않습니다. 남의 워크스페이스가 있는지 없는지가 응답으로 새지 않게 하기 위한 것입니다.

5.2 요청 한도

한도를 넘으면 429 로 답하고, 언제 다시 보내도 되는지 헤더로 알려 줍니다.

요금제에 딸린 호출 한도와 크레딧 차감은 아직 적용되지 않습니다. 적용되면 이 절에 숫자가 실립니다.

6.1 인증

발급받은 API 키를 짧게 사는 토큰으로 바꿉니다. 고객 API 의 첫 호출이고, 인증 없이 부를 수 있는 유일한 엔드포인트입니다.

• 토큰 발급 POST /auth/token

인증 묶음 전체 보기

6.2 워크스페이스

작업 공간입니다. 채널·피드·키가 모두 이 공간에 매달립니다. 토큰은 공간 하나에 묶여 발급되므로, 여기서 받은 코드가 이후 거의 모든 호출의 파라미터입니다.

• 워크스페이스 목록 GET /workspaces
• 워크스페이스 설정 저장 PUT /workspaces/{code}

워크스페이스 묶음 전체 보기

6.3 채널

워크스페이스가 연결한 플랫폼 계정입니다. 연결을 새로 만드는 일만은 API 로 할 수 없습니다 — 플랫폼의 동의 화면을 브라우저로 직접 거쳐야 하기 때문입니다.

• 연결한 채널 목록 GET /channels
• 채널 정보 새로 받기 POST /channels/sync
• 채널 연결 해제 DELETE /channels

채널 묶음 전체 보기

6.4 피드

연결한 채널에 실제로 올라가 있는 글입니다. 읽기는 받아 둔 것만 주므로 빠르고, 새로 받는 일은 따로 부릅니다.

• 피드 — 올라가 있는 글 목록 GET /feed
• 피드 새로 받기 POST /feed

피드 묶음 전체 보기

6.5 콘텐츠

올릴 것을 원장에 올리는 자리입니다. 영상은 파일까지 함께 받고, 외부 식별자를 주면 같은 요청을 다시 보내도 두 줄이 되지 않습니다. 등록과 동시에 채널별 예약을 걸 수도 있습니다.

• 콘텐츠 목록 GET /contents
• 콘텐츠 등록 POST /contents
• 콘텐츠 한 건 조회 GET /contents/{id}
• 콘텐츠 수정 PUT /contents/{id}
• 채널별 예약 저장 POST /contents/schedule

콘텐츠 묶음 전체 보기

6.6 예약

언제 무엇이 어느 채널로 나가는지를 시각 순으로 봅니다. 달력과 타임라인이 이 하나로 그려집니다.

• 예약 목록 GET /publishes

예약 묶음 전체 보기