> ## 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로 첫 문서를 생성해 보세요

> [!NOTE]
>
> API는 일부 계정에서만 사용이 가능합니다. 키 발급이 비활성화되어 있거나 API가 `404`를 반환한다면
> DocuRise 담당자에게 문의하세요.

## 1. API 키 발급하기

대시보드에서 **Settings → Developers**로 이동해, 키 이름을 지정하고(여러 키를 구분하기 위해), 필요한 범위(scope)를 선택한 뒤 발급하세요. 이 가이드에서는 `documents:write`가 필요합니다. 키는 즉시 복사해 두세요 — 전체 값은 딱 한 번만 표시됩니다.

## 2. 문서 생성하기

```bash theme={null}
curl -X POST https://docurise.io/api/preview/documents \
  -H "Authorization: Bearer dr_live_<keyId>_<secret>" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "notion",
    "title": "Q3 Product Roadmap",
    "notionUrl": "https://www.notion.so/myworkspace/Q3-Roadmap-abc123def456"
  }'
```

노션 페이지는 반드시 웹에 게시(공개 공유)되어 있어야 합니다 — DocuRise는 별도의 노션 연동 없이 인증 없이 페이지를 가져옵니다.

`Idempotency-Key`는 모든 생성 요청에 필수입니다. 같은 키와 같은 요청 본문으로 재요청하면 새 문서를 만드는 대신 원래 응답을 그대로 반환합니다 — 타임아웃 시 안전하게 재시도할 수 있습니다.

### 코드를 직접 작성하지 않는다면? Zapier, n8n 등에서 설정하는 방법

`Idempotency-Key`는 재시도(직접 재시도하거나, 자동화 도구가 타임아웃 후 자동으로 재시도하는 경우 모두) 때문에 문서가 두 번 생성되는 것을 막기 위한 값입니다. 다만 제대로 설정해야만 효과가 있습니다:

> [!TIP]
>
> **이렇게 하세요:** 같은 문서를 만드는 시도라면 항상 같은 값, 다른 문서라면 다른 값이 되도록
> 설정하세요 — 보통 이 자동화를 트리거한 대상의 고유 ID(노션 페이지 ID, 폼 제출 ID, 스프레드시트 행
> ID 등)를 사용하면 됩니다.

> [!WARNING]
>
> **이렇게 하지 마세요:** "무작위 ID 생성" 단계를 사용하지 마세요. 시도할 때마다 값이 바뀌는 키는
> 아무런 보호 효과가 없습니다 — 재시도를 안전하게 처리하는 것처럼 보이지만, 실제로는 무작위 값
> 때문에 재시도할 때마다 문서가 중복 생성됩니다.

**Zapier**

액션 단계(예: "Webhooks by Zapier" → Custom Request, 또는 커스텀 앱의 Create 액션)에서 `Idempotency-Key` 필드를 Formatter의 "random" 유틸리티로 생성하지 말고, 트리거 단계의 고유 필드에 직접 매핑하세요. 예를 들어 트리거가 새 노션 페이지라면, 해당 페이지의 ID에 매핑합니다:
`create-doc-{{Trigger: Page ID}}`.

**n8n**

HTTP Request 노드의 헤더에서 `Idempotency-Key`를 Crypto/무작위 ID 노드가 아니라, 이전 노드의 데이터를 참조하는 표현식으로 설정하세요. 예:
`create-doc-{{ $json.pageId }}`.

## 3. 응답 확인하기

성공 시 `201` 상태 코드와 함께 문서 id와 공개 URL이 반환됩니다:

```json theme={null}
{
  "id": "clx1y2z3a4b5c6d7e8f9g0h1",
  "url": "https://docurise.io/v/q3-product-roadmap"
}
```

API 에러는 동일한 JSON 형식을 사용합니다 — 전체 에러 코드와 재시도 여부, 대응 방법은 [에러](https://docurise.io/docs/ko/errors.md)를 참고하세요.

## 다음 단계

* [인증](https://docurise.io/docs/ko/authentication.md) — 범위(scope), 키 로테이션, 폐기(revoke) 방법
* [문서 생성 레퍼런스](https://docurise.io/docs/ko/api-reference/create-document.md) — 전체 요청/응답 계약


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