Docs API

인증과 제한

모든 요청은 Authorization: Bearer <keyId>.<secret> 헤더를 사용합니다. 읽기 요청에는 docs:read 또는 admin:read, 변경 요청에는 docs:write 또는 admin:write가 필요합니다. 프로젝트 범위 키는 사용할 수 없습니다. API는 키별 분당 120회로 제한됩니다.

엔드포인트

사이트 조회와 생성

GET /api/v1/docs/sites

{"sites":[{"id":"site-id","slug":"product","name":"제품 문서","visibility":"public","published":true}]}

POST /api/v1/docs/sites
Content-Type: application/json

{"slug":"product","name":"제품 문서","description":"제품 사용 안내","visibility":"public"}

성공 시 201과 { "site": ... }를 반환합니다. 사이트 이름은 1~80자입니다.

사이트 조회·수정·삭제

GET /api/v1/docs/sites/{siteId}는 사이트, 내비게이션, 게시 정보를 반환합니다. PATCH는 이름, slug, 설명, 공개 범위, 기본 주소, 커스텀 도메인과 설정을 변경합니다. 사이트 삭제는 확인용 slug를 본문으로 요구합니다.

DELETE /api/v1/docs/sites/{siteId}
Content-Type: application/json

{"confirmSlug":"product"}

응답은 {"deleted":true}입니다.

내비게이션

PUT /api/v1/docs/sites/{siteId}/navigation
Content-Type: application/json

내비게이션 입력의 tabs와 groups는 동시에 비어 있지 않을 수 없습니다. 입력은 전체 교체 방식이며 배열 순서가 표시 순서를 정합니다.

{"navigation":{"tabs":[],"groups":[{"title":"가이드","pages":[{"path":"","children":[]}]}]}}

페이지 조회와 생성

GET .../pages?path=guides/start는 경로로 페이지를 찾습니다. 생성 본문은 markdown 또는 contentJson 중 하나를 받습니다.

curl -X POST https://crm.theseeker.io/api/v1/docs/sites/site-id/pages \
  -H "Authorization: Bearer <keyId>.<secret>" \
  -H "Content-Type: application/json" \
  -d '{"path":"guides/start","title":"시작하기","markdown":"## 시작\n"}'

201 응답은 { "page", "warnings" }입니다. 페이지 수정은 PATCH를 사용하고, baseRevision이 현재 revision과 다르면 409 CONFLICT를 반환합니다. 페이지 삭제 응답은 {"deleted":true}입니다.

페이지 수정과 조회

PATCH /api/v1/docs/sites/{siteId}/pages/{pageId}

{"baseRevision":4,"title":"시작하기","markdown":"## 시작\n\n새 본문\n"}

GET은 페이지 메타데이터와 Markdown을 반환합니다. ?includeJson=1을 지정하면 canonical content JSON도 포함됩니다.

게시와 릴리스

POST /api/v1/docs/sites/{siteId}/publish
Content-Type: application/json

{"message":"첫 문서 릴리스"}

게시 성공은 201 { "release", "urls" }입니다. GET .../releases?limit=20에서 최대 100개를 조회하고, POST .../releases/{releaseId}/restore로 기존 릴리스를 게시 상태로 복원합니다.

응답 필드와 오류

{"error":{"code":"CONFLICT","message":"페이지가 다른 곳에서 수정되었습니다."}}