UNPKG

@roottale/cms-mcp

Version:

RootTale CMS MCP server and CLI for models, entries, exposures, media, integration docs, and public API access.

940 lines (761 loc) • 50.4 kB
--- title: HTTP API 레퍼런스 description: 공개 API raw 엔드포인트 — JS 외 스택이나 저수준 연동용 --- # HTTP API 레퍼런스 팝업·배너의 v2 결정 조회와 수정안·예약·일시 중지 API는 [팝업·배너와 예약 표시](popups-and-banners.md)를 참고하세요. 베이스 URL: `https://api.roottale.com` 인증: 모든 요청에 `Authorization: Bearer rtlk_cust_...` 헤더. 공개 콘텐츠 조회를 JS/TS로 연동할 때는 raw 호출 대신 `@roottale/cms-client`를 사용하세요. 전체 CMS 관리는 아래 HTTP API, MCP tool 또는 공개 CLI를 사용합니다. tenant-api의 `GET /v1/cms/public/*` 응답에는 진단용 `Server-Timing` 헤더가 있습니다. `total`, `auth`, `site`는 밀리초이며, `/metadata`와 `/metadata/routes`는 `context_read`, `context_parse`, `tx`, `policy`, `projection`도 제공합니다. 같은 구간은 시간 합계와 `desc="count=N"`으로 표시하고, 실행하지 않은 구간은 count=0입니다. `contract`는 조회한 계약의 DB 저장 크기(압축 포함) 합계와 횟수입니다. 중첩 구간의 시간을 모두 더하지 마세요. Workers의 타이머 제약으로 CPU 구간은 0에 가까울 수 있습니다. 응답 본문·상태·캐시 규칙은 그대로이며, 이 헤더를 애플리케이션의 성공 판정이나 캐시 키로 사용하지 마세요. 글쓰기·미디어 자동화는 `read_write` API 키가 필요합니다. 모델·필드·노출까지 관리하려면 `full_management` 키를 권장합니다. `read` 키는 공개 콘텐츠뿐 아니라 관리 API의 초안·예약·비공개 글과 미디어 목록도 조회할 수 있습니다. 다만 **완전한 읽기 전용은 아닙니다** — 상담 게시판 글 작성 (`POST /v1/cms/public/inquiries`)과 폼별 문의 접수 (`POST /v1/public/inquiry-forms/:formId/submissions`)가 `cms:read`로 허용됩니다. 기존 글·미디어· 설정을 고치거나 지우려면 `read_write` 이상이 필요합니다. 사업장 정보·상단 메뉴를 바꾸는 일(아래 "설정 쓰기 API")은 한 단계 위인 `read_write_settings` 키가 따로 필요합니다 — 글쓰기 키로는 열리지 않습니다. ## 관리 API 빠른 흐름 공통 메타데이터는 `GET /v1/cms/metadata`로 검색·cursor 조회하고, `GET /v1/cms/metadata/{kind}/{key}`로 현재 버전과 지원 필드를 확인합니다. `kind`는 `route | post | term`입니다. `PATCH`는 `{ "expected_version": "조회한 version", "patch": { "title": null, "noindex": false } }` 형식이며 수정은 Pro/Premium(또는 루트테일의 사이트별 허용)과 대상별 쓰기 scope가 모두 필요합니다. 편집이 닫혀 있으면 403 `upgrade_required`(요금제)·`site_denied`(사이트별 제한)·`billing_locked`(구독 중단)를 반환합니다. `site_id`·`locale`은 선택입니다. 본문만 수정하면 저장된 SEO를 보존합니다. 고정 경로 공개 조회는 `GET /v1/cms/public/metadata?route_key=home&locale=ko`이며 `{ "site_id": "…", "metadata": null }` 또는 camelCase `PublicRouteMetadata`를 반환합니다. 공개 응답의 `metadata`에는 `routeKey`, `locale`, `path`, `version`, `overrides`, `defaults`, `effective`, `supportedFields`, 선택적 `fallback`과 `robots` 강제 정책이 있습니다. 공개 읽기는 등급과 관계없이 기존 설정을 사용합니다. 자세한 연동은 [공통 메타데이터](seo.md#공통-메타데이터)를 참고하세요. 관리 API는 초안 작성 → 미디어 연결 → 발행을 분리합니다. 자동화가 실수로 미완성 글을 공개하지 않도록 글 생성의 기본 상태는 `draft`입니다. 전체 리소스 경로와 권한은 [콘텐츠 모델과 노출 관리](./content-models-and-exposures.md)에 정리되어 있습니다. ### POST /v1/cms/posts Tiptap JSON 본문으로 글 또는 페이지를 만듭니다. ```bash curl https://api.roottale.com/v1/cms/posts \ -H "Authorization: Bearer $ROOTTALE_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: post-2026-07-17-001" \ -d '{ "type": "post", "title": "자동화로 작성한 글", "slug": "automated-post", "body_json": {"type":"doc","content":[]}, "author_profile_id": "site-author-id", "featured_media_id": null, "category_ids": [], "tag_ids": [] }' ``` 주요 필드: | 필드 | 설명 | |---|---| | `body_json` | Tiptap 문서 JSON 객체 | | `author_profile_id` | 사이트 공통 공개 작성자 ID. 생략한 사용자 키는 계정별 기본값, `null`은 미지정 | | `featured_media_id` | 미디어 업로드 완료 응답의 `id`; `null`이면 썸네일 없음 | | `publish` | `true`면 즉시 발행. 생략하면 초안 | | `scheduled_at` | 미래 ISO 8601 시각. `publish`와 동시 사용 불가 | | `category_ids`, `tag_ids` | 생성과 동시에 연결할 term ID 배열 | | `model_key` | 페이지·글·정보 모델의 안정 key. 모델이 여러 개면 필수 | | `field_values` | 모델 필드 정의로 검증할 편집 원문 객체 | | `source_key` | 외부 원고의 안정 식별키(1–255자). 같은 tenant/site/key는 기존 글을 반환 | 외부 원장 연동은 제목·슬러그 대신 `source_key`를 사용합니다(예: `notion:<Page ID>`). 키는 기존 글과 같은 DB 트랜잭션에 보관하며 동시 생성도 한 글로 합칩니다. 최초 생성은 201, 같은 키의 재시도는 200으로 기존 글을 반환하고 내용을 덮어쓰지 않습니다. 휴지통에 있으면 409 `source_post_removed`이며 자동으로 복원하지 않습니다. 이는 Worker 메모리의 `Idempotency-Key` 재시도 캐시와 별개입니다. 생성은 초안으로 진행하고 응답의 ID/상태를 확인한 뒤 수정·SEO·발행을 각각 처리하세요. `meta_json._sync`는 외부 동기화 체크포인트용으로 사용할 수 있으며 관리 응답에서만 반환하고 공개 글 목록·상세·미리보기 응답에서는 제외합니다. 인증 정보는 넣지 마세요. ### PATCH /v1/cms/posts/{post_id} 보낸 필드만 수정합니다. `featured_media_id: null`이면 썸네일을 해제하고, `scheduled_at: null`이면 예약을 해제합니다. `author_profile_id`를 생략하면 기존 공개 작성자를 유지하고, `null`이면 초안의 공개 작성자를 비웁니다. `expected_updated_at`에 마지막 조회의 `updated_at`을 보내면 다른 저장이 먼저 일어났을 때 409 `post_update_conflict`로 중단합니다. 충돌 후 새 버전을 읽어 수정 내용을 확인하세요. 새 버전만 바꿔 맹목적으로 재전송하면 사람이 한 수정을 덮을 수 있습니다. ### POST /v1/cms/posts/{post_id}/publish 초안 또는 예약 글을 즉시 발행하고 등록된 revalidate 웹훅을 전송합니다. 본문은 `{}` 또는 `{"site_id":"..."}`입니다. 글(`type: "post"`)은 현재 사이트의 활성 공통 작성자가 지정돼 있어야 발행·예약할 수 있습니다. 선택적 `expected_updated_at`은 본문 검사 이후 다른 저장이 발생했을 때 발행을 409 `post_update_conflict`로 중단합니다. 글 수정과 같은 조회 버전 형식입니다. 모델의 `editor.topic.required`가 `"first-publish"`이면 최초 발행·예약 전에 `meta_json.contentEditor.primaryTermId`가 같은 사이트의 `custom / content_topic` 분류여야 합니다(컬렉션 범위 없음). 누락·다른 분류이면 HTTP 400 `model_topic_required`를 반환합니다. 생성 시 `publish: true`, 예약 생성·수정에도 같이 적용됩니다. 발행 기록이 있는 글의 저장·재발행과 설정 없는 모델에는 적용하지 않습니다. ### POST /v1/cms/posts/{post_id}/unpublish 발행 글을 초안으로 되돌립니다. ### PATCH /v1/cms/posts/{post_id}/terms 특정 taxonomy의 연결을 전체 교체합니다. ```json {"taxonomy":"category","term_ids":["term-id-1","term-id-2"]} ``` ### PATCH /v1/cms/posts/{post_id}/related 글의 **관련 콘텐츠**(어드민 편집기 "관련 콘텐츠" 패널과 같은 원장)를 전체 교체합니다. 유형(모델)과 상관없이 같은 사이트의 글을 순서대로 최대 10개. 자기 자신·중복은 무시되고, 다른 사이트 글은 400. 발행 글이면 `post.updated` 웹훅이 나갑니다. ```json {"related_post_ids":["post-id-1","post-id-2"], "reserved_keys":["faq.headache.migraine.aura-symptoms"]} ``` `reserved_keys` = **아직 없는 콘텐츠 예약**(선택). 공개 주소 조각을 `.` 로 이은 키를 적어 두면 대상이 그 주소로 발행되는 순간 공개 `related_posts` 뒤쪽에 자동 합류합니다. 미전달이면 예약을 손대지 않고, 빈 배열이면 전부 해제합니다(최대 10개). 응답은 `related_posts`(발행 여부 무관, 순서대로, `status` 포함)입니다. 공개 응답에는 그중 **발행 글만** `related_posts` 로 나갑니다(아래 글 목록·상세 참고). ### GET /v1/cms/posts 초안·예약·비공개·발행 글을 조회합니다. 쿼리는 `limit`, `cursor`, `type`, `status`, `site_id`, `model_key`를 지원합니다. 관리 응답은 `owner_user_id`(편집 소유 계정)와 `author_profile_id`(사이트 공통 공개 작성자)를 별도로 반환합니다. 기존 `author_id`는 하위 호환용이며 새 연동에서는 두 분리 필드를 사용하세요. ## 미디어 업로드 API API가 발급한 5분 유효 업로드 URL로 파일을 전송한 뒤 CMS에 등록합니다. 허용 형식은 JPEG, PNG, WebP, GIF, PDF이며 최대 10MB입니다. ### 1. POST /v1/cms/media/uploads ```json { "original_name": "hero.webp", "content_type": "image/webp", "size_bytes": 482031 } ``` 응답의 `upload_url`, `r2_key`, `expires_in`을 보관합니다. ### 2. 서명 URL에 PUT ```bash curl -X PUT "$UPLOAD_URL" \ -H "Content-Type: image/webp" \ --data-binary @hero.webp ``` 1단계에서 선언한 `Content-Type`과 바이트 크기가 정확히 같아야 합니다. ### 3. POST /v1/cms/media/uploads/complete ```json { "r2_key": "tenants/<tenant-id>/sites/<site-id>/media/...", "original_name": "hero.webp", "content_type": "image/webp", "size_bytes": 482031, "alt": "서비스 소개 대표 이미지", "caption": null } ``` `r2_key`는 1단계 응답값을 바꾸지 말고 그대로 보냅니다. 서버가 R2 객체의 tenant/site 경로, 크기, 형식을 검증한 뒤 미디어를 등록합니다. 파일 보존이 활성화된 환경에서는 원본의 별도 보존까지 확인한 뒤 등록합니다. 1단계의 `r2_key`는 업로드용 임시 경로이며, 완료 응답의 `r2_key`가 최종 원본 경로입니다. 공개 주소를 임시 경로로 직접 만들지 마세요. 완료 응답을 받지 못했거나 `503`을 받으면 같은 `r2_key`와 요청 본문으로 완료 요청을 재시도하세요. 새 등록은 `201`, 이미 완료된 업로드의 재시도는 같은 미디어 ID와 `200`을 반환합니다. 삭제된 업로드는 다시 완료할 수 없습니다. 서버의 보존 조회는 일시적인 timeout·429·5xx를 제한 재시도하지만, 원본 대조에 성공하기 전에는 완료로 응답하지 않습니다. 자동 조회 재시도 후에도 `503`이면 위와 같이 같은 업로드의 완료 요청을 재시도합니다. 응답의 `id`는 글의 `featured_media_id`에, `url`은 Tiptap image 노드의 `attrs.src`에 사용합니다. ### 미디어 관리 | 메서드·경로 | 설명 | |---|---| | `GET /v1/cms/media` | 최신순 목록. `limit`, `offset`, `site_id` 지원 | | `PATCH /v1/cms/media/{media_id}` | `alt`, `caption` 수정 | | `DELETE /v1/cms/media/{media_id}` | 미디어 행·R2 원본·변형 이미지·CDN 캐시 삭제 | 미디어 삭제 전 해당 URL을 쓰는 본문과 `featured_media_id` 연결을 먼저 교체하세요. 삭제 후 기존 공개 URL은 더 이상 유효하지 않습니다. 파일 보존이 활성화된 환경에서 원본 보존 또는 삭제 기록 저장에 실패하면 `503`을 반환하며 삭제를 완료하지 않습니다. 외부 파일이나 CDN 정리가 지연되면 목록에서 삭제된 뒤에도 `503`을 받을 수 있습니다. 이때 오류 메시지에 정리 대기와 자동 재시도를 알리며, 서버가 남은 작업을 계속 처리합니다. `200 { deleted: true }`는 공개 파일 정리까지 완료된 경우입니다. 미디어 목록의 `404`만으로 CDN 정리 완료를 판단하지 마세요. 이미 방문자의 브라우저에 저장된 파일은 원격으로 지울 수 없습니다. ## 설정 쓰기 API 사업장 정보와 상단 메뉴를 어드민 화면 대신 API로 바꿉니다. **`read_write_settings` 권한으로 발급한 키가 필요합니다** (`settings:write`). 글쓰기 키(`read_write`)로 호출하면 `403 insufficient_scope` 입니다. 페이지·글·정보 모델과 배너·팝업 슬롯 연동은 [콘텐츠 모델과 노출 슬롯](./content-models-and-exposures.md)을 참고하세요. 세 가지를 먼저 알아 두세요. 1. **두 엔드포인트 모두 "그 설정 블록 전체 교체"입니다.** 메서드는 `PATCH` 지만 부분 병합이 아닙니다 — 보낸 값이 그 설정의 전부가 되고, 빠뜨린 필드는 지워집니다. 한 칸만 고치고 싶으면 공개 조회로 현재 값을 받아 그 값을 고쳐서 통째로 보내세요. 2. **대상 사이트는 `settings` 바깥(envelope)에 적습니다.** 사이트가 둘 이상인 테넌트가 `site_id` 를 생략하면 `400 site_id_required` 입니다 — 임의의 사이트를 고르지 않습니다. 사이트에 묶인 키(site-scoped)는 생략하고, 다른 사이트를 지목하면 `404` 입니다. 3. **저장 뒤 연결된 사이트에 `theme.updated` 알림을 보냅니다.** 알림이 실패해도 저장은 되돌아가지 않습니다 — 결과는 응답의 `revalidate` 로 확인합니다. ### PATCH /v1/cms/settings/business-profile ```json { "site_id": "019eb70c-…", "settings": { "name": "길동세무회계", "business_type": "AccountingService", "telephone": "02-1234-5678", "address": { "street_address": "테헤란로 123", "address_locality": "강남구" }, "opening_hours": [ { "days": ["Mo","Tu","We","Th","Fr"], "opens": "09:00", "closes": "18:00" } ], "area_served": ["서울 강남구"], "services": ["기장·신고대리", "세무고문"], "profiles": { "naver_place": "https://map.naver.com/p/entry/place/1" } } } ``` `settings` 안쪽 필드는 `GET /v1/cms/public/business-profile` 응답과 같은 이름입니다. 서버가 정하는 값(`tenant_id`·`site_id`·`configured`·`updated_at`)은 넣을 수 없습니다 — 넣으면 `400` 입니다. 저장 규칙: | 항목 | 규칙 | |---|---| | `profiles.*` | **https 절대 주소만.** `http://` 와 로컬 주소는 거부 | | `opening_hours` | 최대 7행. 시각은 `HH:MM` 24시간 표기(`09:00`). 선택 `reception_closes`는 시작 뒤·종료 이하 시각 또는 `null` | | `area_served` | 10개 / 각 40자 | | `services` | 12개 / 각 80자 (중복은 자동 제거) | | `alternate_name`·`fax_number` | 각 120자 / 40자 | | 모르는 필드 | 거부 (`400`) | ### PATCH /v1/cms/settings/site-nav ```json { "settings": { "navGroups": [ { "label": "사무소 소개", "href": "/about" }, { "label": "소식", "columns": [ { "title": "알림", "links": [ { "label": "공지", "href": "/notice" } ] } ] } ], "cta": { "label": "상담 문의", "href": "/contact" } } } ``` `settings` 는 `GET /v1/cms/public/theme` 의 `siteNav` 와 같은 모양입니다. 저장 규칙: 메뉴 그룹 7개 / 그룹당 열 3개 / 열당 링크 6개 / 보조 링크 (`utilityLinks`) 4개. 주소는 `#앵커`·`/경로`·`http(s)://` 만 허용합니다. 그룹에는 `href` 나 `columns` 중 하나가 반드시 있어야 합니다. > 상단 메뉴는 한 번 만들면 빈 값으로 되돌릴 수 없습니다(`navGroups` 는 최소 > 1개). 메뉴를 없애려면 어드민 화면에서 지우세요. ### 응답 두 엔드포인트가 같은 모양으로 답합니다. ```json { "tenant_id": "…", "site_id": "…", "updated_at": "2026-07-28T04:20:00.000Z", "settings": { "…": "저장된 값 그대로" }, "revalidate": { "configured": 1, "delivered": 1, "failed": 0, "degraded": false } } ``` `settings` 는 **저장된 값**입니다 — 보낸 값과 다를 수 있습니다(요일 순서 정렬, 목록 중복 제거, `business_type` 기본값 `LocalBusiness` 등). 다음 조회에서 무엇을 보게 될지는 이 값이 정답이고, 공개 조회로 확인하려 하지 마세요(공개 응답에는 최대 10초 캐시가 걸립니다). `revalidate` 는 저장 뒤 보낸 갱신 알림의 결과입니다. | 필드 | 뜻 | |---|---| | `configured` | 등록되어 있고 켜져 있는 알림 목적지 수 | | `delivered` | 성공 | | `failed` | 목적지가 오류를 돌려줌 | | `degraded` | **보내지도 못한** 목적지가 있음 — 설정을 점검해야 합니다 | `configured: 0, degraded: false` 는 정상입니다(알림을 등록하지 않은 사이트). `degraded: true` 면 사이트에 반영되지 않았을 수 있으니 어드민의 발행 알림 설정을 확인하세요. ## GET /v1/cms/public/posts 발행된 글 목록 (커서 페이지네이션). | 쿼리 | 설명 | |---|---| | `limit` | 페이지 크기 (서버에서 상한 clamp) | | `cursor` | 이전 응답의 `next_cursor` | | `type` | `post` \| `page` | | `site_id` | 멀티 사이트 키일 때만 — site-scoped 키면 생략 | ```json { "items": [ { "id": "…", "slug": "…", "title": "…", "body_json": {…}, "collection_key": "blog", "author_profile_id": "site-author-id", "author_name": "공통 작성자", "author_slug": "writer", "author_image_position_x": 50, "author_image_position_y": 50, "terms": [{ "taxonomy": "category", "name": "…", "slug": "…" }], "pattern_slots": { "post_footer": "clinic-guide" }, "published_at": "…" } ], "has_more": false, "next_cursor": null } ``` > `collection_key` = 글이 속한 섹션(콘텐츠 유형). 섹션 라우팅(`/notice`·`/blog`)의 근거이며, > 미설정이면 `null`. 카테고리(`terms`)는 섹션 안의 주제로 아카이브에만 쓰입니다 → > [콘텐츠 유형 (Collections)](./collections.md). `pattern_slots` = 공통 블록 자리별 블록 key(자리 key → `GET /patterns` 의 `key` 또는 `null`). 어드민 배치 규칙을 서버가 이 글의 `model_key`(콘텐츠 모델)에 맞춰 계산한 결과이며, 선언된 자리(현재 `post_footer` = 글 하단)는 항상 키로 존재합니다. 글 상세·미리보기 응답에도 같은 필드가 붙습니다 → 아래 `GET /v1/cms/public/patterns` 참고. `related_posts` = 편집자가 어드민 "관련 콘텐츠"에서 고른 글(유형 무관, 고른 순서) + **발행된 예약 키 대상**(그 뒤, 적은 순서), **발행 글만**·중복 제거. 각 항목은 `{ id, title, slug, path, type, model_key, collection_key, excerpt, featured_media_url, published_at }` 로 카드 하나를 그릴 만큼만 담습니다. 목록·상세·미리보기 응답에 모두 붙습니다 (구 서버는 미포함 → 빈 배열로 취급). 비어 있으면 사이트가 "같은 카테고리 최신 글" 같은 자동 추천을 채우면 됩니다 — `@roottale/cms-renderer-next` 의 `RootTaleBlogPost` 는 편집자 선택이 있으면 그것을, 없으면 `relatedPostsCount` 만큼 자동 추천을 그립니다. ```json { "related_posts": [ { "id": "…", "title": "…", "slug": "…", "path": "/faq/headache/migraine/…", "type": "post", "model_key": "faq", "collection_key": "faq", "excerpt": "…", "featured_media_url": null, "published_at": "…" } ] } ``` `author_profile_id`는 사이트 공통 공개 작성자 ID입니다. 이름·사진·소개·작가 주소는 같은 원장의 `author_name`·`author_image_url`·`author_bio`·`author_slug`로 제공됩니다. 사진 초점은 `author_image_position_x/y`(0~100, 구 서버는 `null`)이며 이미지 모양은 사이트의 시멘틱 토큰/CSS가 정합니다. 기존 `author_id`는 하위 호환용이므로 새 연동에서는 공개 작성자 식별자로 사용하지 마세요. `content_version`은 반영된 콘텐츠 버전(1부터 시작), `contract_page_key`는 사이트 콘텐츠 계약에 연결한 페이지 key입니다. 사이트 계약에 `visualEditing`이 있을 때만 이 두 필드와 `content_editor`를 제공합니다. 미선언 사이트와 구 서버는 생략합니다. `content_editor`는 공개 렌더링에 필요한 허용 필드만 제공합니다: ```json { "sectionStates": { "hero": "visible", "faq": "hidden", "old-section": "deleted" }, "primaryTermId": null, "cta": { "mode": "auto", "targetPostId": null } } ``` 섹션 상태는 `visible`·`hidden`·`deleted`, CTA 모드는 `auto`·`manual`·`off`입니다. `manual`은 `targetPostId`가 필요합니다. 사이트 템플릿은 `hidden`·`deleted`인 섹션을 출력하지 않으며, 내부 검수 정보는 이 응답에 포함되지 않습니다. SDK에서는 `contentVersion`·`contractPageKey`·`contentEditor`로 읽습니다. 선언 사이트의 목록·상세·미리보기에서 저장된 편집 상태가 없으면 `content_editor`를 생략하고, 저장값 해석에 실패하면 `null`을 보냅니다. 실패한 원문은 `meta_json`에서도 제거합니다. SDK는 `null`을 `contentEditorResult: { success: false, error }`로 전달하며 기존 `contentEditor`는 `undefined`입니다. 사이트는 실패를 기본 상태로 바꾸지 않습니다. `fields`는 글의 모델과 템플릿에 맞는 필드 그룹의 최상위 key만 포함합니다. 템플릿은 고정 페이지의 `contract_page_key` 또는 모델 선언에서 찾습니다. 그 템플릿·모델이 사이트 계약의 `visualEditing.templates`에 등록되어 있으면 필드 값을 저장 구조 그대로 전달합니다. 그룹 내부의 코드 소유 경로·배치 값과 반복 항목 `_id`를 보존하며, 없는 선택 그룹은 `null`입니다. 이 경우 이미지·관계 필드도 저장된 ID이므로 사이트가 필요한 공개 대상을 조회합니다. 그 밖의 필드는 기존 포맷과 공개 참조 해석을 유지합니다. 반복행의 유효한 UUID `_id` 보존도 `visualEditing` 선언 사이트에만 적용하며 미선언 사이트는 기존 응답을 유지합니다. ## GET /v1/cms/public/posts/{identifier} 글 1개 — `identifier`는 slug 또는 UUID. 미발행/없는 글은 `404`. ## GET /v1/cms/public/posts/preview 관리자 편집기가 발급한 **미리보기 토큰**으로 초안(미발행 포함)을 **발행 글과 같은 모양**으로 받습니다. 사이트가 자기 글 템플릿으로 미리보기를 그리게 하는 용도입니다 — 관리자 미리보기와 발행 결과가 다르던 문제의 해법(`blog.md` "미리보기 페이지" 참고). | 쿼리 | 설명 | |---|---| | `token` | 편집기 '사이트에서 미리보기'가 URL `?token=`으로 넘긴 값 (글 1건 전용, 1시간) | | `site_id` | 멀티 사이트 키일 때만 | - 응답은 `GET /posts/{identifier}`와 같은 형식이며 `preview` 블록이 추가됩니다: `{ "expires_at": "…", "source_status": "draft" }`. `status`는 템플릿 재사용을 위해 항상 `published`, `title`·`slug`·`excerpt`·`body_json`은 토큰 발급 시점의 편집기 내용입니다. 전체 작업본 토큰은 커스텀 필드·SEO·분류·관련 콘텐츠· 대표 이미지·작성자·`content_editor`·`contract_page_key`도 같은 작업본에서 읽습니다. HTML이 정본인 작업본은 `body_html`을 보존하며, 구 편집기 토큰은 `null`입니다. 발행 전이면 `published_at`은 토큰 발급 시각입니다. - 새 토큰은 작업본 ID와 버전을 참조하며, `preview.visual_target`에 `{ entityId, draftId, draftVersion, contractVersion, templateVersion }`를 반환합니다. `content_version`은 그 작업본의 기준 콘텐츠 버전이고 `draftVersion`과 구분됩니다. 사이트는 실제로 읽은 의존 버전과 이 표식을 사용해 렌더 완료를 확인합니다. - 토큰이 없거나 다른 사이트의 것이면 `404`, 만료면 `410 preview_expired`. - 작업본이 교체됐거나 표식과 내용이 맞지 않으면 `409 preview_superseded`입니다. 등록된 사이트 계약의 checksum이 토큰의 `contractVersion`과 달라도 같은 오류입니다. 최신 작업본이나 발행 글로 자동 대체하지 말고 편집기에서 미리보기를 다시 열도록 안내합니다. - 기존 글 편집기의 `contentTopicIds` 스냅샷은 `content_topic` 분류만 바꾸고 카테고리·태그·다른 사용자 분류는 유지합니다. 전체 작업본의 `termIds`가 있으면 그 전체 목록을 우선합니다. 모든 분류와 관련 글은 같은 사이트 범위에서 확인합니다. - 응답 헤더 `cache-control: no-store` — 사이트도 절대 캐시하지 마세요. JS/TS 는 `@roottale/cms-client/server` 의 `fetchPostPreview({ apiKey, token })` 와 `isPreviewExpiredError(error)`·`isPreviewSupersededError(error)`를 사용하세요. SDK의 작업본 표식은 `post.preview.visualTarget`입니다. ## GET /v1/cms/public/search 발행된 콘텐츠 키워드 검색입니다. 제목 완전일치, 제목 부분일치, 요약, 본문 순으로 관련도를 계산하고 같은 점수에서는 최신 발행순으로 정렬합니다. 응답은 카드 렌더용 슬림 hit이며 본문(`body_json`)은 포함하지 않습니다. | 쿼리 | 설명 | |---|---| | `q` | 검색 키워드 (필수, 1~100자) | | `limit` | 결과 수 1~50, 기본 10 | | `type` | `post`(기본, 하위 호환) \| `page` \| `all`(글+페이지 통합) | | `locale` | BCP-47 언어 코드. 생략하면 사이트 기본 언어 | | `site_id` | 멀티 사이트 키일 때만 | ```json { "tenant_id": "…", "site_id": "…", "query": "세무", "items": [ { "id": "…", "type": "post", "collection_key": "notice", "locale": "ko", "title": "…", "slug": "…", "excerpt": "…", "featured_media_url": "…", "published_at": "…" } ] } ``` JS/TS 는 `@roottale/cms-client/server` 의 `searchPosts({ apiKey, query })` 를 사용하세요. 사이트 전체 검색은 `type: "all"`을 지정합니다. 결과 링크는 `resolveSearchHitPath(hit, collections, locale?)`로 계산해야 콘텐츠 유형의 `basePath`와 다국어 경로를 그대로 따릅니다. `ROOTTALE_API_KEY`는 브라우저에 노출하지 말고 Server Component·Route Handler에서만 사용하세요. ## GET /v1/cms/public/menus 네비게이션 메뉴 전체 — 어드민 "디자인 > 메뉴" 저장값. 항목은 깊이 2 트리. ```json { "tenant_id": "…", "site_id": "…", "items": [ { "id": "…", "name": "헤더 메뉴", "slug": "primary", "items": [ { "id": "…", "label": "회사 소개", "url": "/about", "children": [ { "id": "…", "label": "오시는 길", "url": "/about/location" } ] }, { "id": "…", "label": "블로그", "url": "/blog" } ], "updated_at": "…" } ] } ``` ## GET /v1/cms/public/menus/{slug} 위치 핸들(`primary`, `footer` 등)로 메뉴 1개. 없으면 `404` — 사이트는 자체 fallback 네비를 렌더하세요 (`menus.md` 참고). ## GET /v1/cms/public/redirects 어드민 "설정 > 주소 이동"에서 정의한 **활성** 커스텀 리다이렉트 규칙 전체. 사이트 Proxy가 요청 경로를 매칭해 301/302 처리합니다. 비활성 규칙과 운영자 메모는 응답에 포함되지 않습니다. 라우트 미배포(구 서버)는 `404` — 빈 목록으로 처리하세요. 연동은 `custom-redirects.md` 참고. ```json { "tenant_id": "…", "site_id": "…", "items": [ { "id": "…", "from_path": "/old-event", "to_target": "/promo", "status_code": 301 } ] } ``` | 필드 | 설명 | |---|---| | `from_path` | 출발 경로 — 정규화된 사이트 내부 절대 경로(앞 슬래시, 쿼리 제외). | | `to_target` | 도착지 — 내부 경로(`/promo`) 또는 절대 URL(`https://…`). | | `status_code` | `301`(영구) 또는 `302`(임시). | ## GET /v1/cms/public/theme 어드민에서 설정한 디자인 토큰. 설정된 그룹만 포함됩니다. ```json { "tenant_id": "…", "site_id": "…", "colors": {…}, "fonts": {…}, "radius": {…}, "updated_at": "…" } ``` ## GET /v1/cms/public/blog-settings 블로그 표시 설정 (TOC·작성자·발행일·작성자 카드 표시 정책). `post_cta`는 공통 글 하단 블록이 없는 기존 글에서 `RootTaleBlogPost`가 적용하고, 공통 블록이 있으면 중복을 막기 위해 생략한다. 작성자 이미지 모양과 과거 전역 초점 필드는 호환용이며, 모양은 사이트 시멘틱 토큰/CSS, 초점은 글 응답의 작성자별 값이 소유한다. `toc_position`은 목차 배치(`"inline"`=본문 위 접이식, `"sidebar"`=넓은 화면에서 본문 오른쪽 sticky, 좁은 화면은 자동 인라인)로, 렌더러가 알아서 반영하므로 연동 코드 변경은 불필요하다. ```json { "show_table_of_contents": false, "show_author": true, "show_date": true, "show_author_card": true, "toc_title": null, "toc_position": "inline", "author_profile_name": null, "author_profile_bio": null, "author_profile_image_url": null, "author_profile_image_radius": "circle", "site_profile": { "site_description": null, "home_title": null, "home_description": null, "logo_url": null, "favicon_url": null, "default_og_image_url": null }, "post_cta": { "title": "상담이 필요하신가요?", "description": "첫 상담은 무료입니다.", "button_label": "상담 문의하기", "button_href": "/contact" }, "updated_at": null } ``` `author_profile_name`·`author_profile_bio`·`author_profile_image_url`· `author_card_description`은 이전 연동을 깨지 않기 위해 응답 모양에만 남아 있고 항상 `null`입니다. 작성자 이름·사진·소개는 글 응답의 `author_name`· `author_image_url`·`author_bio`를 사용하세요. 이 값은 글에 지정된 사이트별 작성자 프로필에서 옵니다. 글에 작성자가 없으면 작성자 메타와 카드를 표시하지 않습니다. `site_profile` 은 사이트 공통 SEO 값. `default_og_image_url`(1200×630 권장)은 글에 대표/OG 이미지가 없을 때 SNS 공유 썸네일 폴백으로 쓰세요 — `generateMetadata` 에서 `post.seo?.ogImage ?? post.featured_media_url ?? settings.siteProfile.defaultOgImageUrl` 순으로 우선합니다. `logo_url`· `favicon_url`·`site_description` 은 사이트 `<head>` 에 적용합니다. `home_title`·`home_description`은 **메인 홈(`/`) 전용** 호환 필드입니다. 계약 등록만으로 기존 홈 설정을 바꾸지 않습니다. 초기값 보존 또는 실제 설치 확인에서 홈 전환을 완료한 뒤 해당 경로의 `effective.title`·`effective.description`을 투영합니다. 전환 뒤에는 초기화·연결 해제·계약 제거로 예전 홈 설정을 되살리지 않습니다. 연결된 CMS 홈이 초안이거나 소유 경로가 제거되면 `null`을 반환합니다. 새 연동은 `fetchRouteMetadata`와 공통 빌더를 사용하세요(`seo.md` 참고). ## GET /v1/cms/public/metadata/routes 계약에 등록된 공개 경로의 검색·공유 메타데이터를 한 스냅샷에서 조회합니다. 인증과 `cms:read` scope는 단건 `/metadata?route_key=`와 같습니다. 선택 쿼리는 `locale`(생략 시 사이트 기본 언어), `site_id`입니다. 사이트 범위 키는 다른 사이트를 지정할 수 없고 tenant 범위도 유지됩니다. ```json { "site_id": "site-id", "routes": [{ "routeKey": "home", "locale": "ko", "path": "/", "version": "0", "overrides": {}, "defaults": { "title": "홈" }, "effective": { "title": "홈" }, "supportedFields": ["title"] }] } ``` 각 항목은 단건 응답의 `metadata`와 같은 형식이며 `fallback`·`robots`도 보존합니다. 등록 순서로 반환하고 단건이 `null`인 경로는 제외합니다. 공개 대상이 없으면 `routes: []`이며 조회 장애는 오류 응답입니다. 구독 하향·미납에도 공개 읽기를 유지하고 `Cache-Control: private, no-store`를 반환합니다. SDK의 서버 측 Next fetch cache와는 별도입니다. SDK는 `fetchSiteRouteMetadata(options)`이며 배포 순서는 API → SDK 발행 → 사이트입니다. ## GET /v1/cms/public/patterns 공통 블록(여러 글의 같은 자리에 붙는 재사용 본문) 중 **발행 상태** 목록. 어느 글의 어느 자리에 놓을지는 글 응답의 `pattern_slots`가 이미 말해 주므로, 사이트는 `pattern_slots[slot]` 값으로 이 목록에서 `key`를 찾아 `body_json`(Tiptap 문서)을 글 본문과 같은 렌더러·정화 경로로 그리면 됩니다. 목록이 비었거나 요청이 실패해도 글은 정상 열려야 합니다(블록만 생략). ```json { "tenant_id": "…", "site_id": "…", "patterns": [ { "id": "…", "key": "clinic-guide", "name": "병원 안내", "description": "글 하단 공통 안내", "body_json": { "type": "doc", "content": [ … ] }, "presentation": { "layout": "card", "background": "#f8f9fa", "link_style": "buttons", "button_colors": ["#03c75a", "#1a1a1a", "#666666"] }, "status": "published", "updated_at": "…" } ] } ``` - 자리 key: `post_footer`(글 하단, 본문 바로 아래). 새 자리는 문서와 함께 추가됩니다. - `presentation` = 어드민이 정한 표시 형태(`layout` plain|card, `background` hex, `link_style` text|buttons, `button_colors` hex 순서 — 마지막 문단의 링크에 차례로, 모자라면 마지막 색 반복). 사이트는 이 값을 래퍼의 data 속성·CSS 변수로 옮겨 그리고, 색·모양을 따로 고정하지 않습니다. - 캐시: `Cache-Control: private, max-age=10`. 어드민에서 블록·배치 규칙을 저장하면 `theme.updated` 웹훅이 오므로 설정류 캐시와 함께 지우세요(`revalidation-webhooks.md`). ## GET /v1/cms/public/categories 분류(카테고리)와 **분류별 발행 글 수**. 글 수는 서버가 SQL로 세므로 글이 몇 건이든 정확합니다 — 분류 모음 페이지의 "글 0건이면 404" 판정과 사이트맵 포함 여부(색인 위생)를 계산하는 데 씁니다. `@roottale/cms-renderer-next` 의 `fetchBlogArchiveCategories` 가 이 API를 자동으로 씁니다(직접 부를 일은 드뭅니다). 쿼리(선택): | 이름 | 값 | 설명 | | --- | --- | --- | | `exclude_collections` | `true` | 어느 콘텐츠 유형에도 속하지 않은 글만 셉니다 — `/blog` 계열 모음 페이지가 다루는 범위와 같습니다. | | `collection_key` | 유형 key | 그 유형에 속한 글만 셉니다. `exclude_collections` 와 동시 지정 시 400. | | `locale` | BCP-47 | 미지정이면 사이트 기본 로케일(글 목록과 같은 기본값). | | `site_id` | 사이트 id | 보통 생략. | ```json { "tenant_id": "…", "site_id": "…", "categories": [ { "slug": "tax", "name": "세무", "published_post_count": 412, "collection_key": "column", "hub_promoted": true, "description": "세무 칼럼", "seo_title": "세무 칼럼 모음", "seo_description": "세무 칼럼을 주제별로 확인하세요.", "image_media_id": "019…", "image_url": "https://imagedelivery.net/…/md", "image_alt": "세무 자료와 계산기", "path": "/column/tax" }, { "slug": "law", "name": "법률", "published_post_count": 0, "collection_key": null, "hub_promoted": false } ] } ``` - 글이 0건인 분류도 그대로 내려옵니다(`published_post_count: 0`) — "그런 분류가 없다"와 "분류는 있는데 이 범위에 글이 없다"를 구분할 수 있게. - `description`·`seo_title`·`seo_description`은 ROOT-ADMIN 카테고리 편집값입니다. 검색 화면에서는 `seo_title → "{name} 글 모음"`, `seo_description → description → 사이트별 기본 소개문` 순으로 대체값을 적용하세요. - `image_media_id`는 대표 이미지의 안정 ID, `image_url`은 바로 표시할 수 있는 URL, `image_alt`는 대체 텍스트입니다. 세 값은 이미지 미설정 또는 구버전 API에서 `null`이거나 생략될 수 있습니다. `path`는 콘텐츠 유형의 `category_path` 정책까지 적용한 정규 상대 경로이며, 해당 유형에 카테고리 아카이브가 없으면 `null`입니다. - `hub_promoted` 는 어드민의 "이 카테고리 모음 페이지를 검색에 공개" 값이지만, **검색 노출 판정에는 쓰지 마세요**. 그 판정의 단일 소스는 `/blog-settings` 의 `sitemap.promoted_category_slugs` 입니다(두 소스를 섞으면 사이트맵과 페이지가 서로 다른 시점의 값을 볼 수 있습니다). 여기 값은 진단·표시용입니다. - `category_index_activated`는 사이트의 분류 색인 정책 전환이 끝났는지 알려 줍니다. 사이트 계약에 `terms.categoryIndexActivation: "required"`를 선언한 사이트만 사용합니다. 이 값이 `true`일 때만 `hub_promoted: false`인 분류를 `noindex`와 사이트맵 제외로 처리하고, `false`이거나 값이 없으면 기존처럼 모든 공개 분류를 색인하세요. 선언하지 않은 사이트는 이 값을 읽지 않습니다. - 분류가 서버 상한(500개)을 넘으면 응답에 `"truncated": true` 가 붙습니다. `@roottale/cms-client` 로 직접 부를 때: ```ts import { fetchCategoryCounts } from "@roottale/cms-client/server"; const { categories, truncated } = await fetchCategoryCounts({ apiKey: process.env.ROOTTALE_API_KEY!, excludeCollections: true, }); ``` ## GET /v1/cms/public/site-knowledge 사이트 지식 — 브랜드 보이스(어조·톤·화자) + 용어 규칙(금지어·교정어). AI 에이전트가 이 사이트에 맞는 글을 쓸 때 참고. 운영 메모·내부 SEO 임계값·내부 출처는 노출 안 함 (theme-and-settings.md 참고). ```json { "tenant_id": "…", "site_id": "…", "brand": { "voice": "", "tone": "", "persona": "" }, "lexicon": { "forbidden_words": [], "preferred_terms": [{ "from": "유저", "to": "사용자" }] }, "updated_at": null } ``` ## GET /v1/cms/public/business-profile 비즈니스 프로필 (로컬 SEO) — 어드민 "운영 > 비즈니스 프로필" 저장값. 미설정이면 `configured: false` + 필드 `null`. ```json { "tenant_id": "…", "site_id": "…", "configured": true, "name": "길동세무회계", "legal_name": null, "alternate_name": "길동 세무회계", "business_type": "AccountingService", "telephone": "02-1234-5678", "fax_number": "02-1234-5679", "email": null, "address": { "street_address": "테헤란로 123", "address_locality": "강남구", "address_region": "서울특별시", "postal_code": "06234" }, "geo": { "latitude": 37.5006, "longitude": 127.0364 }, "opening_hours": [ { "days": ["Mo","Tu","We","Th","Fr"], "opens": "09:00", "closes": "18:00" } ], "price_range": "₩₩", "area_served": ["서울 강남구"], "services": ["기장·신고대리", "세무고문"], "profiles": { "naver_place": "https://…", "google_business": "https://…", "kakao_channel": null, "kakao_map": "https://…", "instagram": null, "naver_blog": null }, "updated_at": "…" } ``` `business_type`: `LocalBusiness` | `ProfessionalService` | `AccountingService` | `LegalService` | `MedicalClinic` | `Dentist` | `RealEstateAgent` | `Restaurant` | `BeautySalon`. `opening_hours[].reception_closes`는 접수 마감이다. 키 생략은 미지정(이전 데이터), `null`은 안내 해제, `HH:MM`은 지정 시각이며 `opens < reception_closes <= closes`를 검사한다. 저장 스키마와 SDK는 `receptionCloses`로 매핑하고 세 상태를 보존한다. 사업장 정보의 일반 PATCH는 기존과 같이 전달한 설정을 저장하므로 소비자는 키 생략과 `null`을 혼용하지 않는다. 관리자에서 미지정 행을 빈칸 그대로 저장하면 생략을 유지하고, 안내 해제를 선택하거나 이미 지정한 시각을 비우면 `null`로 저장한다. 사이트 계약·SDK 소비 예시는 [Next.js 연결 예시](../examples/nextjs/connected-content.md)를 따른다. | 필드 | JSON-LD 매핑 | |---|---| | `alternate_name` | `alternateName` — 띄어쓰기 변형 등 같은 사업장의 다른 표기 | | `fax_number` | `faxNumber` | | `services` | `hasOfferCatalog` 의 `Offer.itemOffered` 목록 (최대 12개) | | `profiles.kakao_map` | `hasMap` — `naver_place` 가 있으면 그쪽이 우선. **`sameAs` 에는 들어가지 않는다**(프로필이 아니라 위치 링크) | > **주의**: `name`(사업장 이름)이 비어 있으면 `configured: false` 로 내려가고 > `@roottale/cms-client` 의 `fetchBusinessProfile` 은 `null` 을 반환한다 — > 전화·주소만 채우고 이름을 비우면 나머지 입력이 전부 무시된다. ## GET /v1/cms/public/analytics ROOT-ANALYTICS 사이트 ID와 외부 태그 설정. ```json { "tags": [ { "provider": "ga4", "id": "G-XXXXXXX", "enabled": true } ] } ``` `provider`: `ga4` | `clarity` | `meta_pixel` | `naver`. ## GET /v1/cms/public/jwks 웹훅 서명 검증용 site-scoped JWKS 공개키. **site-scoped 키 필수** — 테넌트 전체 키로 호출하면 `400 site_scope_required`. ## GET /v1/public/inquiry-forms/:formId 사이트에 등록한 활성 문의 폼의 현재 발행 정의를 읽습니다. `cms:read` 고객 키를 사이트 서버에서 사용하며, **고객사 전체 키에는 `site_id` 쿼리가 필수**입니다. 사이트 한정 키는 해당 사이트에 고정됩니다. 다른 고객사·사이트의 폼은 조회하거나 접수할 수 없습니다. 비활성·미등록·범위 밖 폼은 `404 not_found`입니다. ```json { "form_id": "01993841-7930-7000-8000-000000000001", "site_id": "01993841-7930-7000-8000-000000000002", "form_key": "quote", "version": 2, "definition": { "title": "견적 문의", "kind": "sales", "fields": [ { "key": "phone", "label": "전화번호", "type": "tel", "role": "phone", "required": true }, { "key": "message", "label": "문의 내용", "type": "textarea", "role": "message", "required": true } ], "requireOneOf": [], "privacyConsentText": "견적 상담을 위한 연락처 수집에 동의합니다.", "successMessage": "문의가 접수되었습니다." } } ``` 한 사이트에 견적·AS 등 폼 ID를 여러 개 등록할 수 있습니다. 각 폼의 버전과 입력 항목은 독립적입니다. 정의 계약은 공개 패키지 `@roottale/inquiry-forms`, SDK는 `fetchInquiryForm`입니다. 응답은 `no-store`로 다룹니다. ## POST /v1/public/inquiry-forms/:formId/submissions 폼별 CRM 접수. `application/json`, `cms:read` 고객 키를 사용합니다. 사이트 범위는 위 GET과 같고 고객사 전체 키에는 body의 `site_id`가 필수입니다. ```json { "site_id": "01993841-7930-7000-8000-000000000002", "version": 2, "answers": { "phone": "010-1234-5678", "message": "옥상 방수 견적을 요청합니다." }, "privacy_consent": true, "idempotency_key": "01993841-7930-7000-8000-000000000005", "placement": "contact/quote" } ``` | 필드 | 필수 | 설명 | |---|---|---| | `site_id` | 고객사 전체 키 사용 시 | 폼이 속한 사이트 ID | | `version` | ✅ | 방문자가 보고 동의한 발행 버전, 양의 정수 | | `answers` | ✅ | 정의의 항목 키에 해당하는 답변. 문자열·문자열 배열·숫자·boolean 타입 보존 | | `privacy_consent` | ✅ | 사용자 명시 동의 `true` | | `idempotency_key` | ✅ | 같은 제출의 재시도에 재사용. 1~200자 `[A-Za-z0-9_-]` | | `placement` | | 폼 배치 식별자 | | `turnstile_token` | | 사이트의 보안 확인 토큰 | | `attribution` | | 유입 객체. 기존 multipart의 `attr_` 접두 없이 `landing_path`, `utm_source` 등 사용 | | `journey` | | 방문 여정 배열, 최대 30개. 기존 multipart의 JSON 문자열과 구분 | 이름·이메일·사업체명을 일괄 필수로 요구하지 않습니다. 서버가 폼의 항목·선택지· 필수 조건을 검증하고 전화 또는 이메일의 연락 수단을 확인합니다. 등록되지 않은 항목·선택지는 거부합니다. 폼의 업무 유형·항목 라벨은 서버 정의를 사용합니다. 새 저장은 `201`, 저장된 동일 키·동일 내용의 재시도는 `200`과 접수증을 반환합니다. ```json { "id": "01993841-7930-7000-8000-000000000003", "inquiry_no": 17, "received_at": "2026-09-12T08:30:00.000Z", "replayed": false } ``` `inquiry_no`는 정수입니다. HTTP `2xx`만으로 성공을 판단하지 말고 접수증을 확인하세요. 응답 유실·서버 오류에는 **동일한 키와 제출 내용 전체**로 다시 요청합니다. 서버는 문의·접수번호·알림 예약을 함께 저장하며 재시도 시 알림을 다시 만들지 않습니다. 이미 저장된 동일 제출은 폼의 변경·중지 후에도 같은 접수증을 반환합니다. 주요 오류는 `400 validation_error`, `409 form_version_conflict`, `409 idempotency_key_conflict`, `404 not_found`, `429 rate_limited`입니다. 필드 검증 오류는 다음 구조를 사용합니다. ```json { "code": "validation_error", "message": "Request validation failed", "hint": null, "retry_after": null, "details": { "field_errors": { "phone": ["연락처를 확인해주세요."] }, "form_errors": [] } } ``` `form_version_conflict`는 새 정의와 동의 문구를 다시 확인한 뒤 제출해야 합니다. `idempotency_key_conflict`에서는 자동으로 새 키를 만들어 중복 접수하지 마세요. SDK `submitFormInquiry`가 접수증 검증과 구조화 오류 반환을 제공합니다. [문의 폼 연동](./inquiries.md)에 같은 사이트의 두 폼을 연결하는 예제가 있습니다. ## POST /v1/public/inquiries 기존 고정 필드 상담문의(리드) 접수. `multipart/form-data`. 새 사이트의 여러 폼은 위의 폼별 JSON 접수를 사용하세요. | 필드 | 필수 | 비고 | |---|---|---| | `vertical` | ✅ | `consulting` \| `medical` \| `tax` \| `legal`. 입력값은 검증·동의 판단에 쓰며, CRM 저장 업종과 상태 구성은 사이트의 업종 설정을 따릅니다. | | `contact_name` | ✅ | | | `business_name` | ✅ | | | `email` | ✅ | `.+@.+\..+` | | `phone` | ✅ | | | `privacy_consent` | ✅ | 체크박스 (`on`) | | `overseas_transfer_consent` | medical 시 ✅ | | | `message`, `consultation_field`, `current_site_url` | | | | `lead_kind` | | `patient`(기본) \| `sales` | | `_redirect_url` | | 완료 후 redirect base (allowlist 검증) | | `cf-turnstile-response` | | Cloudflare Turnstile 토큰. tenant-api에 `LEAD_INTAKE_TURNSTILE_SECRET_KEY`가 설정된 경우 필수 | | `attr_landing_path`, `attr_rt_src`, `attr_utm_source`, `attr_utm_medium`, `attr_utm_campaign`, `attr_utm_term`, `attr_utm_content`, `attr_ad_click`, `attr_referrer`, `attr_first_touch_at`, `attr_last_touch_at`, `attr_last_touch_channel`, `attr_last_touch_source`, `attr_last_touch_medium`, `attr_last_touch_campaign`, `attr_last_touch_referrer` | | 유입 어트리뷰션 — CRM에 유입 경로 표시 (`inquiries.md` 참고). 그 외 `attr_*` 키는 무시 | | `attr_journey` | | 방문 여정 JSON 원문(서버 zod 검증, 최대 30항목) — CRM "방문 여정" 패널에 표시 (`inquiries.md` 참고) | | 기타 임의 필드 | | 최대 50개, 암호화 보관, CRM 상세 노출 | 응답: `302` redirect — 성공 `?ok=1`, 실패 `?err=<code>` (`consent_privacy`, `consent_overseas`, `invalid_vertical`, `missing_fields`, `invalid_email`, `turnstile_failed`, `internal`). 잘못된 키는 `401`. IP/tenant rate limit 초과 시 `429 rate_limited`를 반환합니다. 서버-서버 호출 시 redirect를 따라가지 말고(`redirect: "manual"`) `Location` 헤더를 파싱하세요 — `@roottale/cms-client`의 `submitInquiry`가 이를 대신합니다. ## POST /v1/cms/revalidate 수동 캐시 갱신 트리거 (등록된 웹훅으로 재발송). ```json { "event": "post.updated", "paths": ["/blog", "/blog/my-post"], "slug": "my-post" } ``` `event`는 `post.published` · `post.updated` · `post.deleted` · `theme.updated` 중 하나이고, 생략하면 `post.updated`입니다. 앞의 세 값은 `read_write` 권한 (`cms:write`)으로 보냅니다. **`theme.updated`(설정 저장 신호)만 `read_write_settings` 권한이 필요합니다** ("읽기 + 쓰기 + 설정 변경", scope `settings:write`). 글쓰기 키로 보내면 `403 insufficient_scope`입니다. 이 신호는 경로 몇 개가 아니라 수신 측의 **설정 캐시 이름표 전체와 루트 레이아웃(그 아래 모든 페이지)** 을 다시 만들게 하므로, 글을 쓰라고 내준 키에는 열지 않습니다. ```json { "event": "theme.updated" } ``` 위 "설정 쓰기 API"로 사업장 정보·상단 메뉴를 바꾸면 이 신호는 저장과 함께 자동으로 나갑니다 — 직접 보낼 필요는 없습니다. 자세한 동작은 [재검증 웹훅 문서](./revalidation-webhooks.md#수동-revalidation-api)에 있습니다. ## 에러 형식 비 2xx 응답은 JSON 에러 바디(`code`, `message`)를 가집니다. 주요 코드: `invalid_key`(401), `insufficient_scope`(403), `rate_limited`(429), `not_found`(404). ## 캐시 헤더 공개 콘텐츠 응답은 private 캐시 헤더로 내려갑니다 — CDN 공유 캐시에 의존하지 말고 사이트 측 ISR + 발행 웹훅 조합을 사용하세요.