# leafchat API

ナレッジの読み書きと同期の REST API

- 人向けの表示：<https://api.leafchat.app/api/v1/docs>
- OpenAPI（JSON）：<https://api.leafchat.app/api/v1/openapi.json>
- MCP の案内：<https://api.leafchat.app/mcp.md>
- llms.txt：<https://leafchat.app/llms.txt>

## 基本

- ベース URL：`https://api.leafchat.app/api/v1`
- 認証：`Authorization: Bearer <API キー>`。ダッシュボードで発行した API キー（lck_ で始まる）
- 版：1.0.0（OpenAPI 3.1.0）

## 概要

ナレッジの読み書きと同期の API。認証は Authorization: Bearer lck_…

- AI エージェント向けの Markdown 版：<https://api.leafchat.app/api/v1/docs.md>
- MCP サーバー：`https://api.leafchat.app/mcp`（接続のしかたとツールの一覧：<https://api.leafchat.app/mcp.md>）
- 公式の CLI と GitHub Action：<https://github.com/leafchat/cli>

- JSON のキーは snake_case、時刻は ISO 8601（UTC）。
- 書き込みは 202 で受け付ける。反映の状態は GET の current_revision と head_revision で確かめる。
- 楽観ロック：GET の ETag（"<head の版の ID>"）を If-Match に入れる。本文を変える PATCH では必須。
- 誤りは RFC 9457（application/problem+json）。code で種類を見分ける。
- テキストの本文は、分割の上限（3 KiB × 512 個）が先に効き、実際は約 1.5 MiB まで（422 too_many_parts）。

## 誤りのコード

| code | 状態 | 意味と直し方 |
| --- | --- | --- |
| `invalid_request` | 400・411・422 | 要求の形式か値が正しくない。errors（項目ごとの理由）か detail を見て直す |
| `empty_manifest` | 400 | 同期で送った一式が空。ソースの文書をすべて消すときは allow_empty を true にする |
| `duplicate_item` | 400 | 同期で送った一式に、同じ external_id か path が複数ある。重複を除いて送る |
| `unauthorized` | 401 | API キーが無いか無効（期限切れ・失効・削除の途中の組織を含み、理由は区別しない）。ダッシュボードで有効な鍵を確かめる |
| `forbidden` | 403 | この API キーの用途か、対象のソースでは実行できない。必要な用途と対象の鍵を使う |
| `needs_draft` | 403 | 用途「AI エージェント」の鍵は、文書を直接変えられない。POST /knowledge/drafts で下書きを作る |
| `not_found` | 404 | 指定した ID かパスが無い（ほかの組織の ID も同じ応答になる）。ID と操作の一覧を確かめる |
| `source_locked` | 409 | 同期のソースの文書は、同期（POST /knowledge/sources/{source_id}/sync）からだけ変えられる |
| `limit_exceeded` | 409 | 組織の文書の数か、受け取り待ちのファイルの数が上限に達する。limit を見て減らす |
| `delete_limit_exceeded` | 409 | 同期で消す数が、確認なしで消せる上限を超える。消してよい external_id を confirmed_deletes に入れる |
| `folder_not_found` | 409 | 同期の path のフォルダが leafchat に無い（サイトごとにナレッジを分けている組織）。ダッシュボードでフォルダを作ってから同期する |
| `folder_limit_exceeded` | 409 | 同期で作るフォルダが、組織のフォルダの上限を超える。置き場所のフォルダを減らす |
| `upload_required` | 409 | 実行に要るファイルをまだ受け取っていない。uploads のファイルを PUT /knowledge/sources/{source_id}/uploads/{sha256} で上げてから実行する |
| `upload_not_expected` | 409 | 計画が求めていないファイルか、予約の期限切れか、大きさが計画と違う。同期の計画（dry_run）を呼び直す |
| `sync_in_progress` | 409 | 同じソースで別の同期を実行中。終わってからやり直す |
| `not_sync_source` | 409 | 指定したソースは同期のソースではない。同期のソースの ID を指定する |
| `external_id_taken` | 409 | この external_id は別の内容で使われている。更新は PUT /knowledge/sources/{source_id}/documents/{external_id} を使う |
| `draft_limit_exceeded` | 409 | 未処理の下書きが上限に達している。ダッシュボードで処理してから作る |
| `already_decided` | 409 | この下書きは公開か破棄が済んでいる。GET で状態を確かめる |
| `not_retryable` | 409 | 最新の版は取り込みに失敗していないか、原本が残っていない。GET で状態を確かめ、原本が無ければ文書を作り直す |
| `precondition_failed` | 412 | If-Match（下書きの作成では base_revision_id）の版が今の版と違う。GET で最新の ETag を取り直す |
| `payload_too_large` | 413 | 本文かファイルが上限を超えた。小さくして送る |
| `unsupported_media_type` | 415 | Content-Type が、その操作の受け付ける形式でない |
| `edit_no_match` | 422 | edits の old_text が本文に無い。最新の本文を読み直して指定する |
| `edit_ambiguous` | 422 | edits の old_text が本文に複数ある。前後の文字を含めて 1 か所に絞る |
| `not_editable` | 422 | この形式の文書（PDF など）は edits で直せない。content で本文全体を置き換える |
| `too_many_parts` | 422 | テキストが長すぎて分割の上限を超える。文書を分ける |
| `invalid_item` | 422 | 同期の項目を受け付けられない（external_id・path・名前・形式・大きさ）。reason を見て直す |
| `upload_mismatch` | 422 | 上げたファイルの大きさ・SHA-256・中身が、Content-Length・URL・形式と合わない。reason を見て直す |
| `precondition_required` | 428 | 本文を変える PATCH に If-Match が無い。GET の ETag を If-Match に入れる |
| `rate_limited` | 429 | 上限を超えた。Retry-After の秒数だけ待ってからやり直す |
| `internal_error` | 500 | サーバーで問題が起きた。少し待ってからやり直す |
| `operation_failed` | 502 | 同期の途中で操作が失敗した。cause が取り込めない中身を示すなら直し、それ以外は同じ一式で呼び直すと続きから実行する |
| `storage_failed` | 503 | 保存かキューへの送信に失敗した。Retry-After の秒数だけ待ってからやり直す |
| `search_unavailable` | 503 | ナレッジの検索の準備ができていない。Retry-After の秒数だけ待ってからやり直す |

## 操作の一覧

