본문으로 건너뛰기

API 개요 ​

Cherpa Open API는 웹사이트와 외부 시스템을 Cherpa에 연결하는 REST API예요. 리소스 중심 URL을 쓰고, JSON 요청/응답과 표준 HTTP 상태 코드·메서드를 따라요.

지금 제공하는 기능은 네 가지예요.

기능설명
인바운드 등록웹사이트 문의 폼을 통합문의함에 접수해요
아웃바운드 등록먼저 컨택할 대상을 아웃바운드 목록에 넣어요
콘텐츠 목록발행된 콘텐츠를 필터·정렬해서 가져와요
콘텐츠 상세발행된 콘텐츠 한 건을 가져와요

인증 ​

모든 요청은 API 키로 인증해요. 콘솔 설정 → API 키 관리에서 키를 발급받아 Authorization: Bearer 헤더로 전달하세요.

키는 스페이스 하나에 묶여 있어요. 어느 스페이스의 데이터인지는 키에서 자동으로 결정되므로 따로 지정할 것이 없고, 다른 스페이스의 데이터에는 닿지 않아요.

키마다 권한을 정해 쓸 수 있는 API를 좁힐 수 있어요.

권한인바운드 등록아웃바운드 등록콘텐츠 조회
full 전체 접근✓✓✓
content 콘텐츠 읽기––✓
inquiry 문의 접수✓––
상황결과
키 누락 · 잘못된 키 · 삭제된 키401
키 권한에 없는 API 호출403
인증 헤더
bash
curl https://api.cherpa.me/v1/content/blog/entries \
  -H "Authorization: Bearer chp_..."

에러 ​

표준 HTTP 상태 코드를 사용해요. 2xx는 성공, 4xx는 요청 문제(누락된 값, 권한 없음 등), 5xx는 서버 문제예요.

상태의미
200 201성공 (조회 / 등록)
400잘못된 요청 — 값 검증 실패
401인증 필요 — API 키 누락 또는 무효
403권한 없음 — 키 권한에 없는 API
404리소스 없음
429요청이 너무 많음 — 요청 제한 초과

에러 본문은 항상 같은 모양이에요.

필드설명
code에러 종류를 나타내는 숫자 (400→3, 401→16, 403→7, 404→5, 429→8)
message사람이 읽을 수 있는 설명
detail추가 정보. 값 검증 실패(400)면 필드별 오류 배열
에러 응답 · 401
json
{
  "code": 16,
  "message": "유효하지 않은 API 키예요",
  "detail": "유효하지 않은 API 키예요"
}
값 검증 실패 · 400
json
{
  "code": 3,
  "message": "Bad Request",
  "detail": [
    { "type": "missing", "loc": ["body", "name"], "msg": "Field required" }
  ]
}

페이지네이션 ​

콘텐츠 목록은 page(1부터) · limit(기본 20, 최대 100) 쿼리 파라미터를 받고, 공통 래퍼로 응답해요.

필드설명
items현재 페이지 항목 배열
total전체 항목 수
page현재 페이지 (1부터)
limit페이지당 항목 수
total_pages전체 페이지 수
목록 응답
json
{
  "items": [{ "...": "..." }],
  "total": 42,
  "page": 1,
  "limit": 20,
  "total_pages": 3
}

요청 제한 ​

등록 API는 폭주를 막기 위해 호출 IP 기준으로 요청 수를 제한해요. 한도를 넘으면 429가 돌아오니 잠시 뒤 다시 시도하세요.

API한도
인바운드 등록같은 IP에서 10분에 10건
아웃바운드 등록같은 IP에서 1분에 60건

콘텐츠 조회에는 별도 한도가 없어요.

한도 초과 · 429
json
{
  "code": 8,
  "message": "잠시 후 다시 시도해 주세요.",
  "detail": "잠시 후 다시 시도해 주세요."
}