콘텐츠 조회
발행된 콘텐츠를 웹사이트·앱에서 가져가는 API예요. 목록과 상세 조회가 중심이고, 화면에 그릴 때 함께 쓰는 미디어 조회 · 조회수 기록이 있어요.
API 키를 Authorization: Bearer 헤더로 전달해 인증하고, 스페이스는 키에서 자동으로 결정돼요. full(전체 접근) 또는 content(콘텐츠 읽기) 권한 키로 호출할 수 있어요.
published 상태의 엔트리만 노출돼요. 발행 후 수정 중인 엔트리(changed)는 계속 노출되며, 이때는 수정 중인 현재 값이 반환돼요. 초안·예약·보관 상태는 404예요.
:content_type은 콘텐츠 타입의 api_id예요 (예: blog). 콘솔에서 콘텐츠 종류를 만들 때 정한 슬러그가 이 값이에요.
curl https://api.cherpa.me/v1/content/blog/entries \
-H "Authorization: Bearer chp_..."엔트리 객체
콘텐츠 한 건(엔트리)을 나타내요. 상태·조회수 같은 내부 필드는 포함되지 않아요.
| 속성 | 설명 |
|---|---|
id | 엔트리 ID (UUID) |
content_type | 콘텐츠 타입 api_id (예: blog) |
values | field_id → 값 맵. 리치텍스트는 문서 JSON, 미디어는 에셋 id. lang_code를 주면 그 언어 값 |
locale | values의 언어 코드. 다국어를 쓰지 않는 콘텐츠 타입이면 null |
published_at | 발행 시각 |
created_at updated_at | 생성·수정 시각 |
미디어 필드의 값은 에셋 id예요 — 미디어 조회로 URL을 가져와요.
{
"id": "0d6f3c2a-7b1e-4c8a-9f2d-1a2b3c4d5e6f",
"content_type": "blog",
"values": {
"title": "전기차 장기렌트, 지금이 기회인 이유",
"slug": "ev-long-term-rental",
"body": { "type": "doc", "content": [] },
"cover": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
},
"locale": "ko",
"published_at": "2026-08-23T04:27:24Z",
"created_at": "2026-08-04T08:27:24Z",
"updated_at": "2026-08-23T08:27:24Z"
}콘텐츠 목록
콘텐츠 타입의 발행된 엔트리 목록이에요. 기본 정렬은 발행 최신순.
| 파라미터 | 설명 |
|---|---|
fields.{field_id} | 동적 필터 — 필드 값으로 필터링 |
order | 정렬 기준. - 접두사는 내림차순 (기본 -published_at) |
lang_code | 언어 코드 (예: en). 생략하면 기본 언어 |
page limit | 페이지네이션 — limit 최대 100 |
order에는 published_at · created_at · updated_at 또는 fields.{field_id}를 쓸 수 있어요.
반환 — 엔트리 객체의 페이지 목록. 존재하지 않는 콘텐츠 타입이면 404.
curl "https://api.cherpa.me/v1/content/blog/entries?order=-published_at&limit=10" \
-H "Authorization: Bearer chp_..."{
"items": [{ "id": "0d6f3c2a-...", "content_type": "blog", "...": "..." }],
"total": 42,
"page": 1,
"limit": 10,
"total_pages": 5
}동적 필터
콘텐츠 타입의 필드는 자유롭게 정의되므로, 필터도 fields.{field_id} 쿼리 파라미터로 동적으로 걸어요. 연산자는 대괄호로 지정하고, 생략하면 eq(일치)예요.
fields.{field_id}=값 → 일치 (eq)
fields.{field_id}[op]=값 → 연산자 지정| 연산자 | 의미 | 예시 |
|---|---|---|
eq | 값 일치 (기본) | fields.slug=hello |
ne | 값 불일치 | fields.category[ne]=news |
contains | 부분 일치 (대소문자 무시) | fields.title[contains]=전기차 |
in | 목록 중 하나 (쉼표 구분) | fields.category[in]=news,event |
exists | 필드 존재 여부 (true/false) | fields.cover[exists]=true |
lt lte gt gte | 비교 (숫자는 숫자로, 그 외는 사전순) | fields.price[gte]=10000 |
여러 필터를 함께 쓰면 AND로 결합돼요. 콘텐츠 타입에 없는 필드로 필터하면 400이에요.
curl "https://api.cherpa.me/v1/content/blog/entries?fields.slug=hello" \
-H "Authorization: Bearer chp_..."curl "https://api.cherpa.me/v1/content/blog/entries\
?fields.title[contains]=전기차&fields.cover[exists]=true" \
-H "Authorization: Bearer chp_..."콘텐츠 상세
lang_code 쿼리로 언어를 고를 수 있어요. 그 언어 번역이 없는 엔트리면 404.
반환 — 엔트리 객체. 발행되지 않았거나(초안·예약·보관) 다른 타입/스페이스의 엔트리면 404.
slug 등 필드 값으로 찾으려면 목록 API의 필터를 사용하세요 (fields.slug=...).
curl https://api.cherpa.me/v1/content/blog/entries/0d6f3c2a-... \
-H "Authorization: Bearer chp_..."다국어
콘텐츠 타입에 언어를 추가하면 엔트리마다 언어별 값을 따로 쓸 수 있어요. 기본 언어의 값이 values이고, 나머지 언어는 번역으로 저장돼요.
목록·조회에 lang_code를 주면:
- 그 언어로 번역된 엔트리만 나와요 (목록의
total·페이지도 그 기준). values는 그 언어 값이에요. 번역하지 않은 필드(예: 커버 이미지)는 기본 언어 값이 그대로 들어가요.- 동적 필터와
order의fields.{field_id}도 그 언어 값으로 동작해요.
lang_code가 기본 언어이거나 생략되면 지금처럼 기본 언어로 모든 엔트리가 나와요. 콘텐츠 타입에 없는 언어 코드면 400이에요. 코드는 대소문자를 구분하지 않아요.
curl "https://api.cherpa.me/v1/content/blog/entries\
?lang_code=en&fields.slug=ev-long-term-rental" \
-H "Authorization: Bearer chp_..."조회수 기록
사이트에서 글을 보여줄 때 한 번 호출하면 조회수가 1 올라가요. 콘솔의 콘텐츠 목록 조회 수와 콘텐츠 대시보드의 누적 조회수 그래프가 이 값으로 집계돼요. 요청 본문은 없어요.
발행된 엔트리만 기록돼요 — 초안·예약·보관 상태면 404. 중복 방지(같은 방문자 재조회 등)는 호출하는 쪽에서 판단해요.
반환 — { "views": 누적 조회수 }
curl -X POST https://api.cherpa.me/v1/content/blog/entries/0d6f3c2a-.../views \
-H "Authorization: Bearer chp_..."{ "views": 1284 }미디어 조회
엔트리의 미디어 필드 값(에셋 id)으로 파일 정보를 조회해요. url로 파일에 접근해요.
| 속성 | 설명 |
|---|---|
id | 에셋 ID (UUID) |
url | 파일 URL |
filename alt | 파일명 · 대체 텍스트 |
width height | 이미지 크기 (px) |
size | 파일 크기 (바이트) |
uploaded_at | 업로드 시각 |
CDN
전용 CDN 도메인을 통한 이미지 서빙·변환은 준비 중이에요. 현재는 url을 그대로 사용해요.
curl https://api.cherpa.me/v1/content/assets/a1b2c3d4-... \
-H "Authorization: Bearer chp_..."{
"id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"url": "https://.../cover.jpg",
"filename": "cover.jpg",
"alt": "커버 이미지",
"width": 1600,
"height": 900,
"size": 254859,
"uploaded_at": "2026-08-01T10:00:00Z"
}