본문으로 건너뛰기

콘텐츠 조회 ​

발행된 콘텐츠를 웹사이트·앱에서 가져가는 API예요. 목록과 상세 조회가 중심이고, 화면에 그릴 때 함께 쓰는 미디어 조회 · 조회수 기록이 있어요.

API 키를 Authorization: Bearer 헤더로 전달해 인증하고, 스페이스는 키에서 자동으로 결정돼요. full(전체 접근) 또는 content(콘텐츠 읽기) 권한 키로 호출할 수 있어요.

published 상태의 엔트리만 노출돼요. 발행 후 수정 중인 엔트리(changed)는 계속 노출되며, 이때는 수정 중인 현재 값이 반환돼요. 초안·예약·보관 상태는 404예요.

:content_type은 콘텐츠 타입의 api_id예요 (예: blog). 콘솔에서 콘텐츠 종류를 만들 때 정한 슬러그가 이 값이에요.

인증
bash
curl https://api.cherpa.me/v1/content/blog/entries \
  -H "Authorization: Bearer chp_..."

엔트리 객체 ​

콘텐츠 한 건(엔트리)을 나타내요. 상태·조회수 같은 내부 필드는 포함되지 않아요.

속성설명
id엔트리 ID (UUID)
content_type콘텐츠 타입 api_id (예: blog)
valuesfield_id → 값 맵. 리치텍스트는 문서 JSON, 미디어는 에셋 id. lang_code를 주면 그 언어 값
localevalues의 언어 코드. 다국어를 쓰지 않는 콘텐츠 타입이면 null
published_at발행 시각
created_at updated_at생성·수정 시각

미디어 필드의 값은 에셋 id예요 — 미디어 조회로 URL을 가져와요.

엔트리 객체
json
{
  "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"
}

콘텐츠 목록 ​

GET/v1/content/:content_type/entries

콘텐츠 타입의 발행된 엔트리 목록이에요. 기본 정렬은 발행 최신순.

파라미터설명
fields.{field_id}동적 필터 — 필드 값으로 필터링
order정렬 기준. - 접두사는 내림차순 (기본 -published_at)
lang_code언어 코드 (예: en). 생략하면 기본 언어
page limit페이지네이션 — limit 최대 100

order에는 published_at · created_at · updated_at 또는 fields.{field_id}를 쓸 수 있어요.

반환 — 엔트리 객체의 페이지 목록. 존재하지 않는 콘텐츠 타입이면 404.

요청
bash
curl "https://api.cherpa.me/v1/content/blog/entries?order=-published_at&limit=10" \
  -H "Authorization: Bearer chp_..."
응답 · 200
json
{
  "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이에요.

slug 로 한 건 찾기
bash
curl "https://api.cherpa.me/v1/content/blog/entries?fields.slug=hello" \
  -H "Authorization: Bearer chp_..."
제목 검색 + 커버 있는 글만
bash
curl "https://api.cherpa.me/v1/content/blog/entries\
?fields.title[contains]=전기차&fields.cover[exists]=true" \
  -H "Authorization: Bearer chp_..."

콘텐츠 상세 ​

GET/v1/content/:content_type/entries/:id

lang_code 쿼리로 언어를 고를 수 있어요. 그 언어 번역이 없는 엔트리면 404.

반환 — 엔트리 객체. 발행되지 않았거나(초안·예약·보관) 다른 타입/스페이스의 엔트리면 404.

slug 등 필드 값으로 찾으려면 목록 API의 필터를 사용하세요 (fields.slug=...).

요청
bash
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이에요. 코드는 대소문자를 구분하지 않아요.

영어 글만, slug 로 찾기
bash
curl "https://api.cherpa.me/v1/content/blog/entries\
?lang_code=en&fields.slug=ev-long-term-rental" \
  -H "Authorization: Bearer chp_..."

조회수 기록 ​

POST/v1/content/:content_type/entries/:id/views

사이트에서 글을 보여줄 때 한 번 호출하면 조회수가 1 올라가요. 콘솔의 콘텐츠 목록 조회 수와 콘텐츠 대시보드의 누적 조회수 그래프가 이 값으로 집계돼요. 요청 본문은 없어요.

발행된 엔트리만 기록돼요 — 초안·예약·보관 상태면 404. 중복 방지(같은 방문자 재조회 등)는 호출하는 쪽에서 판단해요.

반환 — { "views": 누적 조회수 }

요청
bash
curl -X POST https://api.cherpa.me/v1/content/blog/entries/0d6f3c2a-.../views \
  -H "Authorization: Bearer chp_..."
응답 · 200
json
{ "views": 1284 }

미디어 조회 ​

GET/v1/content/assets/:id

엔트리의 미디어 필드 값(에셋 id)으로 파일 정보를 조회해요. url로 파일에 접근해요.

속성설명
id에셋 ID (UUID)
url파일 URL
filename alt파일명 · 대체 텍스트
width height이미지 크기 (px)
size파일 크기 (바이트)
uploaded_at업로드 시각

CDN

전용 CDN 도메인을 통한 이미지 서빙·변환은 준비 중이에요. 현재는 url을 그대로 사용해요.

요청
bash
curl https://api.cherpa.me/v1/content/assets/a1b2c3d4-... \
  -H "Authorization: Bearer chp_..."
응답 · 200
json
{
  "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"
}