> ## Documentation Index
> Fetch the complete documentation index at: https://docurise.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 변경 이력

> DocuRise 공개 API의 변경 사항, 최신순

API 호출에 영향을 주는 `/api/preview/*`의 변경 사항을 최신순으로 정리합니다. 날짜는 UTC
기준입니다. 이 API는 프리뷰 단계라 호환성을 보장하지 않습니다. **호환성 변경**은 기존 연동이
실패할 수 있는 변경을 뜻하며, 각 항목에 무엇을 바꿔야 하는지 적혀 있습니다.

**2026-10-23**

그룹 인원 수 계산은 10초 뒤에 중단됩니다

**동작 변경:** 그룹 규칙에 맞는 연락처 수를 세는 작업이 이제 약 10초 뒤에 중단됩니다.
`POST /api/preview/segments`, `POST /api/preview/segments/preview`,
`GET /api/preview/segments/{id}`에 적용됩니다. 매우 무거운 규칙은 이제
`retryable: true`가 포함된 `503 SERVICE_UNAVAILABLE`을 반환합니다. 규칙을 단순하게
(조건을 줄이거나 가벼운 조건으로) 바꾸거나 다시 시도하세요. 만들기 요청이 시간 초과되면 아무것도
만들어지지 않으며 같은 `Idempotency-Key`를 다시 보낼 수 있습니다.

**2026-10-23**

그룹 만들기와 조회

