> ## 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.

# 연락처 생성 또는 갱신

> 이메일로 연락처를 만들거나 갱신하고, 기존 태그를 붙이고, 직접 받은 수신 동의를 기록합니다

**전화번호.** `+`와 국가번호로 시작하는 번호는 그 국가로 저장됩니다. `010-2938-4756`처럼 국가번호가 없는 한국 휴대전화 번호는 한국(+82) 번호로 저장됩니다. 국가 필드는 없으므로 다른 나라 번호는 `+`와 국가번호를 붙여 보내세요.

**처음 본 날.** `firstSeenAt`(RFC 3339, 미래가 아니어야 하며 2000-01-01 이후)을 보내면 연락처가 처음 본 날로 표시되는 날짜(예: 그 사람이 서비스에 가입한 날)를 정할 수 있습니다. 새 연락처와 이미 있는 연락처 모두에 적용되며, 보낼 때마다 저장된 날짜를 바꿉니다. 보내지 않으면 그대로 둡니다.


## OpenAPI

````yaml api-reference/openapi.ko.yaml POST /api/preview/contacts
openapi: 3.1.0
info:
  title: DocuRise 퍼블릭 API
  version: preview
  description: >
    DocuRise 프로그래매틱 접근입니다.


    **이 API는 프리뷰 단계입니다.** 모든 경로는 `/api/preview/` 하위에 버전이 지정되어 있으며,

    프리뷰 단계에서는 호환성을 보장하지 않습니다 — 필드, 값, 에러 코드가 추가, 변경 또는 제거될

    수 있습니다. 계약이 안정화되면 `/api/v1/`로 승격됩니다.

    변경 사항은 [변경 이력](/ko/changelog)에서 확인하세요.


    ### 접근 조건


    모든 라우트는 다음을 요구합니다:

    1. 유효한 API 키 (아래 인증 참고).

    2. 호출하는 계정의 요금제가 **Iconic 이상**이어야 합니다.

    3. 프리뷰 기간 동안 API는 일부 계정에서만 사용이 가능하며, 요금제와는 별개입니다.
       사용할 수 없는 계정은 아래 모든 라우트에서 `404`를 받습니다. 사용할 수 있어야
       하는 계정이라면 DocuRise 담당자에게 문의하세요.

    키 발급 및 관리는 대시보드의 **Settings → Developers**에서 할 수 있습니다.


    ### 멱등성(Idempotency)


    리소스를 생성하는 `POST` 엔드포인트는 `Idempotency-Key` 헤더가 필요합니다. 같은 키와 같은

    요청 본문으로 재요청하면 두 번째 리소스를 만드는 대신 원래 응답(동일한 상태 코드, 동일한

    본문)을 그대로 반환합니다 — 타임아웃이나 연결 끊김 시 안전하게 재시도할 수 있습니다. 키는

    7일 동안 기억되며, 그 이후에 같은 키로 요청하면 새 요청으로 처리됩니다. 같은

    키를 **다른** 본문으로 재사용하면 `IDEMPOTENCY_KEY_CONFLICT`로 거부됩니다. 매 논리적 작업마다

    새로운 키(UUID나 ULID면 충분)를 생성하세요 — HTTP 시도마다 새로 생성하지 마세요.


    예외: `POST /api/preview/tags`는 `Idempotency-Key`를 받지 않습니다. 같은 이름의 태그를 두 번

    만들어도 아무것도 바뀌지 않으므로(두 번째 호출은 기존 태그를 `created: false`로 반환), 재시도는

    항상 안전합니다.


    또 다른 예외: `POST /api/preview/segments/preview`는 `Idempotency-Key`를 받지 않습니다.

    아무것도 저장하지 않으므로 반복 호출해도 항상 안전합니다.


    ### 응답 호환성


    응답은 시간이 지나면서 필드가 추가될 수 있고, `type`/`code` 형태의 열거값(예를 들어 향후

    추가될 `LeadFormQuestion.type` 값이나 새로운 에러 `code`)도 새 값이 늘어날 수 있습니다.

    알지 못하는 필드나 열거값은 항상 무시하고 에러로 취급하지 마세요 — 이것이 `preview` 기간

    동안의 모든 추가적 변경을 하위 호환되게 만드는 원칙입니다.


    응답에서 필드가 아예 없는 것과 값이 `null`로 존재하는 것은 항상 같은 의미가 아닙니다. 타입에

    `null`이 전혀 포함되지 않는 필드는 해당하지 않을 때 아예 생략됩니다 — `null`로 전송되는 일은

    없습니다(예를 들어 `retryAfterSeconds`는 백오프 힌트가 없을 때 완전히 생략되며, `null`로

    설정되지 않습니다). 타입에 `null`을 명시적으로 허용하는 필드는 "값이 없음"과는 구분되는 실제

    의미로 `null`을 사용합니다(예를 들어 문서의 `expiresAt: null`은 "알 수 없음"이나 "해당

    없음"이 아니라, 고정 만료일이 없다는 뜻입니다).


    모든 필드명은 `notionUrl`, `leadFormQuestions`, `collectName` 등과 같이 모든 요청/응답 본문에서

    일관되게 `camelCase`를 사용합니다.


    ### 식별자


    `id` 값은 불투명한(opaque) 문자열입니다. 구조화되지 않은 토큰으로 저장하고 비교하세요 —

    파싱하거나 형식을 검증하거나 길이·문자 구성에 대해 어떤 가정도 하지 마세요.


    ### 에러


    모든 에러 응답은 동일한 형식을 갖습니다:


    ```json

    { "error": { "code": "STRING", "message": "human-readable", "retryable":
    false } }

    ```


    `message`가 아니라 `code`를 기준으로 분기하세요 — `message`는 로그/디버깅용 자유 텍스트이며

    예고 없이 문구가 바뀔 수 있습니다. `code`가 안정적인 계약입니다. `retryable`은 동일한 요청을

    그대로 재시도해도 되는지를 나타내며, 존재할 경우 `retryAfterSeconds`가 구체적인 백오프

    힌트를 제공합니다.


    요청 본문에 데이터베이스가 저장할 수 없는 텍스트가 있으면 아무것도 저장하기 전에

    `400 VALIDATION_ERROR`로 거부됩니다. NUL 문자(`\u0000`)나 짝 없는 서로게이트(문자열을 UTF-16

    단위 사이에서 자를 때 남는 이모지의 반쪽)가 문자열 값이나 속성 이름에 들어 있는 경우입니다.

    온전한 이모지와 그 밖의 문자는 그대로 받아들입니다. `message`는 문제가 된 필드를 알려주며

    텍스트 자체는 되풀이하지 않습니다.


    ### 속도 제한


    계정이 보유한 키 개수와 무관하게, 모든 `/api/preview/*` 라우트에 대해 계정당 분당 60회

    요청으로 제한됩니다. 초과 시 `Retry-After` 헤더와 함께 `429`가 반환됩니다.


    이와 별도로, 계정이 보유한 키 개수와 무관하게 이 라우트들에서 한 계정이 동시에 실행 중인

    요청은 최대 10개입니다. 11번째가 될 요청은 `code: TOO_MANY_CONCURRENT_REQUESTS`와

    `Retry-After: 1`이 담긴 `429`를 반환합니다. 실행 중인 요청 하나가 끝날 때까지 기다린 뒤

    재시도하세요. 이 제한은 아직 끝나지 않은 요청을 세므로, 분당 60회 이내여도 적용될 수 있습니다.
  contact:
    name: DocuRise
    url: https://docurise.io
servers:
  - url: https://docurise.io
    description: 프로덕션
security:
  - apiKey: []
tags:
  - name: Documents
    description: >-
      문서(노션 페이지, 포스트, 리드 수집 폼)를 생성하고, 내가 소유한 문서를 목록 조회하거나 읽고, 초안을 게시하며, 상태, 만료일,
      이메일 보호 설정을 변경하고, 제목, 설명, 포스트 본문, 폼 필드와 질문을 수정합니다.
  - name: Analytics
    description: >-
      내 문서 하나의 조회, 방문자, 리드, 전환 집계 수치를 조회하고, 유입 채널별 분포, 이전 기간과의 비교, 폼 퍼널로도 확인하며,
      내 모든 문서를 조회, 방문자, 리드 기준으로 순위를 매겨 조회합니다.
  - name: Folders
    description: 폴더와 강의를 항목 수와 함께 조회합니다.
  - name: Products
    description: 상품 카탈로그를 조회합니다(읽기 전용).
  - name: Audiences
    description: >-
      태그와 그룹을 연락처 수와 함께 조회하고, 규칙으로 그룹을 만들고, 규칙에 맞는 연락처 수를 미리 세고, 그룹 하나를 규칙과 함께
      조회합니다. 수치만 제공하며 연락처 정보는 절대 반환하지 않습니다.
  - name: Contacts
    description: 내 연락처 하나에 태그를 추가하거나 제거합니다. 연락처 정보는 반환하지 않습니다.
  - name: Email
    description: 이메일 1회성 발송, 1회성 발송별 집계 수치, 자동화를 조회합니다. 이메일만 해당하며 카카오는 포함되지 않습니다.
  - name: Instagram
    description: Instagram 댓글-DM 자동화 규칙을 생성, 조회, 수정, 일시정지, 재개합니다.
  - name: Account
    description: 호출에 사용 중인 API 키를 확인합니다.
paths:
  /api/preview/contacts:
    post:
      tags:
        - Contacts
      summary: 연락처 생성 또는 갱신
      description: |
        이메일 주소로 내 계정의 연락처를 만들고, 이미 있으면 갱신합니다. 이미 가지고 있는
        태그를 붙이고, 직접 받은 마케팅 수신 동의를 기록할 수도 있습니다.
        `contacts:write` 스코프가 필요하며, 이 스코프는 Business 플랜에서만 제공됩니다.
        다른 플랜에서는 `403 PLAN_REQUIRED`가 반환됩니다. 이 스코프가 생기기 전에 만든
        키에는 없으니 설정 → 개발자의 **스코프 수정**에서 추가하세요(키 자체는 바뀌지 않습니다).

        연락처를 새로 만들었으면 `201`, 이미 있었으면 `200`이며, 본문의 `created`가 어느 쪽인지
        알려 줍니다. 이 호출만으로 이메일이 발송되지는 않습니다.

        **갱신이 바꾸는 것.** 보내지 않은 필드, `null`, 빈 문자열은 그대로 둡니다. 이 호출로
        값이 지워지는 일은 없습니다. 비어 있지 않은 `name`, `company`, `phone`은 저장된 값을
        바꿉니다. API 호출은 방문이 아니므로 마지막 활동 시간은 바뀌지 않습니다. 연락처는
        **현재** 주소로만 찾습니다. 예전에 쓰던 주소로 보내면 새 연락처가 만들어집니다.

        **처음 본 날.** `firstSeenAt`(RFC 3339, 미래가 아니어야 하며 2000-01-01 이후)은 연락처가
        처음 본 날로 표시되는 날짜를 정합니다. 새 연락처와 이미 있는 연락처 모두에 적용되므로,
        그 사람이 실제로 서비스에 가입한 날을 가져올 수 있습니다. 보낼 때마다 저장된 날짜를
        바꾸며, 보내지 않으면 그대로 둡니다.

        **태그.** `tags`에는 이미 있는 태그 이름을 최대 10개까지 넣습니다(정확한 이름, 그다음
        NFC 형태 순서로 찾습니다). 없는 이름이 하나라도 있으면 `422 TAG_NOT_FOUND`로 그 이름들을
        알려 주고 아무것도 쓰지 않습니다. 오타로 만들어진 태그를 그룹 규칙이 나중에 잡는 일이
        없도록 하기 위해서입니다. 태그는 `POST /api/preview/tags`로 먼저 만드세요.

        **수신 동의는 직접 보증하고, 올라가기만 합니다.** `consent`를 보내지 않으면 새
        연락처에는 마케팅 수신 동의가 없습니다. `consent.marketing: true`에는 `consent.collectedAt`
        (RFC 3339, 미래 시각 불가)과 `consent.source`(1~96자, 동의를 받은 곳을 알려 주는 이름)가
        모두 필요하고, 하나라도 없으면 `422 CONSENT_EVIDENCE_REQUIRED`가 반환됩니다. DocuRise는
        보낸 내용과 보낸 키를 기록하며, 동의가 실제인지는 호출하는 쪽의 책임입니다. 기존 연락처는
        동의 없음에서 동의로만 바뀌고 되돌아가지 않으며, 처음 기록된 동의가 유지됩니다. 동의 없이
        가져온 것으로 되어 있던 연락처(예: CSV 가져오기)는 이 호출로 동의가 기록되면 마케팅 발송
        대상이 되므로, 실제로 동의한 사람에게만 `marketing: true`를 보내세요. 수신
        거부했거나 주소가 반송 또는 스팸 신고된 연락처는 이 호출로 바뀌지 않습니다. 응답의
        `marketingConsent`는 **저장된** 값이므로, `marketing: true`를 보냈는데 `false`라면 적용되지
        않은 것입니다. 이 호출은 누구의 수신 거부도 만들거나 되돌리지 않습니다.

        **그룹과 자동화.** 연락처의 그룹 소속은 호출 중이 아니라 호출 직후의 다음 예약 실행(5분
        안팎)에서 갱신됩니다. 그 실행이 끝나면 "태그 X가 있음" 규칙의 그룹에 연락처가 포함되고,
        연락처가 **그룹에 들어올 때** 시작하는 자동화는 같은 실행에서 시작됩니다. 한 주기 안에
        들어온 여러 호출은 한꺼번에 처리됩니다. 두 가지를 알아 두세요. 어떤 것을 보지 않았거나 답하지
        않았다는 규칙의 그룹은 이렇게 만든 모든 연락처와 일치합니다. 방문 기록이 없기
        때문입니다. 그리고 "마케팅 수신 동의 필요"를 **끈** 자동화(서비스 안내 메시지)는 수신
        거부하지 않은 연락처라면 동의한 적이 없어도 발송되므로, 모두가 받아야 하는 메시지에만
        쓰세요. 플랜의 리드 한도를 넘는 연락처도 만들어지며 대시보드에서는 잠긴 것으로 보입니다.

        **`Idempotency-Key`는 필수입니다.** 같은 키와 같은 본문은 첫 응답(`201`과
        `created: true` 포함)을 그대로 돌려주므로, 타임아웃 뒤 재시도해도 답이 달라지지 않습니다.
        거절된 요청도 키와 함께 기억됩니다. 원인을 고친 뒤(예: 없던 태그를 만든 뒤)에는 새 키를
        보내세요.
      operationId: upsertContact
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          description: 이 시도를 구분하는, 클라이언트가 만든 고유 문자열(255자 이하). 위의 "멱등성"을 참고하세요.
          schema:
            type: string
            maxLength: 255
          example: 550e8400-e29b-41d4-a716-446655440000
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertContactRequest'
      responses:
        '200':
          description: '연락처가 이미 있었고, 보낸 내용으로 갱신되었습니다(`created: false`).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpsertedContact'
              example:
                id: 3b9f6c52-0f0e-4f3a-9a52-1c1d7e0a8f10
                email: person@example.com
                created: false
                marketingConsent: true
                tags:
                  - signed-up
        '201':
          description: 이 호출이 연락처를 만들었습니다.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpsertedContact'
              example:
                id: 3b9f6c52-0f0e-4f3a-9a52-1c1d7e0a8f10
                email: person@example.com
                created: true
                marketingConsent: false
                tags:
                  - signed-up
        '400':
          description: >-
            `INVALID_JSON`(본문이 JSON이 아님) 또는 `VALIDATION_ERROR`(`email`이 없거나 올바른
            주소가 아님, 필드 길이 초과, 태그 11개 이상, `consent` 형식 오류 또는
            `consent.collectedAt`이 오프셋이 있는 RFC 3339가 아님, `firstSeenAt`이 오프셋이 있는
            RFC 3339가 아니거나 미래 또는 2000년 이전, NUL 문자, 알 수 없는 필드). 아무것도 쓰지 않았습니다.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: >-
            `PAST_DUE_RESTRICTED`, `INSUFFICIENT_SCOPE`(키에 `contacts:write`가 없음)
            또는 `PLAN_REQUIRED`(내 플랜에 이 엔드포인트가 포함되어 있지 않음).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          $ref: '#/components/responses/NotOnAllowlist'
        '409':
          description: |
            `IDEMPOTENCY_KEY_CONFLICT`(재시도 불가: 같은 키를 다른 본문으로 이미 썼으니 새
            키를 쓰세요) 또는 `IDEMPOTENCY_KEY_IN_PROGRESS`(재시도 가능: 이 키의 요청이 아직
            처리 중이며, `retryAfterSeconds`가 대기 시간을 알려 줍니다).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: >
            요청 형식은 맞지만 적용할 수 없습니다. 아무것도 쓰지 않았습니다. 그대로는 재시도해도 같은 결과입니다.

            `TAG_NOT_FOUND`: `tags` 중 내 계정에 없는 것이 있습니다. `details.tags`가 목록입니다.

            `CONSENT_EVIDENCE_REQUIRED`: `consent.marketing`이 `true`인데 과거의
            `collectedAt`과 `source`가 없습니다. `details.problems`가 빠졌거나 잘못된 항목입니다.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                tagNotFound:
                  value:
                    error:
                      code: TAG_NOT_FOUND
                      message: >-
                        One or more tags do not exist. Nothing was written.
                        Create them with POST /tags.
                      retryable: false
                      details:
                        tags:
                          - sigend-up
                consentEvidenceRequired:
                  value:
                    error:
                      code: CONSENT_EVIDENCE_REQUIRED
                      message: >-
                        consent.marketing true needs consent.collectedAt (a past
                        RFC 3339 time) and consent.source
                      retryable: false
                      details:
                        problems:
                          - source_required
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          description: >-
            `INTERNAL_ERROR`(재시도 가능). 서버 쪽 문제이며 원인은 응답에 담기지 않습니다. 같은
            `Idempotency-Key`로 재시도하세요.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          $ref: '#/components/responses/Unavailable'
      security:
        - apiKey: []
      x-codeSamples:
        - lang: bash
          label: curl
          source: |
            curl -X POST 'https://docurise.io/api/preview/contacts' \
              -H 'Authorization: Bearer dr_live_<keyId>_<secret>' \
              -H 'Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000' \
              -H 'Content-Type: application/json' \
              -d '{
                "email": "person@example.com",
                "name": "Ada Lee",
                "firstSeenAt": "2025-12-24T01:02:03Z",
                "tags": ["signed-up"],
                "consent": {
                  "marketing": true,
                  "collectedAt": "2026-11-09T01:02:03Z",
                  "source": "signup-form-v3"
                }
              }'