| operationId | メソッド | パス | 概要 |
| --- | --- | --- | --- |
| [`list_knowledge_sources`](#op-list_knowledge_sources) | GET | `/knowledge/sources` | ソースの一覧 |
| [`get_knowledge_source`](#op-get_knowledge_source) | GET | `/knowledge/sources/{source_id}` | ソースの取得 |
| [`list_knowledge_folders`](#op-list_knowledge_folders) | GET | `/knowledge/folders` | フォルダの一覧 |
| [`list_knowledge_documents`](#op-list_knowledge_documents) | GET | `/knowledge/documents` | 文書の一覧 |
| [`create_knowledge_document`](#op-create_knowledge_document) | POST | `/knowledge/documents` | 文書の作成 |
| [`get_knowledge_document`](#op-get_knowledge_document) | GET | `/knowledge/documents/{document_id}` | 文書の取得 |
| [`update_knowledge_document`](#op-update_knowledge_document) | PATCH | `/knowledge/documents/{document_id}` | 文書の変更 |
| [`delete_knowledge_document`](#op-delete_knowledge_document) | DELETE | `/knowledge/documents/{document_id}` | 文書の削除 |
| [`get_knowledge_document_content`](#op-get_knowledge_document_content) | GET | `/knowledge/documents/{document_id}/content` | 文書の原本 |
| [`list_knowledge_document_revisions`](#op-list_knowledge_document_revisions) | GET | `/knowledge/documents/{document_id}/revisions` | 版の履歴 |
| [`upsert_knowledge_document`](#op-upsert_knowledge_document) | PUT | `/knowledge/sources/{source_id}/documents/{external_id}` | 外部 ID で文書を作成・更新する |
| [`restore_knowledge_document_revision`](#op-restore_knowledge_document_revision) | POST | `/knowledge/documents/{document_id}/revisions/{revision_id}/restore` | 以前の版に戻す |
| [`retry_knowledge_document`](#op-retry_knowledge_document) | POST | `/knowledge/documents/{document_id}/retry` | 取り込みに失敗した最新の版を取り込み直す |
| [`sync_knowledge_source`](#op-sync_knowledge_source) | POST | `/knowledge/sources/{source_id}/sync` | 同期のソースに一式を送る |
| [`upload_knowledge_source_file`](#op-upload_knowledge_source_file) | PUT | `/knowledge/sources/{source_id}/uploads/{sha256}` | 同期のファイルを上げる |
| [`list_knowledge_drafts`](#op-list_knowledge_drafts) | GET | `/knowledge/drafts` | 下書きの一覧 |
| [`create_knowledge_draft`](#op-create_knowledge_draft) | POST | `/knowledge/drafts` | 下書きを作る |
| [`get_knowledge_draft`](#op-get_knowledge_draft) | GET | `/knowledge/drafts/{draft_id}` | 下書きの取得 |
| [`discard_knowledge_draft`](#op-discard_knowledge_draft) | DELETE | `/knowledge/drafts/{draft_id}` | 下書きを破棄する |
| [`get_knowledge_draft_content`](#op-get_knowledge_draft_content) | GET | `/knowledge/drafts/{draft_id}/content` | 下書きの提案の本文 |

## Sources

ナレッジの持ち主の単位

<a id="op-list_knowledge_sources"></a>
### list_knowledge_sources

`GET /knowledge/sources` — ソースの一覧

#### 応答

| 状態 | 説明 | 本文 |
| --- | --- | --- |
| 200 | 組織のソース（既定のソースが先頭） | `application/json`：object |
| 401 | API キーが無いか無効（期限切れ・失効・削除の途中の組織を含み、理由は区別しない）<br><br>返る code：`unauthorized` | `application/problem+json`：[Problem](#schema-Problem) |
| 403 | この API キーの用途か、対象のソースでは実行できない<br><br>返る code：`forbidden`・`needs_draft` | `application/problem+json`：[Problem](#schema-Problem) |
| 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 が無ければ少し待ってからやり直す<br><br>返る code：`rate_limited`。ヘッダー：`Retry-After`（待つ秒数） | `application/problem+json`：[Problem](#schema-Problem) |
| 500 | サーバーで問題が起きた。少し待ってからやり直す<br><br>返る code：`internal_error` | `application/problem+json`：[Problem](#schema-Problem) |

<a id="op-get_knowledge_source"></a>
### get_knowledge_source

`GET /knowledge/sources/{source_id}` — ソースの取得

#### パラメータ

| 名前 | 場所 | 型 | 必須 | 説明 |
| --- | --- | --- | --- | --- |
| `source_id` | パス | string | 必須 | 1〜64 文字 |

#### 応答

| 状態 | 説明 | 本文 |
| --- | --- | --- |
| 200 | ソース | `application/json`：[Source](#schema-Source) |
| 400 | 要求の形式か値が正しくない。errors（検証の誤り）に項目（path）ごとの理由が入る<br><br>返る code：`invalid_request`・`empty_manifest`・`duplicate_item` | `application/problem+json`：[Problem](#schema-Problem) |
| 401 | API キーが無いか無効（期限切れ・失効・削除の途中の組織を含み、理由は区別しない）<br><br>返る code：`unauthorized` | `application/problem+json`：[Problem](#schema-Problem) |
| 403 | この API キーの用途か、対象のソースでは実行できない<br><br>返る code：`forbidden`・`needs_draft` | `application/problem+json`：[Problem](#schema-Problem) |
| 404 | 指定した ID かパスが無い（ほかの組織の ID も同じ応答になる）。削除した文書は、削除の起票が保守の GC で消えるまで DELETE が already_deleted を返し、その後は 404<br><br>返る code：`not_found` | `application/problem+json`：[Problem](#schema-Problem) |
| 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 が無ければ少し待ってからやり直す<br><br>返る code：`rate_limited`。ヘッダー：`Retry-After`（待つ秒数） | `application/problem+json`：[Problem](#schema-Problem) |
| 500 | サーバーで問題が起きた。少し待ってからやり直す<br><br>返る code：`internal_error` | `application/problem+json`：[Problem](#schema-Problem) |

## Folders

サイト別の出し分けの単位

<a id="op-list_knowledge_folders"></a>
### list_knowledge_folders

`GET /knowledge/folders` — フォルダの一覧

既定のフォルダが先頭。is_global のフォルダはすべてのサイトから参照され、それ以外は sites に挙げたサイトだけが参照する

#### 応答

| 状態 | 説明 | 本文 |
| --- | --- | --- |
| 200 | 組織のフォルダ | `application/json`：object |
| 401 | API キーが無いか無効（期限切れ・失効・削除の途中の組織を含み、理由は区別しない）<br><br>返る code：`unauthorized` | `application/problem+json`：[Problem](#schema-Problem) |
| 403 | この API キーの用途か、対象のソースでは実行できない<br><br>返る code：`forbidden`・`needs_draft` | `application/problem+json`：[Problem](#schema-Problem) |
| 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 が無ければ少し待ってからやり直す<br><br>返る code：`rate_limited`。ヘッダー：`Retry-After`（待つ秒数） | `application/problem+json`：[Problem](#schema-Problem) |
| 500 | サーバーで問題が起きた。少し待ってからやり直す<br><br>返る code：`internal_error` | `application/problem+json`：[Problem](#schema-Problem) |

## Documents

文書と版

<a id="op-list_knowledge_documents"></a>
### list_knowledge_documents

`GET /knowledge/documents` — 文書の一覧

作成の新しい順。next_cursor が null でなければ、cursor に入れて次のページを取る

#### パラメータ

| 名前 | 場所 | 型 | 必須 | 説明 |
| --- | --- | --- | --- | --- |
| `source_id` | クエリ | string | 任意 | 1〜64 文字 |
| `folder_id` | クエリ | string | 任意 | 1〜64 文字 |
| `external_id` | クエリ | string | 任意 | source_id と一緒のときだけ指定できる。512 文字まで |
| `status` | クエリ | string | 任意 | 値：`processing`・`pending`・`ready`・`error` |
| `cursor` | クエリ | string | 任意 | 前の応答の next_cursor。512 文字まで |
| `limit` | クエリ | integer | 任意 | 1〜100。既定：`50` |

#### 応答

| 状態 | 説明 | 本文 |
| --- | --- | --- |
| 200 | 文書の 1 ページ | `application/json`：object |
| 400 | 要求の形式か値が正しくない。errors（検証の誤り）に項目（path）ごとの理由が入る<br><br>返る code：`invalid_request`・`empty_manifest`・`duplicate_item` | `application/problem+json`：[Problem](#schema-Problem) |
| 401 | API キーが無いか無効（期限切れ・失効・削除の途中の組織を含み、理由は区別しない）<br><br>返る code：`unauthorized` | `application/problem+json`：[Problem](#schema-Problem) |
| 403 | この API キーの用途か、対象のソースでは実行できない<br><br>返る code：`forbidden`・`needs_draft` | `application/problem+json`：[Problem](#schema-Problem) |
| 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 が無ければ少し待ってからやり直す<br><br>返る code：`rate_limited`。ヘッダー：`Retry-After`（待つ秒数） | `application/problem+json`：[Problem](#schema-Problem) |
| 500 | サーバーで問題が起きた。少し待ってからやり直す<br><br>返る code：`internal_error` | `application/problem+json`：[Problem](#schema-Problem) |

<a id="op-create_knowledge_document"></a>
### create_knowledge_document

`POST /knowledge/documents` — 文書の作成

テキストは JSON（content と content_type）、PDF などのリッチの形式は multipart/form-data（file）で送る。

source_id を省くと既定のソースに入る。同じ external_id で同じ内容をもう一度送ると、作らずに 200 で既存を返す。

本文の上限は JSON 6 MiB・multipart 16 MiB。テキストは分割の上限が先に効き、実際は約 1.5 MiB まで。

#### 要求の本文（任意）

- `application/json`：[CreateDocument](#schema-CreateDocument)

例「text」：テキストの文書を作る

```json
{
  "external_id": "faq/shipping",
  "filename": "送料.md",
  "content": "# 送料\n\n全国一律で無料です。",
  "content_type": "text/markdown"
}
```

- `multipart/form-data`：[CreateDocumentMultipart](#schema-CreateDocumentMultipart)

#### 応答

| 状態 | 説明 | 本文 |
| --- | --- | --- |
| 200 | 同じ外部 ID・同じ内容の文書が既にあった | `application/json`：[DocumentAccepted](#schema-DocumentAccepted) |
| 202 | 受け付けた。反映の状態は Location の文書で確かめる。ヘッダー：`Location`（文書の URL） | `application/json`：[DocumentAccepted](#schema-DocumentAccepted) |
| 400 | 要求の形式か値が正しくない。errors（検証の誤り）に項目（path）ごとの理由が入る<br><br>返る code：`invalid_request`・`empty_manifest`・`duplicate_item` | `application/problem+json`：[Problem](#schema-Problem) |
| 401 | API キーが無いか無効（期限切れ・失効・削除の途中の組織を含み、理由は区別しない）<br><br>返る code：`unauthorized` | `application/problem+json`：[Problem](#schema-Problem) |
| 403 | この API キーの用途か、対象のソースでは実行できない<br><br>返る code：`forbidden`・`needs_draft` | `application/problem+json`：[Problem](#schema-Problem) |
| 404 | 指定した ID かパスが無い（ほかの組織の ID も同じ応答になる）。削除した文書は、削除の起票が保守の GC で消えるまで DELETE が already_deleted を返し、その後は 404<br><br>返る code：`not_found` | `application/problem+json`：[Problem](#schema-Problem) |
| 409 | 今の状態と合わない。code で見分ける<br><br>返る 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`・`external_id_taken`・`draft_limit_exceeded`・`already_decided`・`not_retryable` | `application/problem+json`：[Problem](#schema-Problem) |
| 413 | 本文が上限を超えた（JSON 6 MiB・multipart 16 MiB・同期 8 MiB・同期のアップロード 15 MiB）。テキストの本文が 4 MiB を超えたときは、本文の上限の内側でも 422 invalid_request になる<br><br>返る code：`payload_too_large` | `application/problem+json`：[Problem](#schema-Problem) |
| 415 | Content-Type が、その操作の受け付ける形式でない。文書の作成に application/x-www-form-urlencoded で送ると、415 ではなく 400 になる<br><br>返る code：`unsupported_media_type` | `application/problem+json`：[Problem](#schema-Problem) |
| 422 | 内容を受け付けられない（編集の対象・分割の上限・形式・同期の項目・アップロードの中身など）。code で見分ける<br><br>返る code：`invalid_request`・`edit_no_match`・`edit_ambiguous`・`not_editable`・`too_many_parts`・`invalid_item`・`upload_mismatch` | `application/problem+json`：[Problem](#schema-Problem) |
| 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 が無ければ少し待ってからやり直す<br><br>返る code：`rate_limited`。ヘッダー：`Retry-After`（待つ秒数） | `application/problem+json`：[Problem](#schema-Problem) |
| 500 | サーバーで問題が起きた。少し待ってからやり直す<br><br>返る code：`internal_error` | `application/problem+json`：[Problem](#schema-Problem) |
| 503 | 保存かキューへの送信に失敗した（storage_failed）。Retry-After の秒数だけ待ってからやり直す。search_unavailable は今の操作からは返らない（変換の口と MCP のために目録に残している）<br><br>返る code：`storage_failed`・`search_unavailable`。ヘッダー：`Retry-After`（待つ秒数） | `application/problem+json`：[Problem](#schema-Problem) |

<a id="op-get_knowledge_document"></a>
### get_knowledge_document

`GET /knowledge/documents/{document_id}` — 文書の取得

反映の状態は current_revision（公開中の版）と head_revision（最新の版）で確かめる。書き込みの応答の revision_id が current_revision.id になれば公開されている

#### パラメータ

| 名前 | 場所 | 型 | 必須 | 説明 |
| --- | --- | --- | --- | --- |
| `document_id` | パス | string | 必須 | 1〜64 文字 |

#### 応答

| 状態 | 説明 | 本文 |
| --- | --- | --- |
| 200 | 文書。ヘッダー：`ETag`（"<版の ID>"。If-Match にそのまま入れる） | `application/json`：[Document](#schema-Document) |
| 400 | 要求の形式か値が正しくない。errors（検証の誤り）に項目（path）ごとの理由が入る<br><br>返る code：`invalid_request`・`empty_manifest`・`duplicate_item` | `application/problem+json`：[Problem](#schema-Problem) |
| 401 | API キーが無いか無効（期限切れ・失効・削除の途中の組織を含み、理由は区別しない）<br><br>返る code：`unauthorized` | `application/problem+json`：[Problem](#schema-Problem) |
| 403 | この API キーの用途か、対象のソースでは実行できない<br><br>返る code：`forbidden`・`needs_draft` | `application/problem+json`：[Problem](#schema-Problem) |
| 404 | 指定した ID かパスが無い（ほかの組織の ID も同じ応答になる）。削除した文書は、削除の起票が保守の GC で消えるまで DELETE が already_deleted を返し、その後は 404<br><br>返る code：`not_found` | `application/problem+json`：[Problem](#schema-Problem) |
| 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 が無ければ少し待ってからやり直す<br><br>返る code：`rate_limited`。ヘッダー：`Retry-After`（待つ秒数） | `application/problem+json`：[Problem](#schema-Problem) |
| 500 | サーバーで問題が起きた。少し待ってからやり直す<br><br>返る code：`internal_error` | `application/problem+json`：[Problem](#schema-Problem) |

<a id="op-update_knowledge_document"></a>
### update_knowledge_document

`PATCH /knowledge/documents/{document_id}` — 文書の変更

次の 3 つの組のうち 1 つだけを送る。組を混ぜると 400。

- 本文：content と content_type、または edits（どちらか一方）。filename は任意。If-Match が必須（無ければ 428）

- フォルダ：folder_id

- ソース：source_id（同期のソースへ移すときは external_id も）

#### パラメータ

| 名前 | 場所 | 型 | 必須 | 説明 |
| --- | --- | --- | --- | --- |
| `document_id` | パス | string | 必須 | 1〜64 文字 |
| `if-match` | ヘッダー | string | 任意 | GET で受け取った ETag（"<版の ID>"）。強い比較の 1 つの値だけを受ける |

#### 要求の本文（必須）

- `application/json`：[PatchDocument](#schema-PatchDocument)

#### 応答

| 状態 | 説明 | 本文 |
| --- | --- | --- |
| 200 | フォルダ・ソースを変えた（文書を返す）。本文が同じで版を作らなかったときは DocumentAccepted（created: false） | `application/json`：[Document](#schema-Document) または [DocumentAccepted](#schema-DocumentAccepted) |
| 202 | 本文の変更を受け付けた | `application/json`：[DocumentAccepted](#schema-DocumentAccepted) |
| 400 | 要求の形式か値が正しくない。errors（検証の誤り）に項目（path）ごとの理由が入る<br><br>返る code：`invalid_request`・`empty_manifest`・`duplicate_item` | `application/problem+json`：[Problem](#schema-Problem) |
| 401 | API キーが無いか無効（期限切れ・失効・削除の途中の組織を含み、理由は区別しない）<br><br>返る code：`unauthorized` | `application/problem+json`：[Problem](#schema-Problem) |
| 403 | この API キーの用途か、対象のソースでは実行できない<br><br>返る code：`forbidden`・`needs_draft` | `application/problem+json`：[Problem](#schema-Problem) |
| 404 | 指定した ID かパスが無い（ほかの組織の ID も同じ応答になる）。削除した文書は、削除の起票が保守の GC で消えるまで DELETE が already_deleted を返し、その後は 404<br><br>返る code：`not_found` | `application/problem+json`：[Problem](#schema-Problem) |
| 409 | 今の状態と合わない。code で見分ける<br><br>返る 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`・`external_id_taken`・`draft_limit_exceeded`・`already_decided`・`not_retryable` | `application/problem+json`：[Problem](#schema-Problem) |
| 412 | If-Match（下書きの作成では base_revision_id）の版が、今の head の版と違う。存在しない文書へ If-Match を付けた upsert でも返る<br><br>返る code：`precondition_failed` | `application/problem+json`：[Problem](#schema-Problem) |
| 413 | 本文が上限を超えた（JSON 6 MiB・multipart 16 MiB・同期 8 MiB・同期のアップロード 15 MiB）。テキストの本文が 4 MiB を超えたときは、本文の上限の内側でも 422 invalid_request になる<br><br>返る code：`payload_too_large` | `application/problem+json`：[Problem](#schema-Problem) |
| 415 | Content-Type が、その操作の受け付ける形式でない。文書の作成に application/x-www-form-urlencoded で送ると、415 ではなく 400 になる<br><br>返る code：`unsupported_media_type` | `application/problem+json`：[Problem](#schema-Problem) |
| 422 | 内容を受け付けられない（編集の対象・分割の上限・形式・同期の項目・アップロードの中身など）。code で見分ける<br><br>返る code：`invalid_request`・`edit_no_match`・`edit_ambiguous`・`not_editable`・`too_many_parts`・`invalid_item`・`upload_mismatch` | `application/problem+json`：[Problem](#schema-Problem) |
| 428 | 本文を変える PATCH に If-Match が無い<br><br>返る code：`precondition_required` | `application/problem+json`：[Problem](#schema-Problem) |
| 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 が無ければ少し待ってからやり直す<br><br>返る code：`rate_limited`。ヘッダー：`Retry-After`（待つ秒数） | `application/problem+json`：[Problem](#schema-Problem) |
| 500 | サーバーで問題が起きた。少し待ってからやり直す<br><br>返る code：`internal_error` | `application/problem+json`：[Problem](#schema-Problem) |
| 503 | 保存かキューへの送信に失敗した（storage_failed）。Retry-After の秒数だけ待ってからやり直す。search_unavailable は今の操作からは返らない（変換の口と MCP のために目録に残している）<br><br>返る code：`storage_failed`・`search_unavailable`。ヘッダー：`Retry-After`（待つ秒数） | `application/problem+json`：[Problem](#schema-Problem) |

<a id="op-delete_knowledge_document"></a>
### delete_knowledge_document

`DELETE /knowledge/documents/{document_id}` — 文書の削除

削除を受け付け、実体は裏で消す。消した文書をもう一度消すと、削除の起票が保守の GC で消えるまでは already_deleted、その後は 404

#### パラメータ

| 名前 | 場所 | 型 | 必須 | 説明 |
| --- | --- | --- | --- | --- |
| `document_id` | パス | string | 必須 | 1〜64 文字 |
| `if-match` | ヘッダー | string | 任意 | GET で受け取った ETag（"<版の ID>"）。強い比較の 1 つの値だけを受ける |

#### 応答

| 状態 | 説明 | 本文 |
| --- | --- | --- |
| 202 | 削除を受け付けた | `application/json`：[DeleteResult](#schema-DeleteResult) |
| 400 | 要求の形式か値が正しくない。errors（検証の誤り）に項目（path）ごとの理由が入る<br><br>返る code：`invalid_request`・`empty_manifest`・`duplicate_item` | `application/problem+json`：[Problem](#schema-Problem) |
| 401 | API キーが無いか無効（期限切れ・失効・削除の途中の組織を含み、理由は区別しない）<br><br>返る code：`unauthorized` | `application/problem+json`：[Problem](#schema-Problem) |
| 403 | この API キーの用途か、対象のソースでは実行できない<br><br>返る code：`forbidden`・`needs_draft` | `application/problem+json`：[Problem](#schema-Problem) |
| 404 | 指定した ID かパスが無い（ほかの組織の ID も同じ応答になる）。削除した文書は、削除の起票が保守の GC で消えるまで DELETE が already_deleted を返し、その後は 404<br><br>返る code：`not_found` | `application/problem+json`：[Problem](#schema-Problem) |
| 409 | 今の状態と合わない。code で見分ける<br><br>返る 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`・`external_id_taken`・`draft_limit_exceeded`・`already_decided`・`not_retryable` | `application/problem+json`：[Problem](#schema-Problem) |
| 412 | If-Match（下書きの作成では base_revision_id）の版が、今の head の版と違う。存在しない文書へ If-Match を付けた upsert でも返る<br><br>返る code：`precondition_failed` | `application/problem+json`：[Problem](#schema-Problem) |
| 422 | 内容を受け付けられない（編集の対象・分割の上限・形式・同期の項目・アップロードの中身など）。code で見分ける<br><br>返る code：`invalid_request`・`edit_no_match`・`edit_ambiguous`・`not_editable`・`too_many_parts`・`invalid_item`・`upload_mismatch` | `application/problem+json`：[Problem](#schema-Problem) |
| 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 が無ければ少し待ってからやり直す<br><br>返る code：`rate_limited`。ヘッダー：`Retry-After`（待つ秒数） | `application/problem+json`：[Problem](#schema-Problem) |
| 500 | サーバーで問題が起きた。少し待ってからやり直す<br><br>返る code：`internal_error` | `application/problem+json`：[Problem](#schema-Problem) |

<a id="op-get_knowledge_document_content"></a>
### get_knowledge_document_content

`GET /knowledge/documents/{document_id}/content` — 文書の原本

revision_id が無ければ公開中の版の原本を返す。公開中の版がまだ無い文書は 404（revision_id で版を指定する）

#### パラメータ

| 名前 | 場所 | 型 | 必須 | 説明 |
| --- | --- | --- | --- | --- |
| `document_id` | パス | string | 必須 | 1〜64 文字 |
| `revision_id` | クエリ | string | 任意 | 無ければ公開中の版。1〜64 文字 |

#### 応答

| 状態 | 説明 | 本文 |
| --- | --- | --- |
| 200 | 原本のバイト列（Content-Disposition: attachment）。ヘッダー：`ETag`（"<版の ID>"。If-Match にそのまま入れる） | `application/octet-stream`：string（binary） |
| 400 | 要求の形式か値が正しくない。errors（検証の誤り）に項目（path）ごとの理由が入る<br><br>返る code：`invalid_request`・`empty_manifest`・`duplicate_item` | `application/problem+json`：[Problem](#schema-Problem) |
| 401 | API キーが無いか無効（期限切れ・失効・削除の途中の組織を含み、理由は区別しない）<br><br>返る code：`unauthorized` | `application/problem+json`：[Problem](#schema-Problem) |
| 403 | この API キーの用途か、対象のソースでは実行できない<br><br>返る code：`forbidden`・`needs_draft` | `application/problem+json`：[Problem](#schema-Problem) |
| 404 | 指定した ID かパスが無い（ほかの組織の ID も同じ応答になる）。削除した文書は、削除の起票が保守の GC で消えるまで DELETE が already_deleted を返し、その後は 404<br><br>返る code：`not_found` | `application/problem+json`：[Problem](#schema-Problem) |
| 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 が無ければ少し待ってからやり直す<br><br>返る code：`rate_limited`。ヘッダー：`Retry-After`（待つ秒数） | `application/problem+json`：[Problem](#schema-Problem) |
| 500 | サーバーで問題が起きた。少し待ってからやり直す<br><br>返る code：`internal_error` | `application/problem+json`：[Problem](#schema-Problem) |

<a id="op-list_knowledge_document_revisions"></a>
### list_knowledge_document_revisions

`GET /knowledge/documents/{document_id}/revisions` — 版の履歴

新しい順。以前の版は 20 版まで原本が残り、復元できる

#### パラメータ

| 名前 | 場所 | 型 | 必須 | 説明 |
| --- | --- | --- | --- | --- |
| `document_id` | パス | string | 必須 | 1〜64 文字 |

#### 応答

| 状態 | 説明 | 本文 |
| --- | --- | --- |
| 200 | 版の一覧 | `application/json`：object |
| 400 | 要求の形式か値が正しくない。errors（検証の誤り）に項目（path）ごとの理由が入る<br><br>返る code：`invalid_request`・`empty_manifest`・`duplicate_item` | `application/problem+json`：[Problem](#schema-Problem) |
| 401 | API キーが無いか無効（期限切れ・失効・削除の途中の組織を含み、理由は区別しない）<br><br>返る code：`unauthorized` | `application/problem+json`：[Problem](#schema-Problem) |
| 403 | この API キーの用途か、対象のソースでは実行できない<br><br>返る code：`forbidden`・`needs_draft` | `application/problem+json`：[Problem](#schema-Problem) |
| 404 | 指定した ID かパスが無い（ほかの組織の ID も同じ応答になる）。削除した文書は、削除の起票が保守の GC で消えるまで DELETE が already_deleted を返し、その後は 404<br><br>返る code：`not_found` | `application/problem+json`：[Problem](#schema-Problem) |
| 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 が無ければ少し待ってからやり直す<br><br>返る code：`rate_limited`。ヘッダー：`Retry-After`（待つ秒数） | `application/problem+json`：[Problem](#schema-Problem) |
| 500 | サーバーで問題が起きた。少し待ってからやり直す<br><br>返る code：`internal_error` | `application/problem+json`：[Problem](#schema-Problem) |

<a id="op-upsert_knowledge_document"></a>
### upsert_knowledge_document

`PUT /knowledge/sources/{source_id}/documents/{external_id}` — 外部 ID で文書を作成・更新する

external_id は encodeURIComponent で符号化してパスに入れる（faq/shipping は faq%2Fshipping）。If-Match は任意で、指定すると head の版が違えば 412 になる

#### パラメータ

| 名前 | 場所 | 型 | 必須 | 説明 |
| --- | --- | --- | --- | --- |
| `source_id` | パス | string | 必須 | 1〜64 文字 |
| `external_id` | パス | string | 必須 | encodeURIComponent で符号化して送る（faq/shipping は faq%2Fshipping）。サーバーは復号した値を検査する。512 文字まで |
| `if-match` | ヘッダー | string | 任意 | GET で受け取った ETag（"<版の ID>"）。強い比較の 1 つの値だけを受ける |

#### 要求の本文（必須）

- `application/json`：[UpsertDocument](#schema-UpsertDocument)

#### 応答

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

<a id="op-restore_knowledge_document_revision"></a>
### restore_knowledge_document_revision

`POST /knowledge/documents/{document_id}/revisions/{revision_id}/restore` — 以前の版に戻す

指定した版の内容で新しい版を作る。If-Match は任意

#### パラメータ

| 名前 | 場所 | 型 | 必須 | 説明 |
| --- | --- | --- | --- | --- |
| `document_id` | パス | string | 必須 | 1〜64 文字 |
| `revision_id` | パス | string | 必須 | 1〜64 文字 |
| `if-match` | ヘッダー | string | 任意 | GET で受け取った ETag（"<版の ID>"）。強い比較の 1 つの値だけを受ける |

#### 応答

| 状態 | 説明 | 本文 |
| --- | --- | --- |
| 200 | 今の版と同じ内容で、版を作らなかった | `application/json`：[DocumentAccepted](#schema-DocumentAccepted) |
| 202 | 新しい版を受け付けた | `application/json`：[DocumentAccepted](#schema-DocumentAccepted) |
| 400 | 要求の形式か値が正しくない。errors（検証の誤り）に項目（path）ごとの理由が入る<br><br>返る code：`invalid_request`・`empty_manifest`・`duplicate_item` | `application/problem+json`：[Problem](#schema-Problem) |
| 401 | API キーが無いか無効（期限切れ・失効・削除の途中の組織を含み、理由は区別しない）<br><br>返る code：`unauthorized` | `application/problem+json`：[Problem](#schema-Problem) |
| 403 | この API キーの用途か、対象のソースでは実行できない<br><br>返る code：`forbidden`・`needs_draft` | `application/problem+json`：[Problem](#schema-Problem) |
| 404 | 指定した ID かパスが無い（ほかの組織の ID も同じ応答になる）。削除した文書は、削除の起票が保守の GC で消えるまで DELETE が already_deleted を返し、その後は 404<br><br>返る code：`not_found` | `application/problem+json`：[Problem](#schema-Problem) |
| 409 | 今の状態と合わない。code で見分ける<br><br>返る 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`・`external_id_taken`・`draft_limit_exceeded`・`already_decided`・`not_retryable` | `application/problem+json`：[Problem](#schema-Problem) |
| 412 | If-Match（下書きの作成では base_revision_id）の版が、今の head の版と違う。存在しない文書へ If-Match を付けた upsert でも返る<br><br>返る code：`precondition_failed` | `application/problem+json`：[Problem](#schema-Problem) |
| 422 | 内容を受け付けられない（編集の対象・分割の上限・形式・同期の項目・アップロードの中身など）。code で見分ける<br><br>返る code：`invalid_request`・`edit_no_match`・`edit_ambiguous`・`not_editable`・`too_many_parts`・`invalid_item`・`upload_mismatch` | `application/problem+json`：[Problem](#schema-Problem) |
| 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 が無ければ少し待ってからやり直す<br><br>返る code：`rate_limited`。ヘッダー：`Retry-After`（待つ秒数） | `application/problem+json`：[Problem](#schema-Problem) |
| 500 | サーバーで問題が起きた。少し待ってからやり直す<br><br>返る code：`internal_error` | `application/problem+json`：[Problem](#schema-Problem) |
| 503 | 保存かキューへの送信に失敗した（storage_failed）。Retry-After の秒数だけ待ってからやり直す。search_unavailable は今の操作からは返らない（変換の口と MCP のために目録に残している）<br><br>返る code：`storage_failed`・`search_unavailable`。ヘッダー：`Retry-After`（待つ秒数） | `application/problem+json`：[Problem](#schema-Problem) |

<a id="op-retry_knowledge_document"></a>
### retry_knowledge_document

`POST /knowledge/documents/{document_id}/retry` — 取り込みに失敗した最新の版を取り込み直す

#### パラメータ

| 名前 | 場所 | 型 | 必須 | 説明 |
| --- | --- | --- | --- | --- |
| `document_id` | パス | string | 必須 | 1〜64 文字 |

#### 応答

| 状態 | 説明 | 本文 |
| --- | --- | --- |
| 202 | 取り込み直しを受け付けた | `application/json`：[RetryResult](#schema-RetryResult) |
| 400 | 要求の形式か値が正しくない。errors（検証の誤り）に項目（path）ごとの理由が入る<br><br>返る code：`invalid_request`・`empty_manifest`・`duplicate_item` | `application/problem+json`：[Problem](#schema-Problem) |
| 401 | API キーが無いか無効（期限切れ・失効・削除の途中の組織を含み、理由は区別しない）<br><br>返る code：`unauthorized` | `application/problem+json`：[Problem](#schema-Problem) |
| 403 | この API キーの用途か、対象のソースでは実行できない<br><br>返る code：`forbidden`・`needs_draft` | `application/problem+json`：[Problem](#schema-Problem) |
| 404 | 指定した ID かパスが無い（ほかの組織の ID も同じ応答になる）。削除した文書は、削除の起票が保守の GC で消えるまで DELETE が already_deleted を返し、その後は 404<br><br>返る code：`not_found` | `application/problem+json`：[Problem](#schema-Problem) |
| 409 | 今の状態と合わない。code で見分ける<br><br>返る 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`・`external_id_taken`・`draft_limit_exceeded`・`already_decided`・`not_retryable` | `application/problem+json`：[Problem](#schema-Problem) |
| 422 | 内容を受け付けられない（編集の対象・分割の上限・形式・同期の項目・アップロードの中身など）。code で見分ける<br><br>返る code：`invalid_request`・`edit_no_match`・`edit_ambiguous`・`not_editable`・`too_many_parts`・`invalid_item`・`upload_mismatch` | `application/problem+json`：[Problem](#schema-Problem) |
| 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 が無ければ少し待ってからやり直す<br><br>返る code：`rate_limited`。ヘッダー：`Retry-After`（待つ秒数） | `application/problem+json`：[Problem](#schema-Problem) |
| 500 | サーバーで問題が起きた。少し待ってからやり直す<br><br>返る code：`internal_error` | `application/problem+json`：[Problem](#schema-Problem) |
| 503 | 保存かキューへの送信に失敗した（storage_failed）。Retry-After の秒数だけ待ってからやり直す。search_unavailable は今の操作からは返らない（変換の口と MCP のために目録に残している）<br><br>返る code：`storage_failed`・`search_unavailable`。ヘッダー：`Retry-After`（待つ秒数） | `application/problem+json`：[Problem](#schema-Problem) |

## Sync

同期のソースに、置き場所の一式を送ってそろえる。files で送ると、パスの最初の階層がフォルダ、最後がファイル名になる（2 階層まで）。テキスト（md・txt・json）は本文ごと、それ以外（html・csv・pdf・docx）は一覧（SHA-256・大きさ・形式）だけを送り、計画の uploads_required に出たファイルを PUT …/uploads/{sha256} で上げてから実行する。中身が同じで名前やフォルダだけが変わったファイルは、同じ文書の名前の変更・移動として扱う。remaining が 0 になるまで同じ一式で呼び直す。公式の CLI と GitHub Action：<https://github.com/leafchat/cli>

<a id="op-sync_knowledge_source"></a>
### sync_knowledge_source

`POST /knowledge/sources/{source_id}/sync` — 同期のソースに一式を送る

送った一式と、ソースの今の文書を external_id で突き合わせ、作成・更新・名前の変更・移動・削除を計画して実行する。一式は items か files のどちらか一方で送る。

files の項目は、テキスト（md・txt・json）なら本文（content）ごと、それ以外（html・csv・pdf・docx。テキストも可）は参照（sha256・size・content_type）で送る。参照の項目は計画の uploads_required に出たファイルを PUT …/uploads/{sha256} で上げてから実行する。足りないまま実行すると 409 upload_required になる。参照の項目の作成・更新は 1 回の実行で 10 件まで（残りは remaining）。

files で送ると、パスの最初の階層をフォルダ、最後をファイル名として扱う（2 階層まで）。leafchat に無いフォルダは、サイトごとにナレッジを分けていない組織なら実行のときに作り、分けている組織では 409 folder_not_found で止める。client には送り手の名前・版・CI・実行の URL を入れる。ダッシュボードのソースの画面に出る。

files で送ると、消える文書と現れる文書の中身の SHA-256 が一致し、組が 1 つに決まるものは、削除と作成ではなく名前の変更（rename）として扱う。文書 ID と版の履歴が続く。名前と中身を同時に変えると削除と作成になる。

dry_run が true なら計画だけを返し、文書を書かない（読み取りの用途の鍵でも使える）。用途「同期の確認」の鍵は、対象のソースの dry-run だけができる（PR の確認に使う）。warnings には、止めずに知らせる注意（別のフォルダの同じファイル名・Markdown の節の途中の切れ目）が入る。

実行は 1 回で最大 100 操作・25 秒前後（時間を使い切ると、新しい操作を始めずに残りを remaining に返す）。remaining が 0 になるまで同じ一式で呼び直す。最終同期のまとめ（ダッシュボードのソースの一覧）は、呼び出しをまたいだ同期の全体を数える。

一式に無い文書の削除は、確認なしで消せる数を超えると 409 delete_limit_exceeded になる。消してよい external_id を confirmed_deletes に入れる。

実行は API キーごとに 1 分 10 回まで（dry-run は数えない）。本文は 8 MiB まで。

変更点（files を足したとき）：external_id の規則を、日本語のパスを入れられる形（UTF-8 で 512 バイトまで・NFC・`/` 区切り）へ広げた。items の external_id と confirmed_deletes も同じ規則で受け、今まで通っていた ID はすべてそのまま通る。応答の folder_id・to_folder_id は、files で作るフォルダのときだけ null になる（items では常に文字列）。plan.rename と executed[].kind の rename は files で送ったときだけ出る（items では plan.rename は常に空）。ソースの last_sync_summary に renamed を足した。warnings の要素は code で形が分かれる（same_filename_across_folders・chunk_boundary）。

#### パラメータ

| 名前 | 場所 | 型 | 必須 | 説明 |
| --- | --- | --- | --- | --- |
| `source_id` | パス | string | 必須 | 1〜64 文字 |

#### 要求の本文（必須）

- `application/json`：[SyncRequest](#schema-SyncRequest)

例「files」：files で送る（パスの最初の階層がフォルダ、最後がファイル名になる）

```json
{
  "files": [
    {
      "path": "渋谷店/営業時間.md",
      "content": "# 営業時間\n\n毎日 10 時から 20 時まで営業しています。",
      "content_type": "text/markdown"
    },
    {
      "path": "共通/料金表.pdf",
      "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
      "size": 182044,
      "content_type": "application/pdf"
    }
  ],
  "dry_run": true,
  "client": {
    "name": "leafchat-cli",
    "version": "1.0.0",
    "ci": "github_actions",
    "repository": "example/knowledge",
    "run_url": "https://github.com/example/knowledge/actions/runs/1"
  }
}
```

例「items」：items で送る（フォルダを ID で指定する、前からの形）

```json
{
  "items": [
    {
      "external_id": "faq/shipping",
      "filename": "送料.md",
      "content": "# 送料\n\n全国一律で無料です。",
      "content_type": "text/markdown"
    }
  ],
  "dry_run": false
}
```

#### 応答

| 状態 | 説明 | 本文 |
| --- | --- | --- |
| 200 | 計画と、実行した操作 | `application/json`：[SyncResponse](#schema-SyncResponse) |
| 400 | 要求の形式か値が正しくない。errors（検証の誤り）に項目（path）ごとの理由が入る<br><br>返る code：`invalid_request`・`empty_manifest`・`duplicate_item` | `application/problem+json`：[Problem](#schema-Problem) |
| 401 | API キーが無いか無効（期限切れ・失効・削除の途中の組織を含み、理由は区別しない）<br><br>返る code：`unauthorized` | `application/problem+json`：[Problem](#schema-Problem) |
| 403 | この API キーの用途か、対象のソースでは実行できない<br><br>返る code：`forbidden`・`needs_draft` | `application/problem+json`：[Problem](#schema-Problem) |
| 404 | 指定した ID かパスが無い（ほかの組織の ID も同じ応答になる）。削除した文書は、削除の起票が保守の GC で消えるまで DELETE が already_deleted を返し、その後は 404<br><br>返る code：`not_found` | `application/problem+json`：[Problem](#schema-Problem) |
| 409 | 今の状態と合わない。code で見分ける<br><br>返る 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`・`external_id_taken`・`draft_limit_exceeded`・`already_decided`・`not_retryable` | `application/problem+json`：[Problem](#schema-Problem) |
| 413 | 本文が上限を超えた（JSON 6 MiB・multipart 16 MiB・同期 8 MiB・同期のアップロード 15 MiB）。テキストの本文が 4 MiB を超えたときは、本文の上限の内側でも 422 invalid_request になる<br><br>返る code：`payload_too_large` | `application/problem+json`：[Problem](#schema-Problem) |
| 415 | Content-Type が、その操作の受け付ける形式でない。文書の作成に application/x-www-form-urlencoded で送ると、415 ではなく 400 になる<br><br>返る code：`unsupported_media_type` | `application/problem+json`：[Problem](#schema-Problem) |
| 422 | 内容を受け付けられない（編集の対象・分割の上限・形式・同期の項目・アップロードの中身など）。code で見分ける<br><br>返る code：`invalid_request`・`edit_no_match`・`edit_ambiguous`・`not_editable`・`too_many_parts`・`invalid_item`・`upload_mismatch` | `application/problem+json`：[Problem](#schema-Problem) |
| 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 が無ければ少し待ってからやり直す<br><br>返る code：`rate_limited`。ヘッダー：`Retry-After`（待つ秒数） | `application/problem+json`：[Problem](#schema-Problem) |
| 500 | サーバーで問題が起きた。少し待ってからやり直す<br><br>返る code：`internal_error` | `application/problem+json`：[Problem](#schema-Problem) |
| 502 | 同期の途中で操作が失敗した。同じ一式で呼び直すと、済んだ操作を除いて続きから実行する<br><br>返る code：`operation_failed` | `application/problem+json`：[Problem](#schema-Problem) |

<a id="op-upload_knowledge_source_file"></a>
### upload_knowledge_source_file

`PUT /knowledge/sources/{source_id}/uploads/{sha256}` — 同期のファイルを上げる

同期の計画（POST …/sync）が uploads_required で求めたファイルを 1 件ずつ上げる。計画が求めていないファイルは受けない。

本文はファイルのバイト列そのまま。Content-Type に形式、Content-Length に大きさを付ける。中身の SHA-256 が URL と違えば 422 upload_mismatch。

同じファイルを 2 度上げると、2 度目は 200 で何もしない。受け取ったファイルは 24 時間で消える（その間に実行の同期を呼ぶ）。

#### パラメータ

| 名前 | 場所 | 型 | 必須 | 説明 |
| --- | --- | --- | --- | --- |
| `source_id` | パス | string | 必須 | 1〜64 文字 |
| `sha256` | パス | string | 必須 | ファイルの中身の SHA-256（16 進の小文字）。形式：`^[0-9a-f]{64}$` |

#### 要求の本文（必須）

- `text/plain`：string（binary）

- `text/markdown`：string（binary）

- `application/json`：string（binary）

- `text/html`：string（binary）

- `text/csv`：string（binary）

- `application/pdf`：string（binary）

- `application/vnd.openxmlformats-officedocument.wordprocessingml.document`：string（binary）

#### 応答

| 状態 | 説明 | 本文 |
| --- | --- | --- |
| 200 | 受け取り済み（何もしない） | `application/json`：[UploadAccepted](#schema-UploadAccepted) |
| 201 | 受け取った | `application/json`：[UploadAccepted](#schema-UploadAccepted) |
| 400 | 要求の形式か値が正しくない。errors（検証の誤り）に項目（path）ごとの理由が入る<br><br>返る code：`invalid_request`・`empty_manifest`・`duplicate_item` | `application/problem+json`：[Problem](#schema-Problem) |
| 401 | API キーが無いか無効（期限切れ・失効・削除の途中の組織を含み、理由は区別しない）<br><br>返る code：`unauthorized` | `application/problem+json`：[Problem](#schema-Problem) |
| 403 | この API キーの用途か、対象のソースでは実行できない<br><br>返る code：`forbidden`・`needs_draft` | `application/problem+json`：[Problem](#schema-Problem) |
| 404 | 指定した ID かパスが無い（ほかの組織の ID も同じ応答になる）。削除した文書は、削除の起票が保守の GC で消えるまで DELETE が already_deleted を返し、その後は 404<br><br>返る code：`not_found` | `application/problem+json`：[Problem](#schema-Problem) |
| 409 | 今の状態と合わない。code で見分ける<br><br>返る 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`・`external_id_taken`・`draft_limit_exceeded`・`already_decided`・`not_retryable` | `application/problem+json`：[Problem](#schema-Problem) |
| 411 | Content-Length が無い<br><br>返る code：`invalid_request` | `application/problem+json`：[Problem](#schema-Problem) |
| 413 | 本文が上限を超えた（JSON 6 MiB・multipart 16 MiB・同期 8 MiB・同期のアップロード 15 MiB）。テキストの本文が 4 MiB を超えたときは、本文の上限の内側でも 422 invalid_request になる<br><br>返る code：`payload_too_large` | `application/problem+json`：[Problem](#schema-Problem) |
| 415 | Content-Type が、その操作の受け付ける形式でない。文書の作成に application/x-www-form-urlencoded で送ると、415 ではなく 400 になる<br><br>返る code：`unsupported_media_type` | `application/problem+json`：[Problem](#schema-Problem) |
| 422 | 内容を受け付けられない（編集の対象・分割の上限・形式・同期の項目・アップロードの中身など）。code で見分ける<br><br>返る code：`invalid_request`・`edit_no_match`・`edit_ambiguous`・`not_editable`・`too_many_parts`・`invalid_item`・`upload_mismatch` | `application/problem+json`：[Problem](#schema-Problem) |
| 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 が無ければ少し待ってからやり直す<br><br>返る code：`rate_limited`。ヘッダー：`Retry-After`（待つ秒数） | `application/problem+json`：[Problem](#schema-Problem) |
| 500 | サーバーで問題が起きた。少し待ってからやり直す<br><br>返る code：`internal_error` | `application/problem+json`：[Problem](#schema-Problem) |

## Drafts

ナレッジの変更の提案。人がダッシュボードで差分を見て公開・破棄する（API からは公開できない）

<a id="op-list_knowledge_drafts"></a>
### list_knowledge_drafts

`GET /knowledge/drafts` — 下書きの一覧

作成の新しい順。state の既定は open（未処理）。next_cursor が null でなければ、cursor に入れて次のページを取る

#### パラメータ

| 名前 | 場所 | 型 | 必須 | 説明 |
| --- | --- | --- | --- | --- |
| `state` | クエリ | string | 任意 | 値：`open`・`published`・`discarded`。既定：`open` |
| `target_document_id` | クエリ | string | 任意 | 1〜64 文字 |
| `cursor` | クエリ | string | 任意 | 前の応答の next_cursor。512 文字まで |
| `limit` | クエリ | integer | 任意 | 1〜100。既定：`50` |

#### 応答

| 状態 | 説明 | 本文 |
| --- | --- | --- |
| 200 | 下書きの 1 ページ | `application/json`：object |
| 400 | 要求の形式か値が正しくない。errors（検証の誤り）に項目（path）ごとの理由が入る<br><br>返る code：`invalid_request`・`empty_manifest`・`duplicate_item` | `application/problem+json`：[Problem](#schema-Problem) |
| 401 | API キーが無いか無効（期限切れ・失効・削除の途中の組織を含み、理由は区別しない）<br><br>返る code：`unauthorized` | `application/problem+json`：[Problem](#schema-Problem) |
| 403 | この API キーの用途か、対象のソースでは実行できない<br><br>返る code：`forbidden`・`needs_draft` | `application/problem+json`：[Problem](#schema-Problem) |
| 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 が無ければ少し待ってからやり直す<br><br>返る code：`rate_limited`。ヘッダー：`Retry-After`（待つ秒数） | `application/problem+json`：[Problem](#schema-Problem) |
| 500 | サーバーで問題が起きた。少し待ってからやり直す<br><br>返る code：`internal_error` | `application/problem+json`：[Problem](#schema-Problem) |

<a id="op-create_knowledge_draft"></a>
### create_knowledge_draft

`POST /knowledge/drafts` — 下書きを作る

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 まで。

#### 要求の本文（必須）

- `application/json`：[CreateDraft](#schema-CreateDraft)

例「update_with_edits」：既存の文書の一部を直す提案

```json
{
  "operation": "update",
  "document_id": "p3l8n1b6v9c2x5z7m0q4w8e1",
  "base_revision_id": "r7t2y5u8i1o4p6a9s3d0f2g5",
  "edits": [
    {
      "old_text": "全国一律で無料です。",
      "new_text": "全国一律で 500 円です。5,000 円以上のご注文で無料になります。"
    }
  ],
  "summary": "送料が有料になったことに合わせて、送料の説明を直す",
  "rationale": "担当者が会話で、10 月から送料が 500 円になったと案内している",
  "evidence": {
    "conversation_ids": [
      "c5v8b1n4m7q0w3e6r9t2y5u8"
    ]
  }
}
```

#### 応答

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

<a id="op-get_knowledge_draft"></a>
### get_knowledge_draft

`GET /knowledge/drafts/{draft_id}` — 下書きの取得

#### パラメータ

| 名前 | 場所 | 型 | 必須 | 説明 |
| --- | --- | --- | --- | --- |
| `draft_id` | パス | string | 必須 | 1〜64 文字 |

#### 応答

| 状態 | 説明 | 本文 |
| --- | --- | --- |
| 200 | 下書き | `application/json`：[Draft](#schema-Draft) |
| 400 | 要求の形式か値が正しくない。errors（検証の誤り）に項目（path）ごとの理由が入る<br><br>返る code：`invalid_request`・`empty_manifest`・`duplicate_item` | `application/problem+json`：[Problem](#schema-Problem) |
| 401 | API キーが無いか無効（期限切れ・失効・削除の途中の組織を含み、理由は区別しない）<br><br>返る code：`unauthorized` | `application/problem+json`：[Problem](#schema-Problem) |
| 403 | この API キーの用途か、対象のソースでは実行できない<br><br>返る code：`forbidden`・`needs_draft` | `application/problem+json`：[Problem](#schema-Problem) |
| 404 | 指定した ID かパスが無い（ほかの組織の ID も同じ応答になる）。削除した文書は、削除の起票が保守の GC で消えるまで DELETE が already_deleted を返し、その後は 404<br><br>返る code：`not_found` | `application/problem+json`：[Problem](#schema-Problem) |
| 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 が無ければ少し待ってからやり直す<br><br>返る code：`rate_limited`。ヘッダー：`Retry-After`（待つ秒数） | `application/problem+json`：[Problem](#schema-Problem) |
| 500 | サーバーで問題が起きた。少し待ってからやり直す<br><br>返る code：`internal_error` | `application/problem+json`：[Problem](#schema-Problem) |

<a id="op-discard_knowledge_draft"></a>
### discard_knowledge_draft

`DELETE /knowledge/drafts/{draft_id}` — 下書きを破棄する

下書きを作った API キーだけが破棄できる。公開済み・破棄済みの下書きは 409 already_decided

#### パラメータ

| 名前 | 場所 | 型 | 必須 | 説明 |
| --- | --- | --- | --- | --- |
| `draft_id` | パス | string | 必須 | 1〜64 文字 |

#### 応答

| 状態 | 説明 | 本文 |
| --- | --- | --- |
| 200 | 破棄した | `application/json`：[DiscardResult](#schema-DiscardResult) |
| 400 | 要求の形式か値が正しくない。errors（検証の誤り）に項目（path）ごとの理由が入る<br><br>返る code：`invalid_request`・`empty_manifest`・`duplicate_item` | `application/problem+json`：[Problem](#schema-Problem) |
| 401 | API キーが無いか無効（期限切れ・失効・削除の途中の組織を含み、理由は区別しない）<br><br>返る code：`unauthorized` | `application/problem+json`：[Problem](#schema-Problem) |
| 403 | この API キーの用途か、対象のソースでは実行できない<br><br>返る code：`forbidden`・`needs_draft` | `application/problem+json`：[Problem](#schema-Problem) |
| 404 | 指定した ID かパスが無い（ほかの組織の ID も同じ応答になる）。削除した文書は、削除の起票が保守の GC で消えるまで DELETE が already_deleted を返し、その後は 404<br><br>返る code：`not_found` | `application/problem+json`：[Problem](#schema-Problem) |
| 409 | 今の状態と合わない。code で見分ける<br><br>返る 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`・`external_id_taken`・`draft_limit_exceeded`・`already_decided`・`not_retryable` | `application/problem+json`：[Problem](#schema-Problem) |
| 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 が無ければ少し待ってからやり直す<br><br>返る code：`rate_limited`。ヘッダー：`Retry-After`（待つ秒数） | `application/problem+json`：[Problem](#schema-Problem) |
| 500 | サーバーで問題が起きた。少し待ってからやり直す<br><br>返る code：`internal_error` | `application/problem+json`：[Problem](#schema-Problem) |

<a id="op-get_knowledge_draft_content"></a>
### get_knowledge_draft_content

`GET /knowledge/drafts/{draft_id}/content` — 下書きの提案の本文

削除の下書きは本文を持たないので 404

#### パラメータ

| 名前 | 場所 | 型 | 必須 | 説明 |
| --- | --- | --- | --- | --- |
| `draft_id` | パス | string | 必須 | 1〜64 文字 |

#### 応答

| 状態 | 説明 | 本文 |
| --- | --- | --- |
| 200 | 提案の本文（Content-Disposition: attachment） | `application/octet-stream`：string（binary） |
| 400 | 要求の形式か値が正しくない。errors（検証の誤り）に項目（path）ごとの理由が入る<br><br>返る code：`invalid_request`・`empty_manifest`・`duplicate_item` | `application/problem+json`：[Problem](#schema-Problem) |
| 401 | API キーが無いか無効（期限切れ・失効・削除の途中の組織を含み、理由は区別しない）<br><br>返る code：`unauthorized` | `application/problem+json`：[Problem](#schema-Problem) |
| 403 | この API キーの用途か、対象のソースでは実行できない<br><br>返る code：`forbidden`・`needs_draft` | `application/problem+json`：[Problem](#schema-Problem) |
| 404 | 指定した ID かパスが無い（ほかの組織の ID も同じ応答になる）。削除した文書は、削除の起票が保守の GC で消えるまで DELETE が already_deleted を返し、その後は 404<br><br>返る code：`not_found` | `application/problem+json`：[Problem](#schema-Problem) |
| 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 が無ければ少し待ってからやり直す<br><br>返る code：`rate_limited`。ヘッダー：`Retry-After`（待つ秒数） | `application/problem+json`：[Problem](#schema-Problem) |
| 500 | サーバーで問題が起きた。少し待ってからやり直す<br><br>返る code：`internal_error` | `application/problem+json`：[Problem](#schema-Problem) |

## スキーマ

<a id="schema-Problem"></a>
### Problem

| 項目 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `type` | string | 必須 | `urn:leafchat:problem:<code>` |
| `title` | string | 必須 |  |
| `status` | integer | 必須 |  |
| `detail` | string | 任意 |  |
| `code` | string | 必須 | 誤りの種類。値と意味は、この文書の冒頭（info）の「誤りのコード」の表にある。値は増えることがあるので、知らない値は status で扱う |

表に無い項目が入ることがある。

<a id="schema-Source"></a>
### Source

| 項目 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `id` | string | 必須 |  |
| `name` | string | 必須 |  |
| `mode` | string | 必須 | 値：`managed`・`sync` |
| `is_default` | boolean | 必須 |  |
| `default_folder_id` | string または null | 必須 |  |
| `document_count` | integer | 必須 |  |
| `last_synced_at` | string（date-time） または null | 必須 |  |
| `last_sync_summary` | object または null | 必須 |  |
| `last_sync_summary.created` | integer | 必須 |  |
| `last_sync_summary.updated` | integer | 必須 |  |
| `last_sync_summary.renamed` | integer | 必須 |  |
| `last_sync_summary.moved` | integer | 必須 |  |
| `last_sync_summary.deleted` | integer | 必須 |  |
| `last_sync_summary.unchanged` | integer | 必須 |  |

<a id="schema-SyncResponse"></a>
### SyncResponse

| 項目 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `dry_run` | boolean | 必須 |  |
| `plan` | object | 必須 |  |
| `plan.folders_to_create` | object の配列 | 必須 |  |
| `plan.folders_to_create[].name` | string | 必須 |  |
| `plan.folders_to_create[].similar_to` | string または null | 必須 | 空白・大文字小文字・全角半角だけが違う既存のフォルダの名前（打ち間違いの手がかり） |
| `plan.create` | object の配列 | 必須 |  |
| `plan.create[].external_id` | string | 必須 |  |
| `plan.create[].filename` | string | 必須 |  |
| `plan.create[].parts` | integer または null | 必須 | 参照の形（sha256）で送った項目は、中身を受け取る前なので null |
| `plan.create[].folder_id` | string または null | 必須 | この同期で作るフォルダなら null |
| `plan.create[].folder_name` | string | 必須 |  |
| `plan.update` | object の配列 | 必須 |  |
| `plan.update[].external_id` | string | 必須 |  |
| `plan.update[].document_id` | string | 必須 |  |
| `plan.update[].filename` | string | 必須 |  |
| `plan.update[].parts` | integer または null | 必須 |  |
| `plan.update[].to_folder_id` | string または null | 必須 |  |
| `plan.update[].to_folder_name` | string または null | 必須 |  |
| `plan.move` | object の配列 | 必須 |  |
| `plan.move[].external_id` | string | 必須 |  |
| `plan.move[].document_id` | string | 必須 |  |
| `plan.move[].to_folder_id` | string または null | 必須 | この同期で作るフォルダなら null |
| `plan.move[].to_folder_name` | string | 必須 |  |
| `plan.rename` | object の配列 | 必須 | 消える文書と現れる文書の中身の SHA-256 が一致し、組が 1 つに決まったもの。文書 ID と版の履歴が続く（items では常に空） |
| `plan.rename[].from_external_id` | string | 必須 | 今の external_id（前回のパス） |
| `plan.rename[].external_id` | string | 必須 | 新しい external_id（今回のパス） |
| `plan.rename[].document_id` | string | 必須 |  |
| `plan.rename[].filename` | string | 必須 |  |
| `plan.rename[].to_folder_id` | string または null | 必須 | フォルダが変わらないか、この同期で作るフォルダなら null |
| `plan.rename[].to_folder_name` | string または null | 必須 | フォルダが変わらなければ null |
| `plan.delete` | object の配列 | 必須 |  |
| `plan.delete[].external_id` | string | 必須 |  |
| `plan.delete[].document_id` | string | 必須 |  |
| `plan.delete[].filename` | string | 必須 |  |
| `plan.unchanged` | string の配列 | 必須 |  |
| `plan.unmanaged` | string の配列 | 必須 |  |
| `limits` | object | 必須 |  |
| `limits.delete_cap` | integer | 必須 |  |
| `limits.max_files` | integer | 必須 |  |
| `limits.source_count` | integer | 必須 |  |
| `limits.total_count` | integer | 必須 |  |
| `uploads_required` | [UploadNeed](#schema-UploadNeed) の配列 | 必須 | まだ受け取っていないファイル。PUT …/uploads/{sha256} で上げてから実行の同期を呼ぶ |
| `warnings` | object または object の配列 | 必須 |  |
| `created_folders` | object の配列 | 必須 |  |
| `created_folders[].name` | string | 必須 |  |
| `created_folders[].folder_id` | string | 必須 |  |
| `executed` | object の配列 | 必須 |  |
| `executed[].kind` | string | 必須 | 値：`create`・`update`・`rename`・`move`・`delete` |
| `executed[].external_id` | string | 必須 |  |
| `executed[].document_id` | string | 必須 |  |
| `executed[].revision_id` | string または null | 必須 |  |
| `remaining` | integer | 必須 | まだ実行していない操作の数。0 になるまで同じ一式で呼び直す |

<a id="schema-UploadNeed"></a>
### UploadNeed

| 項目 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `sha256` | string | 必須 |  |
| `size` | integer | 必須 |  |
| `content_type` | string | 必須 |  |
| `external_ids` | string の配列 | 必須 |  |

<a id="schema-SyncRequest"></a>
### SyncRequest

| 項目 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `items` | object の配列 | 任意 | 500 件まで |
| `items[].external_id` | string | 必須 | 1〜512 文字 |
| `items[].filename` | string | 必須 | 1〜200 文字 |
| `items[].content` | string | 必須 |  |
| `items[].content_type` | string | 必須 | 値：`text/markdown`・`text/plain` |
| `items[].folder_id` | string | 任意 | 1〜64 文字 |
| `files` | [SyncFileInline](#schema-SyncFileInline) または [SyncFileRef](#schema-SyncFileRef) の配列 | 任意 | 500 件まで |
| `confirmed_deletes` | string の配列 | 任意 | 500 件まで。各要素：512 文字まで。既定：`[]` |
| `allow_empty` | boolean | 任意 | 既定：`false` |
| `dry_run` | boolean | 任意 | 既定：`false` |
| `client` | [SyncClient](#schema-SyncClient) | 任意 |  |

表に無い項目を送ると 400 になる。

<a id="schema-SyncFileInline"></a>
### SyncFileInline

| 項目 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `path` | string | 必須 | ソースの根からの相対パス（`/` 区切り・NFC）。最初の階層がフォルダ、最後がファイル名。2 階層まで。1〜512 文字 |
| `external_id` | string | 任意 | 省くと path を外部 ID にする。送り手が変わらない ID を持つときだけ送る。1〜512 文字 |
| `content` | string | 必須 |  |
| `content_type` | string | 必須 | 値：`text/markdown`・`text/plain`・`application/json` |

表に無い項目を送ると 400 になる。

<a id="schema-SyncFileRef"></a>
### SyncFileRef

| 項目 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `path` | string | 必須 | ソースの根からの相対パス（`/` 区切り・NFC）。最初の階層がフォルダ、最後がファイル名。2 階層まで。1〜512 文字 |
| `external_id` | string | 任意 | 省くと path を外部 ID にする。送り手が変わらない ID を持つときだけ送る。1〜512 文字 |
| `sha256` | string | 必須 | ファイルの中身の SHA-256（16 進の小文字）。形式：`^[0-9a-f]{64}$` |
| `size` | integer | 必須 | バイト数。形式ごとの上限（テキスト 4 MiB・その他 15 MiB）まで。1〜15728640 |
| `content_type` | string | 必須 | 値：`text/plain`・`text/markdown`・`application/json`・`text/html`・`text/csv`・`application/pdf`・`application/vnd.openxmlformats-officedocument.wordprocessingml.document` |

表に無い項目を送ると 400 になる。

<a id="schema-SyncClient"></a>
### SyncClient

| 項目 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `name` | string | 必須 | 1〜40 文字。形式：`^[a-z0-9][a-z0-9._-]*$` |
| `version` | string | 必須 | 1〜40 文字。形式：`^[0-9A-Za-z.+-]+$` |
| `ci` | string | 任意 | 値：`github_actions`・`other` |
| `repository` | string | 任意 | 140 文字まで。形式：`^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$` |
| `run_url` | string（uri） | 任意 | 同期を実行した CI の実行の URL（https だけ）。500 文字まで |

表に無い項目を送ると 400 になる。

<a id="schema-UploadAccepted"></a>
### UploadAccepted

| 項目 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `sha256` | string | 必須 |  |
| `size` | integer | 必須 |  |
| `already_uploaded` | boolean | 必須 |  |

<a id="schema-Folder"></a>
### Folder

| 項目 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `id` | string | 必須 |  |
| `name` | string | 必須 |  |
| `is_global` | boolean | 必須 |  |
| `is_default` | boolean | 必須 |  |
| `sites` | object の配列 | 必須 |  |
| `sites[].id` | string | 必須 |  |
| `sites[].name` | string | 必須 |  |

<a id="schema-Document"></a>
### Document

| 項目 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `id` | string | 必須 |  |
| `source_id` | string | 必須 |  |
| `external_id` | string または null | 必須 |  |
| `folder_id` | string または null | 必須 | null はフォルダに割り当てる前に登録した文書。サイト別の出し分けを有効にすると既定のフォルダに入る |
| `filename` | string | 必須 |  |
| `mime` | string または null | 必須 |  |
| `size` | integer または null | 必須 |  |
| `status` | string | 必須 | 値：`processing`・`pending`・`ready`・`error` |
| `current_revision` | [RevisionRef](#schema-RevisionRef) または null | 必須 | 公開中の版。公開した版がまだ無い文書では null |
| `head_revision` | [RevisionRef](#schema-RevisionRef) | 必須 |  |
| `created_at` | string（date-time） | 必須 |  |
| `updated_at` | string（date-time） | 必須 |  |

<a id="schema-RevisionRef"></a>
### RevisionRef

| 項目 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `id` | string | 必須 |  |
| `number` | integer | 必須 |  |
| `state` | string | 必須 | 値：`queued`・`processing`・`indexing`・`live`・`failed`・`superseded`・`abandoned` |
| `error_message` | string または null | 必須 |  |
| `created_at` | string（date-time） | 必須 |  |

<a id="schema-Revision"></a>
### Revision

[RevisionRef](#schema-RevisionRef) の項目に加えて、次の項目を持つ。

| 項目 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `filename` | string | 必須 |  |
| `mime` | string | 必須 |  |
| `size` | integer | 必須 |  |
| `content_sha256` | string または null | 必須 |  |
| `origin` | string | 必須 | 値：`dashboard`・`api`・`mcp`・`sync`・`draft`・`restore`・`system` |
| `actor` | object | 必須 |  |
| `actor.type` | string | 必須 | 値：`operator`・`api_key`・`system` |
| `actor.id` | string または null | 必須 |  |
| `live_at` | string（date-time） または null | 必須 |  |
| `superseded_at` | string（date-time） または null | 必須 |  |
| `original_available` | boolean | 必須 |  |

<a id="schema-DocumentAccepted"></a>
### DocumentAccepted

| 項目 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `document_id` | string | 必須 |  |
| `revision_id` | string | 必須 |  |
| `created` | boolean | 必須 | 新しい文書（POST）か新しい版（PATCH・復元）を作ったか。同じ内容なら false で、状態は 200 |

<a id="schema-CreateDocument"></a>
### CreateDocument

| 項目 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `source_id` | string | 任意 | 1〜64 文字 |
| `folder_id` | string | 任意 | 1〜64 文字 |
| `external_id` | string | 任意 | 外部 ID は、ソースの中で一意の文字列です。UTF-8 で 512 バイトまで、Unicode の NFC にそろえ、`/` で区切れます。空の区切り・`.`・`..`・区切りの前後の空白・制御文字・`\` は使えません。例：`faq/shipping`、`渋谷店/営業時間.md`。512 文字まで |
| `filename` | string | 必須 | 1〜40 文字 |
| `content` | string | 必須 | 1 文字以上 |
| `content_type` | string | 必須 | 値：`text/markdown`・`text/plain`・`application/json` |

表に無い項目を送ると 400 になる。

<a id="schema-CreateDocumentMultipart"></a>
### CreateDocumentMultipart

| 項目 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `file` | string（binary） | 必須 |  |
| `source_id` | string | 任意 | 1〜64 文字 |
| `folder_id` | string | 任意 | 1〜64 文字 |
| `external_id` | string | 任意 | 外部 ID は、ソースの中で一意の文字列です。UTF-8 で 512 バイトまで、Unicode の NFC にそろえ、`/` で区切れます。空の区切り・`.`・`..`・区切りの前後の空白・制御文字・`\` は使えません。例：`faq/shipping`、`渋谷店/営業時間.md`。512 文字まで |

表に無い項目を送ると 400 になる。

<a id="schema-UpsertResult"></a>
### UpsertResult

| 項目 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `document_id` | string | 必須 |  |
| `revision_id` | string | 必須 |  |
| `outcome` | string | 必須 | 値：`created`・`updated`・`unchanged` |

<a id="schema-UpsertDocument"></a>
### UpsertDocument

| 項目 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `filename` | string | 必須 | 1〜40 文字 |
| `content` | string | 必須 | 1 文字以上 |
| `content_type` | string | 必須 | 値：`text/markdown`・`text/plain`・`application/json` |

表に無い項目を送ると 400 になる。

<a id="schema-PatchDocument"></a>
### PatchDocument

| 項目 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `content` | string | 任意 | 1 文字以上 |
| `content_type` | string | 任意 | 値：`text/markdown`・`text/plain`・`application/json` |
| `edits` | object の配列 | 任意 | 1〜20 件 |
| `edits[].old_text` | string | 必須 | 1 文字以上 |
| `edits[].new_text` | string | 必須 |  |
| `filename` | string | 任意 | 1〜40 文字 |
| `folder_id` | string | 任意 | 1〜64 文字 |
| `source_id` | string | 任意 | 1〜64 文字 |
| `external_id` | string または null | 任意 | 外部 ID は、ソースの中で一意の文字列です。UTF-8 で 512 バイトまで、Unicode の NFC にそろえ、`/` で区切れます。空の区切り・`.`・`..`・区切りの前後の空白・制御文字・`\` は使えません。例：`faq/shipping`、`渋谷店/営業時間.md`。512 文字まで |

表に無い項目を送ると 400 になる。

<a id="schema-DeleteResult"></a>
### DeleteResult

| 項目 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `document_id` | string | 必須 |  |
| `outcome` | string | 必須 | 値：`deleted`・`already_deleted` |

<a id="schema-RetryResult"></a>
### RetryResult

| 項目 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `document_id` | string | 必須 |  |
| `revision_id` | string | 必須 |  |

<a id="schema-Draft"></a>
### Draft

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

<a id="schema-CreateDraft"></a>
### CreateDraft

次のどれか（`operation` で見分ける）：[CreateDraftOfCreate](#schema-CreateDraftOfCreate)・[CreateDraftOfUpdate](#schema-CreateDraftOfUpdate)・[CreateDraftOfDelete](#schema-CreateDraftOfDelete)

<a id="schema-CreateDraftOfCreate"></a>
### CreateDraftOfCreate

| 項目 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `operation` | string | 必須 | 値：`create` |
| `source_id` | string | 任意 | 1〜64 文字 |
| `folder_id` | string | 任意 | 1〜64 文字 |
| `external_id` | string | 任意 | 外部 ID は、ソースの中で一意の文字列です。UTF-8 で 512 バイトまで、Unicode の NFC にそろえ、`/` で区切れます。空の区切り・`.`・`..`・区切りの前後の空白・制御文字・`\` は使えません。例：`faq/shipping`、`渋谷店/営業時間.md`。512 文字まで |
| `filename` | string | 必須 | 1〜40 文字 |
| `content` | string | 必須 | 1 文字以上 |
| `content_type` | string | 必須 | 値：`text/markdown`・`text/plain`・`application/json` |
| `summary` | string | 必須 | 1〜120 文字 |
| `rationale` | string | 必須 | 1〜2000 文字 |
| `evidence` | object | 任意 | 提案の根拠。組織に無い ID と、内部の会話の ID は 422。公開すると根拠の未回答はアーカイブされる |
| `evidence.conversation_ids` | string の配列 | 任意 | 10 件まで。各要素：1〜64 文字。既定：`[]` |
| `evidence.unanswered_question_ids` | string の配列 | 任意 | 20 件まで。各要素：1〜64 文字。既定：`[]` |

表に無い項目を送ると 400 になる。

<a id="schema-CreateDraftOfUpdate"></a>
### CreateDraftOfUpdate

| 項目 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `operation` | string | 必須 | 値：`update` |
| `document_id` | string | 必須 | 1〜64 文字 |
| `base_revision_id` | string | 任意 | 読んだ版（GET の ETag の中身）。今の版と違えば 412。無ければ今の head を基準にする。1〜64 文字 |
| `filename` | string | 任意 | 1〜40 文字 |
| `content` | string | 任意 | 1 文字以上 |
| `content_type` | string | 任意 | 値：`text/markdown`・`text/plain`・`application/json` |
| `edits` | object の配列 | 任意 | 1〜20 件 |
| `edits[].old_text` | string | 必須 | 1 文字以上 |
| `edits[].new_text` | string | 必須 |  |
| `summary` | string | 必須 | 1〜120 文字 |
| `rationale` | string | 必須 | 1〜2000 文字 |
| `evidence` | object | 任意 | 提案の根拠。組織に無い ID と、内部の会話の ID は 422。公開すると根拠の未回答はアーカイブされる |
| `evidence.conversation_ids` | string の配列 | 任意 | 10 件まで。各要素：1〜64 文字。既定：`[]` |
| `evidence.unanswered_question_ids` | string の配列 | 任意 | 20 件まで。各要素：1〜64 文字。既定：`[]` |

表に無い項目を送ると 400 になる。

<a id="schema-CreateDraftOfDelete"></a>
### CreateDraftOfDelete

| 項目 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `operation` | string | 必須 | 値：`delete` |
| `document_id` | string | 必須 | 1〜64 文字 |
| `base_revision_id` | string | 任意 | 読んだ版（GET の ETag の中身）。今の版と違えば 412。無ければ今の head を基準にする。1〜64 文字 |
| `summary` | string | 必須 | 1〜120 文字 |
| `rationale` | string | 必須 | 1〜2000 文字 |
| `evidence` | object | 任意 | 提案の根拠。組織に無い ID と、内部の会話の ID は 422。公開すると根拠の未回答はアーカイブされる |
| `evidence.conversation_ids` | string の配列 | 任意 | 10 件まで。各要素：1〜64 文字。既定：`[]` |
| `evidence.unanswered_question_ids` | string の配列 | 任意 | 20 件まで。各要素：1〜64 文字。既定：`[]` |

表に無い項目を送ると 400 になる。

<a id="schema-DiscardResult"></a>
### DiscardResult

| 項目 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `draft_id` | string | 必須 |  |
| `state` | string | 必須 | 値：`discarded` |