**신규:** 이제 API로 그룹을 만들고 조회할 수 있습니다.
`POST /api/preview/segments`는 규칙으로 그룹을 만들며, `Idempotency-Key`와 새 `segments:write`
범위가 필요합니다. `POST /api/preview/segments/preview`는 아무것도 저장하지 않고 규칙에 맞는
연락처 수를 세고, `GET /api/preview/segments/{id}`는 그룹 하나를 규칙과 멤버 수와 함께
반환합니다. 두 엔드포인트는 `automations:read`만 있으면 됩니다. 수치만 반환하며 연락처 정보는
반환하지 않습니다. 이전에 만든 키에는 `segments:write`가 없으니 **Settings → Developers**의
**Edit scopes**에서 추가하세요. `GET /api/preview/segments`는 바뀌지 않았습니다.
[그룹 만들기](https://docurise.io/docs/ko/api-reference/create-segment.md)와
[그룹 조건](https://docurise.io/docs/ko/api-reference/group-conditions.md)을 참고하세요.

**2026-10-21**

태그 만들기

**신규:** `POST /api/preview/tags`로 이름만으로 태그를 만들 수 있습니다. `contacts:tag` 범위가
필요하고 `Idempotency-Key`는 필요 없습니다. 같은 이름으로 다시 호출하면 기존 태그를
(`created: false`) 돌려주고, 대소문자나 앞뒤 공백만 다른 이름은 `409 TAG_ALREADY_EXISTS`로
거부됩니다. [태그 만들기](https://docurise.io/docs/ko/api-reference/create-tag.md)를 참고하세요.

**2026-10-20**

요청 제한

**동작 변경:** 이제 `/api/preview/*`의 제한은 계정당 분당 60회이며, 기존 30회에서 늘었습니다.
또한 계정은 동시에 실행 중인 요청을 최대 10개까지 가질 수 있습니다. 11번째 요청은
`429 TOO_MANY_CONCURRENT_REQUESTS`와 `Retry-After: 1`로 거절되며 그대로 재시도해도 됩니다.
자세한 내용은 [에러](https://docurise.io/docs/ko/errors.md#속도-제한)를 참고하세요.

**2026-10-16**

상품에 가격 방식 필드 추가

**새 필드:** `GET /api/preview/products`의 각 항목에 이제 `pricingModel`(`fixed` 또는 `phased`)이
포함됩니다. `phased` 상품은 일정에 따라 가격이 바뀌므로 하나의 가격으로 나타낼 수 없습니다. 이때
`priceMinor`는 기본 가격일 뿐이며 설정되지 않았다면 `0`입니다. `priceMinor`를 쓰기 전에
`pricingModel`을 먼저 확인하세요. 기존 필드는 모두 그대로입니다.

**2026-10-15**

입력 검사 강화

**호환성 변경:** 아래 요청은 그동안 받아들여지거나, 무시되거나, `500`으로 응답했지만 이제 문제가 된
필드를 알려주는 `400 VALIDATION_ERROR`입니다.

* `POST /documents`, `POST /instagram/rules` 요청 본문의 속성 이름에 NUL 문자(`\u0000`)가 있는
  경우.
* `kind: form`인 `POST /documents`에서 `leadFormQuestions` 항목 안에 알 수 없는 키가 있는 경우.
* `GET /tags`와 `GET /segments`에서 반복된 쿼리 파라미터, 그리고 `GET /instagram/rules`에서
  `status`가 아닌 반복된 파라미터.
* 목록 엔드포인트의 `q` 검색 파라미터에 NUL 문자가 있는 경우.

**동작 변경:**

* `q`는 앞뒤 공백이 제거되고 일반 텍스트로 비교됩니다. `%`와 `_`는 더 이상 와일드카드가 아닙니다.
* `GET /instagram/rules`: 100을 넘는 `limit`은 `400` 대신 100으로 처리됩니다. 다른 목록과
  같습니다.
* `PATCH /documents/{id}`: `GET`이 반환한 `ETag` 헤더 값을 `revision`으로 그대로 보낼 수 있습니다.

**2026-10-14**

문서 revision을 요청 본문으로 이동

**호환성 변경:** `PATCH /api/preview/documents/{id}`는 이제 문서의 revision을 `If-Match` 헤더가
아니라 JSON 본문의 `revision` 필드로 받습니다. `GET /api/preview/documents/{id}`(또는 직전
`PATCH` 응답)의 `revision`을 보내세요. `If-Match`나 `If-Unmodified-Since` 헤더가 있는 요청은
`400 VALIDATION_ERROR`로 거절됩니다. 헤더를 빼세요.

**동작 변경:** `kind: post`와 `status: live`(기본값)로 보내는 `POST /api/preview/documents`는 이제
초안을 게시할 때와 같은 내용 검사를 거칩니다. 내용이 없는 포스트는 `422 EMPTY_BODY`,
`{recipient_name}` 같은 이메일 변수가 포함된 포스트는 `422 UNSUPPORTED_VARIABLE`입니다. 검사를
건너뛰려면 `status: draft`로 생성하세요.

**2026-10-08**

일시정지 상태로 Instagram 규칙 생성

`POST /api/preview/instagram/rules`가 `status: active | paused`(기본값 `active`)를 받습니다.
`status: paused`와 `schedule.batchSendAt`을 함께 보내면 `422 BATCH_RULE_NOT_PAUSABLE`입니다.

**2026-10-07**

엔드포인트 정리: 문서 리소스 통합, 상태는 PATCH로

**호환성 변경.** 작업(operation)이 28개에서 22개로 줄었습니다.

* **제거:** `POST /posts`, `POST /forms`. `kind: notion | post | form`과 함께
  `POST /documents`를 사용하세요.
* **제거:** `GET`, `PATCH /documents/{id}/settings`. 이제 `GET /documents/{id}`가 만료, 보호 설정,
  `revision`을 반환하고, `PATCH /documents/{id}`가 기존 설정 필드를 받아 `GET`과 같은 형태로
  응답합니다.
* **대체:** 생성 시 `isDraft` 대신 `status`(`draft | live`, 기본값 `live`. Notion 문서는 `live`)를
  사용합니다. 생성 시점의 `status: inactive`는 `422 STATUS_NOT_SUPPORTED`입니다. 다른 `kind`에
  같은 `Idempotency-Key`를 쓰면 `409 IDEMPOTENCY_KEY_CONFLICT`입니다.
* **제거:** `POST /instagram/rules/{id}/pause`, `.../resume`. 대신 `status: paused` 또는
  `status: active`만 담아 `PATCH /instagram/rules/{id}`를 보내세요. 다른 필드와 함께 보낸
  `status`는 `422 STATUS_CHANGE_MUST_BE_ALONE`입니다.
* **제거:** `DELETE /instagram/rules/{id}`(이제 `405`).

**2026-10-05**

응답 필드 정리와 Instagram 소문자 값

**호환성 변경.**

* `GET /documents`, `GET /documents/{id}`: `viewCount`와 `leadCount`가 제거되었습니다. 애널리틱스
  엔드포인트를 사용하세요.
* `403 DOCUMENT_LIMIT_REACHED`에 더 이상 `details`가 없습니다.
* `422 PROTECTION_RULE_CONFLICT`는 변경을 거절한 규칙을 `details.rule`로 반환합니다.
* `GET /products`: `sales`, `usageCount`, `archived` 쿼리 파라미터가 제거되었습니다(`archived`는
  이제 `400`입니다. `status`로 필터링하세요).
* `GET /automations`: `triggerType`은 문서화된 목록이며, 목록에 없는 트리거는 `other`입니다.
* `GET /documents/{id}/analytics/channels`: 문서화된 채널에 속하지 않는 유입은 `other`로 묶이므로,
  채널별 조회수의 합이 전체 조회수와 같습니다.
* Instagram 규칙은 소문자 값을 사용합니다: `status`는 `waiting_for_post`, `active`, `scheduled`, `expired`, `paused` 중 하나, `type`은 `standard`, `target.type`은 `next_post`입니다(둘 다 이제 선택
  사항). 기존 대문자 값은 `400`입니다.
* Instagram 에러 코드 이름 변경: `PRESET_RULE_EXISTS`는 `NEXT_POST_RULE_EXISTS`로,
  `RULE_PARKED`는 `BATCH_SEND_MISSED`로, `PLAN_UPGRADE_REQUIRED`는 `PLAN_REQUIRED`로 바뀌었습니다.

**2026-10-04**

초안 게시, 보호 설정, 애널리틱스 추가

* 초안 포스트나 폼은 `PATCH /documents/{id}`에서 `status: live`로 게시합니다.
* 같은 엔드포인트에 이메일 보호 필드가 추가되었습니다: `requireEmail`,
  `requireEmailVerification`, `allowedEmails`, `allowedDomains`. 문서 구성과 충돌하는 변경은
  `422 PROTECTION_RULE_CONFLICT`입니다.
* 애널리틱스: 문서 애널리틱스의 `compare=previous`, 그리고
  `GET /documents/{id}/analytics/channels`, `GET /documents/{id}/analytics/funnel`(폼),
  `GET /analytics/documents`(조회수, 고유 방문자, 리드 기준 문서 순위).
* **호환성 변경:** `GET /whoami`는 `{ "scopes": [...] }`만 반환합니다.
* 폼의 날짜 질문은 항상 허용되며, `403 LEAD_FORM_DATE_QUESTION_DISABLED`는 더 이상 반환되지
  않습니다.

**2026-10-03**

조회 엔드포인트와 연락처 태그

* 조회 엔드포인트 10개: 문서(목록과 상세), 문서 애널리틱스, 폴더와 코스, 상품, 태그, 그룹,
  이메일 1회성 발송과 인사이트, 자동화. 목록은 커서 페이지네이션을 사용합니다(`limit` 기본값 20,
  최대 100).
* `PUT`, `DELETE /contacts/{contactId}/tags/{tagName}`로 연락처 1명에 기존 태그 하나를 추가하거나
  제거합니다(새 범위 `contacts:tag`).

**2026-10-02**

범위, whoami, Instagram 규칙

* 새 범위 `documents:read`, `email:read`, `automations:read`, `products:read`, `contacts:tag`. 기존
  키에는 **Settings → Developers**의 **Edit scopes**로 범위를 추가할 수 있습니다.
* `GET /whoami`는 호출에 사용한 키의 범위를 보여 줍니다.
* 결제가 연체된 계정은 결제 수단을 업데이트할 때까지 모든 라우트에서
  `403 PAST_DUE_RESTRICTED`를 받습니다.
* Instagram DM 규칙: 계정의 다음 게시물 규칙을 생성, 목록 조회, 조회, 수정합니다(범위
  `instagram:write`, `instagram:read`).

**2026-10-01**

더 엄격한 요청 본문, 키 교체 후에도 유지되는 멱등성

* **호환성 변경:** 생성 요청은 알 수 없는 본문 필드를 무시하지 않고 `400 VALIDATION_ERROR`로
  거절합니다.
* `Idempotency-Key`는 API 키 하나가 아니라 계정에 속하므로, 새로 교체한 키로 보낸 재시도도 원래
  응답을 재생합니다.

**2026-09-22**

프리뷰 출시

`POST /api/preview/documents`로 공개된 Notion 페이지에서 문서를 생성합니다. `Idempotency-Key`가
필수이며 계정별 속도 제한이 적용됩니다. API 키는 **Settings → Developers**에서 관리합니다.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.