components:
  schemas:
    UpsertContactRequest:
      type: object
      required:
        - email
      additionalProperties: false
      properties:
        email:
          type: string
          maxLength: 320
          description: 연락처의 이메일 주소. 앞뒤 공백은 제거되고 소문자로 바뀝니다. ASCII 주소여야 합니다.
          example: person@example.com
        name:
          type:
            - string
            - 'null'
          maxLength: 200
          description: 비어 있지 않으면 저장된 이름을 바꿉니다. 보내지 않거나 `null`, 빈 문자열이면 그대로 둡니다.
          example: Ada Lee
        company:
          type:
            - string
            - 'null'
          maxLength: 200
          description: 비어 있지 않으면 저장된 회사명을 바꿉니다. 보내지 않거나 `null`, 빈 문자열이면 그대로 둡니다.
          example: Example Inc
        phone:
          type:
            - string
            - 'null'
          maxLength: 32
          description: >-
            비어 있지 않으면 저장된 전화번호를 바꿉니다. `+`와 국가번호로 시작하는 번호는 그 국가로 저장됩니다.
            `010-2938-4756`처럼 국가번호가 없는 한국 휴대전화 번호는 한국(+82) 번호로 저장됩니다. 국가 필드는
            없으므로 다른 나라 번호는 `+`와 국가번호를 붙여 보내세요. 해석할 수 없는 번호는 보낸 그대로 저장됩니다. 보내지
            않거나 `null`, 빈 문자열이면 그대로 둡니다.
          example: +82 10 2938 4756
        firstSeenAt:
          type: string
          format: date-time
          description: >-
            연락처가 처음 본 날로 표시되는 날짜(예: 그 사람이 서비스에 가입한 날). 오프셋이 있는 RFC 3339 또는 `Z`,
            미래가 아니어야 하며 2000-01-01 이후. 새 연락처와 이미 있는 연락처 모두에서 저장된 날짜를 바꿉니다. 보내지
            않으면 그대로 둡니다(새 연락처는 이 호출의 시각이 됩니다).
          example: '2025-12-24T01:02:03Z'
        tags:
          type: array
          maxItems: 10
          items:
            type: string
          description: >-
            이미 가지고 있는 태그 이름, 최대 10개. 없는 이름이 있으면 `422 TAG_NOT_FOUND`이고 아무것도 쓰지
            않습니다.
          example:
            - signed-up
        consent:
          type: object
          required:
            - marketing
          additionalProperties: false
          description: 직접 받은 마케팅 수신 동의. 동의를 주지 않으려면 생략하세요.
          properties:
            marketing:
              type: boolean
              description: >-
                `true`는 동의를 기록하며 `collectedAt`과 `source`가 함께 필요합니다. `false`는
                아무것도 기록하지 않고 이미 있는 동의를 철회하지도 않습니다.
            collectedAt:
              type: string
              format: date-time
              description: 동의한 시각. 오프셋 또는 `Z`가 있는 RFC 3339이며 미래 시각은 안 됩니다.
              example: '2026-11-09T01:02:03Z'
            source:
              type: string
              maxLength: 96
              description: 동의를 받은 곳(내 폼이나 흐름)을 알려 주는 이름.
              example: signup-form-v3
    UpsertedContact:
      type: object
      required:
        - id
        - email
        - created
        - marketingConsent
        - tags
      properties:
        id:
          type: string
          format: uuid
          description: 연락처의 id.
        email:
          type: string
          description: 저장된 주소(공백 제거, 소문자).
        created:
          type: boolean
          description: 이 호출이 연락처를 만들었으면 `true`, 이미 있었으면 `false`.
        marketingConsent:
          type: boolean
          description: >-
            연락처가 **지금** 가진 마케팅 수신 동의. `marketing: true`를 보냈는데 `false`라면 적용되지 않은
            것입니다(수신 거부했거나 주소가 차단됨).
        tags:
          type: array
          items:
            type: string
          description: 이 호출이 붙인 태그의 저장된 이름. 모두 지금 연락처에 붙어 있습니다.
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - retryable
          properties:
            code:
              type: string
              description: 안정적인 기계 판독용 에러 코드입니다 — `message`가 아니라 이 값을 기준으로 분기하세요.
            message:
              type: string
              description: 사람이 읽을 수 있는 상세 설명입니다. 예고 없이 문구가 바뀔 수 있습니다.
            retryable:
              type: boolean
              description: 동일한 요청을 재시도했을 때 성공할 가능성이 있는지 여부입니다.
            retryAfterSeconds:
              type: integer
              description: 구체적인 백오프 힌트가 있는 경우에만 존재합니다.
            details:
              type: object
              description: >
                일부 특정 코드에만 존재합니다:

                - `PROTECTION_RULE_CONFLICT`: `{ rule: string }`, 요청을 거부한 보호
                규칙입니다
                  (`form`, `restricted_access`, `paid_lead_gate`, `free_lead_gate`,
                  `form_no_access_controls` 또는 `needs_email_gate`).
                  열려 있는 값입니다. 새 값을 허용하세요.
                - `NEXT_POST_RULE_EXISTS`: `{ ruleId: string }`, 이미 있는 "다음 게시물"
                규칙입니다.

                - `NOTION_FETCH_FAILED`: `{ notionErrorCode: string }`, 다음 중
                하나입니다:
                  `NOTION_ERROR_PRIVATE`, `NOTION_ERROR_NOT_FOUND`,
                  `NOTION_ERROR_NETWORK`, `NOTION_ERROR_RATE_LIMIT`,
                  `NOTION_ERROR_TEMPORARILY_UNAVAILABLE`,
                  `NOTION_ERROR_PAGE_REJECTED`, `NOTION_ERROR_UNKNOWN`.
                - `HTML_REJECTED`: `{ reason: string }`, `too_large`,
                `css_rejected`, `invalid` 중 하나입니다.
                  열려 있는 값입니다. 새 값을 허용하세요.
                - `CONDITION_NOT_SUPPORTED`: `{ field: string, path: string }`,
                받지 않는 조건 타입과 그 조건이
                  요청에서 있는 위치입니다. 그 위치에서 거부된 조건 형태에는 `operator: string`이,
                  `requiredConditions`에서 대신 쓸 수 있는 연산자가 있으면 `invertTo: string`도 더해집니다.
                - `REFERENCE_NOT_FOUND`: `{ path: string, kind: string }`, 알 수
                없는 id가 요청에서 있는 위치와
                  그 id가 가리키는 대상(`document`, `product`, `tier`, `cta`, `folder`, `broadcast`, `step`)입니다.
                  열려 있는 값입니다. 새 값을 허용하세요.
                - `TAG_NOT_FOUND`(그룹 규칙에서): `{ tag: string }`, 존재하지 않는 태그 이름입니다.

                - `GROUP_REFERENCE_NOT_FOUND`: `{ groupIds: string[] }`, 계정에 없는
                그룹 id입니다.

                - `GROUP_LIMIT_REACHED`: `{ limit: integer }`, API로 계정이 만들 수 있는
                그룹의 최대 개수입니다.
          description: >-
            오류 정보입니다. API의 모든 오류 응답에 들어 있으며 `code`, `message`, `retryable`을 담고,
            일부 코드에는 `retryAfterSeconds`와 `details`도 담깁니다.
  responses:
    Unauthorized:
      description: '누락되었거나 형식이 잘못되었거나 폐기된 API 키입니다(`code: UNAUTHORIZED`).'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotOnAllowlist:
      description: |
        API는 일부 계정에서만 사용이 가능하며, 요금제와는 별개입니다. 사용할 수
        있어야 하는 계정이라면 DocuRise 담당자에게 문의하세요 (`code: NOT_FOUND`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimited:
      description: >-
        속도 제한에 걸렸습니다 (`code: RATE_LIMITED`, 항상 재시도 가능): `Retry-After` 헤더와
        `X-RateLimit-*` 헤더를 참고하세요. 또는 동시에 실행 중인 요청이 너무 많습니다 (`code:
        TOO_MANY_CONCURRENT_REQUESTS`, 항상 재시도 가능): `Retry-After`는 `1`이고
        `X-RateLimit-*` 헤더는 없습니다.
      headers:
        Retry-After:
          schema:
            type: integer
        X-RateLimit-Limit:
          schema:
            type: integer
        X-RateLimit-Remaining:
          schema:
            type: integer
        X-RateLimit-Reset:
          schema:
            type: integer
          description: 제한이 초기화되는 유닉스 타임스탬프(초)입니다.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unavailable:
      description: |
        서버 측 의존성이 일시적으로 다운되었습니다(`RATE_LIMIT_UNAVAILABLE` 또는
        `SERVICE_UNAVAILABLE`). 요청이나 키의 문제가 아니며, 항상 재시도 가능합니다 —
        `retryAfterSeconds`가 있으면 그에 따르세요. 그룹 엔드포인트(`POST /segments`,
        `POST /segments/preview`, `GET /segments/{id}`)는 매우 무거운 규칙의 인원을 약 10초
        안에 셀 수 없을 때도 이 코드를 반환합니다. 규칙을 단순하게 만들거나 다시 시도하세요.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: dr_live_<keyId>_<secret>
      description: |
        Settings → Developers에서 발급한 키를 `Authorization: Bearer
        dr_live_<12자리 16진수>_<64자리 16진수>` 형태로 전송합니다. 키는 명시적인 범위를
        가지며 — 각 엔드포인트에 필요한 범위가 해당 엔드포인트에 명시되어 있습니다. 전체 키는 발급 시점에 딱 한
        번만 표시되며 다시 조회할 수 없습니다 — 이후에는 `keyId` 접두어만 표시됩니다. 폐기된
        키는 바로 다음 요청부터 인증에 실패합니다.

````

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