---
title: "下書きを作る"
method: POST
path: "/knowledge/drafts"
tags: ["Drafts"]
---

# 下書きを作る

`POST /knowledge/drafts`

## Request

- Base URL: `https://api.leafchat.app/api/v1`
- URL: `https://api.leafchat.app/api/v1/knowledge/drafts`
- Auth: HTTP bearer

AI エージェントの用途の API キーで、ナレッジの変更の提案を作る。公開はダッシュボードで人が行う（API からは公開できない）。

operation ごとに必須の欄：create は filename・content・content_type、update は document_id と content（content_type と一緒に）か edits のどちらか一方、delete は document_id。

edits は今の本文に当てた全文として保存する。base_revision_id を渡すと、今の版と違うときに 412 になる。

evidence には、提案の根拠の会話と未回答の ID を入れる（組織に無い ID と、内部の会話の ID は 422）。公開すると根拠の未回答はアーカイブされる。

未処理の下書きは組織で 100 件まで（409 draft_limit_exceeded）。本文は 6 MiB まで。

## Request body

- union
  - CreateDraftOfCreate
    - `operation` 'create', required
    - `source_id` string
    - `folder_id` string
    - `external_id` string: 外部 ID は、ソースの中で一意の文字列です。UTF-8 で 512 バイトまで、Unicode の NFC にそろえ、`/` で区切れます。空の区切り・`.`・`..`・区切りの前後の空白・制御文字・`\` は使えません。例：`faq/shipping`、`渋谷店/営業時間.md`
    - `filename` string, required
    - `content` string, required
    - `content_type` 'text/markdown' | 'text/plain' | 'application/json', required
    - `summary` string, required
    - `rationale` string, required
    - `evidence` object: 提案の根拠。組織に無い ID と、内部の会話の ID は 422。公開すると根拠の未回答はアーカイブされる
      - `conversation_ids` string[]
      - `unanswered_question_ids` string[]
  - CreateDraftOfUpdate
    - `operation` 'update', required
    - `document_id` string, required
    - `base_revision_id` string: 読んだ版（GET の ETag の中身）。今の版と違えば 412。無ければ今の head を基準にする
    - `filename` string
    - `content` string
    - `content_type` 'text/markdown' | 'text/plain' | 'application/json'
    - `edits` object[]
      - `old_text` string, required
      - `new_text` string, required
    - `summary` string, required
    - `rationale` string, required
    - `evidence` object: 提案の根拠。組織に無い ID と、内部の会話の ID は 422。公開すると根拠の未回答はアーカイブされる
      - `conversation_ids` string[]
      - `unanswered_question_ids` string[]
  - CreateDraftOfDelete
    - `operation` 'delete', required
    - `document_id` string, required
    - `base_revision_id` string: 読んだ版（GET の ETag の中身）。今の版と違えば 412。無ければ今の head を基準にする
    - `summary` string, required
    - `rationale` string, required
    - `evidence` object: 提案の根拠。組織に無い ID と、内部の会話の ID は 422。公開すると根拠の未回答はアーカイブされる
      - `conversation_ids` string[]
      - `unanswered_question_ids` string[]

## Response `201`

作った下書き

- Draft
  - `id` string, required
  - `operation` 'create' | 'update' | 'delete', required
  - `state` 'open' | 'published' | 'discarded', required
  - `summary` string, required
  - `rationale` string, required
  - `evidence` object, required
    - `conversation_ids` string[], required
    - `unanswered_question_ids` string[], required
  - `document_id` string, nullable, required: 更新・削除の対象の文書。作成では null
  - `base_revision_id` string, nullable, required: 下書きを作ったときの、対象の文書の head の版
  - `stale` boolean, required: 下書きを作った後に、対象の文書が変わったか消えた。公開する人が置き換えを選ばないと公開できない
  - `target` object, nullable, required: 対象の文書の今の状態。作成では null
    - `exists` boolean, required
    - `filename` string, nullable, required
    - `head_revision_id` string, nullable, required
  - `source_id` string, nullable, required
  - `folder_id` string, nullable, required
  - `external_id` string, nullable, required
  - `filename` string, nullable, required: 提案のファイル名。削除では null
  - `mime` string, nullable, required
  - `size` integer, nullable, required
  - `content_sha256` string, nullable, required
  - `author` object, required
    - `type` 'operator' | 'api_key', required
    - `id` string, nullable, required
    - `via` 'mcp' | 'api', required
  - `published_document_id` string, nullable, required
  - `published_revision_id` string, nullable, required
  - `created_at` string, date-time, required
  - `decided_at` string, date-time, nullable, required

## Other responses

- `400`: 要求の形式か値が正しくない。errors（検証の誤り）に項目（path）ごとの理由が入る 返る code：`invalid_request`・`empty_manifest`・`duplicate_item`
- `401`: API キーが無いか無効（期限切れ・失効・削除の途中の組織を含み、理由は区別しない） 返る code：`unauthorized`
- `403`: この API キーの用途か、対象のソースでは実行できない 返る code：`forbidden`・`needs_draft`
- `404`: 指定した ID かパスが無い（ほかの組織の ID も同じ応答になる）。削除した文書は、削除の起票が保守の GC で消えるまで DELETE が already_deleted を返し、その後は 404 返る code：`not_found`
- `409`: 今の状態と合わない。code で見分ける 返る code：`source_locked`・`limit_exceeded`・`delete_limit_exceeded`・`folder_not_found`・`folder_limit_exceeded`・`upload_required`・`upload_not_expected`・`sync_in_progress`・`not_sync_source`・`same_name_exists`・`external_id_taken`・`draft_limit_exceeded`・`already_decided`・`not_retryable`
- `412`: If-Match（下書きの作成では base_revision_id）の版が、今の head の版と違う。存在しない文書へ If-Match を付けた upsert でも返る 返る code：`precondition_failed`
- `413`: 本文が上限を超えた（JSON 6 MiB・multipart 16 MiB・同期 8 MiB・同期のアップロード 15 MiB）。テキストの本文が 4 MiB を超えたときは、本文の上限の内側でも 422 invalid_request になる 返る code：`payload_too_large`
- `415`: Content-Type が、その操作の受け付ける形式でない。文書の作成に application/x-www-form-urlencoded で送ると、415 ではなく 400 になる 返る code：`unsupported_media_type`
- `422`: 内容を受け付けられない（編集の対象・分割の上限・形式・同期の項目・アップロードの中身など）。code で見分ける 返る code：`invalid_request`・`edit_no_match`・`edit_ambiguous`・`not_editable`・`too_many_parts`・`invalid_item`・`upload_mismatch`
- `429`: 上限を超えた。Retry-After の秒数だけ待ってからやり直す。上限は、API キーごとに 1 分 120 回（REST と MCP で共通）・同期の実行は鍵ごとに 1 分 10 回（dry_run は数えない）・組織の文書の書き込みは 1 分 300 版・API キーの検証の失敗は IP ごとに 1 分 20 回（超えると、正しい鍵でも 429 になる）。このほか、IP ごとの上限を超えると Cloudflare が 429（error code 1015）を返す。この応答は problem+json でないことがあり、Retry-After が無ければ少し待ってからやり直す 返る code：`rate_limited`
- `500`: サーバーで問題が起きた。少し待ってからやり直す 返る code：`internal_error`
- `503`: 保存かキューへの送信に失敗した（storage_failed）。Retry-After の秒数だけ待ってからやり直す。search_unavailable は今の操作からは返らない（変換の口と MCP のために目録に残している） 返る code：`storage_failed`・`search_unavailable`

---

[API](https://skmtc.dev/leafchat/apis/leafchat-api.md) · [All operations](https://skmtc.dev/leafchat/apis/leafchat-api/llms.txt) · [OpenAPI document](https://skmtc.dev/leafchat/apis/leafchat-api/revisions/2667db05c2ff?raw)