API 개요
Cherpa Open API는 웹사이트와 외부 시스템을 Cherpa에 연결하는 REST API예요. 리소스 중심 URL을 쓰고, JSON 요청/응답과 표준 HTTP 상태 코드·메서드를 따라요.
지금 제공하는 기능은 네 가지예요.
| 기능 | 설명 |
|---|---|
| 인바운드 등록 | 웹사이트 문의 폼을 통합문의함에 접수해요 |
| 아웃바운드 등록 | 먼저 컨택할 대상을 아웃바운드 목록에 넣어요 |
| 콘텐츠 목록 | 발행된 콘텐츠를 필터·정렬해서 가져와요 |
| 콘텐츠 상세 | 발행된 콘텐츠 한 건을 가져와요 |
Base URL
https://api.cherpa.me/v1인증
모든 요청은 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": "잠시 후 다시 시도해 주세요."
}