REST API 개요

Profound CMS REST API는 Rust translation_manager 서비스에서 제공합니다. 이 서비스는 렌더러에서 사용하는 헤드리스 읽기/스트림 엔드포인트와, 콘텐츠·번역·CSV 가져오기에 대한 쓰기 엔드포인트를 제공합니다.

모든 예시는 {CMS_API_URL}을 CMS API 호스트의 기본 URL로 사용합니다(예: https://cms.dev.tryprofound.com). 전역 경로 접두사는 없습니다 — 라우트는 루트에 마운트되며, 예: {CMS_API_URL}/routes.

인증

API는 엔드포인트에 따라 두 가지 별도의 방식을 사용합니다.

API 키(헤드리스 읽기 + 변형 업서트)

키는 x-api-key 헤더 또는 api_key 쿼리 매개변수로 전달합니다:

curl '{CMS_API_URL}/dataset/post?websiteId=<uuid>' \
  -H 'x-api-key: <your-api-key>'

키는 WorkOS에 대해 검증되며 메모리에 잠시 캐시됩니다. 읽기 엔드포인트의 경우 서버가 require_schema_api_key = true로 설정되었을 때만 API 키가 필요하며, 그렇지 않으면 익명 읽기가 허용됩니다. 변형 업서트(PATCH /dataset/{schema_name})에는 content_write 권한을 가진 유효한 키가 항상 필요합니다.

API 키 인증을 사용하는 엔드포인트: /routes, /route, /blocks*, /components*, /dataset/*, /schemas/*, /content-changes.

베어러 JWT(WorkOS)

관리 엔드포인트에는 WorkOS 사용자 JWT가 필요합니다:

curl '{CMS_API_URL}/usage?orgId=<uuid>' \
  -H 'Authorization: Bearer <workos-jwt>'

베어러 인증을 사용하는 엔드포인트: /translation, /translations, /usage, /csv.

웹사이트(테넌트) 결정

API 키 엔드포인트는 대상 웹사이트를 다음 순서로 결정합니다:

1. ?websiteId=<uuid> 쿼리 매개변수
2. 구성된 웹사이트 도메인과 일치하는 Host 헤더
3. CMS_WEBSITE_ID 폴백(단일 테넌트 / 로컬 개발)

이 중 어느 것도 유효한 UUID로 해석되지 않으면 엔드포인트는 400을 반환합니다.

오류 모델

상태 점검

GET {CMS_API_URL}/health는 { "status": "ok" }를 반환하며 인증이 필요 없습니다 — 활성 상태 점검에 사용하십시오.