{"openapi":"3.1.0","info":{"title":"leafchat API","summary":"ナレッジの読み書きと同期の REST API","version":"1.0.0","description":"ナレッジの読み書きと同期の API。認証は Authorization: Bearer lck_…\n\n- AI エージェント向けの Markdown 版：<https://api.leafchat.app/api/v1/docs.md>\n- MCP サーバー：`https://api.leafchat.app/mcp`（接続のしかたとツールの一覧：<https://api.leafchat.app/mcp.md>）\n- 公式の CLI と GitHub Action：<https://github.com/leafchat/cli>\n\n- JSON のキーは snake_case、時刻は ISO 8601（UTC）。\n- 書き込みは 202 で受け付ける。反映の状態は GET の current_revision と head_revision で確かめる。\n- 楽観ロック：GET の ETag（\"<head の版の ID>\"）を If-Match に入れる。本文を変える PATCH では必須。\n- 誤りは RFC 9457（application/problem+json）。code で種類を見分ける。\n- テキストの本文は、分割の上限（3 KiB × 512 個）が先に効き、実際は約 1.5 MiB まで（422 too_many_parts）。\n\n## 誤りのコード\n\n| code | 状態 | 意味と直し方 |\n| --- | --- | --- |\n| `invalid_request` | 400・411・422 | 要求の形式か値が正しくない。errors（項目ごとの理由）か detail を見て直す |\n| `empty_manifest` | 400 | 同期で送った一式が空。ソースの文書をすべて消すときは allow_empty を true にする |\n| `duplicate_item` | 400 | 同期で送った一式に、同じ external_id か path が複数ある。重複を除いて送る |\n| `unauthorized` | 401 | API キーが無いか無効（期限切れ・失効・削除の途中の組織を含み、理由は区別しない）。ダッシュボードで有効な鍵を確かめる |\n| `forbidden` | 403 | この API キーの用途か、対象のソースでは実行できない。必要な用途と対象の鍵を使う |\n| `needs_draft` | 403 | 用途「AI エージェント」の鍵は、文書を直接変えられない。POST /knowledge/drafts で下書きを作る |\n| `not_found` | 404 | 指定した ID かパスが無い（ほかの組織の ID も同じ応答になる）。ID と操作の一覧を確かめる |\n| `source_locked` | 409 | 同期のソースの文書は、同期（POST /knowledge/sources/{source_id}/sync）からだけ変えられる |\n| `limit_exceeded` | 409 | 組織の文書の数か、受け取り待ちのファイルの数が上限に達する。limit を見て減らす |\n| `delete_limit_exceeded` | 409 | 同期で消す数が、確認なしで消せる上限を超える。消してよい external_id を confirmed_deletes に入れる |\n| `folder_not_found` | 409 | 同期の path のフォルダが leafchat に無い（サイトごとにナレッジを分けている組織）。ダッシュボードでフォルダを作ってから同期する |\n| `folder_limit_exceeded` | 409 | 同期で作るフォルダが、組織のフォルダの上限を超える。置き場所のフォルダを減らす |\n| `upload_required` | 409 | 実行に要るファイルをまだ受け取っていない。uploads のファイルを PUT /knowledge/sources/{source_id}/uploads/{sha256} で上げてから実行する |\n| `upload_not_expected` | 409 | 計画が求めていないファイルか、予約の期限切れか、大きさが計画と違う。同期の計画（dry_run）を呼び直す |\n| `sync_in_progress` | 409 | 同じソースで別の同期を実行中。終わってからやり直す |\n| `not_sync_source` | 409 | 指定したソースは同期のソースではない。同期のソースの ID を指定する |\n| `external_id_taken` | 409 | この external_id は別の内容で使われている。更新は PUT /knowledge/sources/{source_id}/documents/{external_id} を使う |\n| `draft_limit_exceeded` | 409 | 未処理の下書きが上限に達している。ダッシュボードで処理してから作る |\n| `already_decided` | 409 | この下書きは公開か破棄が済んでいる。GET で状態を確かめる |\n| `not_retryable` | 409 | 最新の版は取り込みに失敗していないか、原本が残っていない。GET で状態を確かめ、原本が無ければ文書を作り直す |\n| `precondition_failed` | 412 | If-Match（下書きの作成では base_revision_id）の版が今の版と違う。GET で最新の ETag を取り直す |\n| `payload_too_large` | 413 | 本文かファイルが上限を超えた。小さくして送る |\n| `unsupported_media_type` | 415 | Content-Type が、その操作の受け付ける形式でない |\n| `edit_no_match` | 422 | edits の old_text が本文に無い。最新の本文を読み直して指定する |\n| `edit_ambiguous` | 422 | edits の old_text が本文に複数ある。前後の文字を含めて 1 か所に絞る |\n| `not_editable` | 422 | この形式の文書（PDF など）は edits で直せない。content で本文全体を置き換える |\n| `too_many_parts` | 422 | テキストが長すぎて分割の上限を超える。文書を分ける |\n| `invalid_item` | 422 | 同期の項目を受け付けられない（external_id・path・名前・形式・大きさ）。reason を見て直す |\n| `upload_mismatch` | 422 | 上げたファイルの大きさ・SHA-256・中身が、Content-Length・URL・形式と合わない。reason を見て直す |\n| `precondition_required` | 428 | 本文を変える PATCH に If-Match が無い。GET の ETag を If-Match に入れる |\n| `rate_limited` | 429 | 上限を超えた。Retry-After の秒数だけ待ってからやり直す |\n| `internal_error` | 500 | サーバーで問題が起きた。少し待ってからやり直す |\n| `operation_failed` | 502 | 同期の途中で操作が失敗した。cause が取り込めない中身を示すなら直し、それ以外は同じ一式で呼び直すと続きから実行する |\n| `storage_failed` | 503 | 保存かキューへの送信に失敗した。Retry-After の秒数だけ待ってからやり直す |\n| `search_unavailable` | 503 | ナレッジの検索の準備ができていない。Retry-After の秒数だけ待ってからやり直す |"},"servers":[{"url":"https://api.leafchat.app/api/v1"}],"tags":[{"name":"Sources","description":"ナレッジの持ち主の単位"},{"name":"Folders","description":"サイト別の出し分けの単位"},{"name":"Documents","description":"文書と版"},{"name":"Sync","description":"同期のソースに、置き場所の一式を送ってそろえる。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>"},{"name":"Drafts","description":"ナレッジの変更の提案。人がダッシュボードで差分を見て公開・破棄する（API からは公開できない）"}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","description":"ダッシュボードで発行した API キー（lck_ で始まる）"}},"responses":{"InvalidRequest":{"description":"要求の形式か値が正しくない。errors（検証の誤り）に項目（path）ごとの理由が入る\n\n返る code：`invalid_request`・`empty_manifest`・`duplicate_item`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Unauthorized":{"description":"API キーが無いか無効（期限切れ・失効・削除の途中の組織を含み、理由は区別しない）\n\n返る code：`unauthorized`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Forbidden":{"description":"この API キーの用途か、対象のソースでは実行できない\n\n返る code：`forbidden`・`needs_draft`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"NotFound":{"description":"指定した ID かパスが無い（ほかの組織の ID も同じ応答になる）。削除した文書は、削除の起票が保守の GC で消えるまで DELETE が already_deleted を返し、その後は 404\n\n返る code：`not_found`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Conflict":{"description":"今の状態と合わない。code で見分ける\n\n返る 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`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"LengthRequired":{"description":"Content-Length が無い\n\n返る code：`invalid_request`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"PreconditionFailed":{"description":"If-Match（下書きの作成では base_revision_id）の版が、今の head の版と違う。存在しない文書へ If-Match を付けた upsert でも返る\n\n返る code：`precondition_failed`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"PayloadTooLarge":{"description":"本文が上限を超えた（JSON 6 MiB・multipart 16 MiB・同期 8 MiB・同期のアップロード 15 MiB）。テキストの本文が 4 MiB を超えたときは、本文の上限の内側でも 422 invalid_request になる\n\n返る code：`payload_too_large`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"UnsupportedMediaType":{"description":"Content-Type が、その操作の受け付ける形式でない。文書の作成に application/x-www-form-urlencoded で送ると、415 ではなく 400 になる\n\n返る code：`unsupported_media_type`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Unprocessable":{"description":"内容を受け付けられない（編集の対象・分割の上限・形式・同期の項目・アップロードの中身など）。code で見分ける\n\n返る code：`invalid_request`・`edit_no_match`・`edit_ambiguous`・`not_editable`・`too_many_parts`・`invalid_item`・`upload_mismatch`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"PreconditionRequired":{"description":"本文を変える PATCH に If-Match が無い\n\n返る code：`precondition_required`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"RateLimited":{"description":"上限を超えた。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 が無ければ少し待ってからやり直す\n\n返る code：`rate_limited`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"Retry-After":{"description":"待つ秒数","schema":{"type":"integer"}}}},"InternalServerError":{"description":"サーバーで問題が起きた。少し待ってからやり直す\n\n返る code：`internal_error`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"BadGateway":{"description":"同期の途中で操作が失敗した。同じ一式で呼び直すと、済んだ操作を除いて続きから実行する\n\n返る code：`operation_failed`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"ServiceUnavailable":{"description":"保存かキューへの送信に失敗した（storage_failed）。Retry-After の秒数だけ待ってからやり直す。search_unavailable は今の操作からは返らない（変換の口と MCP のために目録に残している）\n\n返る code：`storage_failed`・`search_unavailable`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"Retry-After":{"description":"待つ秒数","schema":{"type":"integer"}}}}},"schemas":{"Problem":{"type":"object","properties":{"type":{"type":"string","description":"`urn:leafchat:problem:<code>`"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"code":{"type":"string","description":"誤りの種類。値と意味は、この文書の冒頭（info）の「誤りのコード」の表にある。値は増えることがあるので、知らない値は status で扱う"}},"required":["type","title","status","code"],"additionalProperties":{}},"Source":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"mode":{"type":"string","enum":["managed","sync"]},"is_default":{"type":"boolean"},"default_folder_id":{"type":["string","null"]},"document_count":{"type":"integer"},"last_synced_at":{"type":["string","null"],"format":"date-time","examples":["2026-09-29T02:31:07.000Z"]},"last_sync_summary":{"type":["object","null"],"properties":{"created":{"type":"integer"},"updated":{"type":"integer"},"renamed":{"type":"integer"},"moved":{"type":"integer"},"deleted":{"type":"integer"},"unchanged":{"type":"integer"}},"required":["created","updated","renamed","moved","deleted","unchanged"]}},"required":["id","name","mode","is_default","default_folder_id","document_count","last_synced_at","last_sync_summary"]},"SyncResponse":{"type":"object","properties":{"dry_run":{"type":"boolean"},"plan":{"type":"object","properties":{"folders_to_create":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"similar_to":{"type":["string","null"],"description":"空白・大文字小文字・全角半角だけが違う既存のフォルダの名前（打ち間違いの手がかり）"}},"required":["name","similar_to"]}},"create":{"type":"array","items":{"type":"object","properties":{"external_id":{"type":"string"},"filename":{"type":"string"},"parts":{"type":["integer","null"],"description":"参照の形（sha256）で送った項目は、中身を受け取る前なので null"},"folder_id":{"type":["string","null"],"description":"この同期で作るフォルダなら null"},"folder_name":{"type":"string"}},"required":["external_id","filename","parts","folder_id","folder_name"]}},"update":{"type":"array","items":{"type":"object","properties":{"external_id":{"type":"string"},"document_id":{"type":"string"},"filename":{"type":"string"},"parts":{"type":["integer","null"]},"to_folder_id":{"type":["string","null"]},"to_folder_name":{"type":["string","null"]}},"required":["external_id","document_id","filename","parts","to_folder_id","to_folder_name"]}},"move":{"type":"array","items":{"type":"object","properties":{"external_id":{"type":"string"},"document_id":{"type":"string"},"to_folder_id":{"type":["string","null"],"description":"この同期で作るフォルダなら null"},"to_folder_name":{"type":"string"}},"required":["external_id","document_id","to_folder_id","to_folder_name"]}},"rename":{"type":"array","items":{"type":"object","properties":{"from_external_id":{"type":"string","description":"今の external_id（前回のパス）"},"external_id":{"type":"string","description":"新しい external_id（今回のパス）"},"document_id":{"type":"string"},"filename":{"type":"string"},"to_folder_id":{"type":["string","null"],"description":"フォルダが変わらないか、この同期で作るフォルダなら null"},"to_folder_name":{"type":["string","null"],"description":"フォルダが変わらなければ null"}},"required":["from_external_id","external_id","document_id","filename","to_folder_id","to_folder_name"]},"description":"消える文書と現れる文書の中身の SHA-256 が一致し、組が 1 つに決まったもの。文書 ID と版の履歴が続く（items では常に空）"},"delete":{"type":"array","items":{"type":"object","properties":{"external_id":{"type":"string"},"document_id":{"type":"string"},"filename":{"type":"string"}},"required":["external_id","document_id","filename"]}},"unchanged":{"type":"array","items":{"type":"string"}},"unmanaged":{"type":"array","items":{"type":"string"}}},"required":["folders_to_create","create","update","move","rename","delete","unchanged","unmanaged"]},"limits":{"type":"object","properties":{"delete_cap":{"type":"integer"},"max_files":{"type":"integer"},"source_count":{"type":"integer"},"total_count":{"type":"integer"}},"required":["delete_cap","max_files","source_count","total_count"]},"uploads_required":{"type":"array","items":{"$ref":"#/components/schemas/UploadNeed"},"description":"まだ受け取っていないファイル。PUT …/uploads/{sha256} で上げてから実行の同期を呼ぶ"},"warnings":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"code":{"type":"string","enum":["same_filename_across_folders"]},"external_ids":{"type":"array","items":{"type":"string"}},"filename":{"type":"string"}},"required":["code","external_ids","filename"]},{"type":"object","properties":{"code":{"type":"string","enum":["chunk_boundary"]},"external_id":{"type":"string"},"part":{"type":"integer","description":"見出しから始まらないパートの番号（2 から）"},"line":{"type":"integer","description":"そのパートが始まる、本文の中の行（1 から）"}},"required":["code","external_id","part","line"]}]}},"created_folders":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"folder_id":{"type":"string"}},"required":["name","folder_id"]}},"executed":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["create","update","rename","move","delete"]},"external_id":{"type":"string"},"document_id":{"type":"string"},"revision_id":{"type":["string","null"]}},"required":["kind","external_id","document_id","revision_id"]}},"remaining":{"type":"integer","description":"まだ実行していない操作の数。0 になるまで同じ一式で呼び直す"}},"required":["dry_run","plan","limits","uploads_required","warnings","created_folders","executed","remaining"]},"UploadNeed":{"type":"object","properties":{"sha256":{"type":"string"},"size":{"type":"integer"},"content_type":{"type":"string"},"external_ids":{"type":"array","items":{"type":"string"}}},"required":["sha256","size","content_type","external_ids"]},"SyncRequest":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"external_id":{"type":"string","minLength":1,"maxLength":512},"filename":{"type":"string","minLength":1,"maxLength":200},"content":{"type":"string"},"content_type":{"type":"string","enum":["text/markdown","text/plain"]},"folder_id":{"type":"string","minLength":1,"maxLength":64}},"required":["external_id","filename","content","content_type"],"additionalProperties":false},"maxItems":500},"files":{"type":"array","items":{"anyOf":[{"$ref":"#/components/schemas/SyncFileInline"},{"$ref":"#/components/schemas/SyncFileRef"}]},"maxItems":500},"confirmed_deletes":{"type":"array","items":{"type":"string","maxLength":512},"maxItems":500,"default":[]},"allow_empty":{"type":"boolean","default":false},"dry_run":{"type":"boolean","default":false},"client":{"$ref":"#/components/schemas/SyncClient"}},"additionalProperties":false},"SyncFileInline":{"type":"object","properties":{"path":{"type":"string","minLength":1,"maxLength":512,"description":"ソースの根からの相対パス（`/` 区切り・NFC）。最初の階層がフォルダ、最後がファイル名。2 階層まで","examples":["渋谷店/営業時間.md"]},"external_id":{"type":"string","minLength":1,"maxLength":512,"description":"省くと path を外部 ID にする。送り手が変わらない ID を持つときだけ送る"},"content":{"type":"string"},"content_type":{"type":"string","enum":["text/markdown","text/plain","application/json"]}},"required":["path","content","content_type"],"additionalProperties":false},"SyncFileRef":{"type":"object","properties":{"path":{"type":"string","minLength":1,"maxLength":512,"description":"ソースの根からの相対パス（`/` 区切り・NFC）。最初の階層がフォルダ、最後がファイル名。2 階層まで","examples":["渋谷店/営業時間.md"]},"external_id":{"type":"string","minLength":1,"maxLength":512,"description":"省くと path を外部 ID にする。送り手が変わらない ID を持つときだけ送る"},"sha256":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"ファイルの中身の SHA-256（16 進の小文字）","examples":["9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"]},"size":{"type":"integer","minimum":1,"maximum":15728640,"description":"バイト数。形式ごとの上限（テキスト 4 MiB・その他 15 MiB）まで"},"content_type":{"type":"string","enum":["text/plain","text/markdown","application/json","text/html","text/csv","application/pdf","application/vnd.openxmlformats-officedocument.wordprocessingml.document"]}},"required":["path","sha256","size","content_type"],"additionalProperties":false},"SyncClient":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9._-]*$"},"version":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[0-9A-Za-z.+-]+$"},"ci":{"type":"string","enum":["github_actions","other"]},"repository":{"type":"string","maxLength":140,"pattern":"^[A-Za-z0-9_.-]+\\/[A-Za-z0-9_.-]+$"},"run_url":{"type":"string","maxLength":500,"format":"uri","description":"同期を実行した CI の実行の URL（https だけ）","examples":["https://github.com/example/knowledge/actions/runs/1"]}},"required":["name","version"],"additionalProperties":false},"UploadAccepted":{"type":"object","properties":{"sha256":{"type":"string"},"size":{"type":"integer"},"already_uploaded":{"type":"boolean"}},"required":["sha256","size","already_uploaded"]},"Folder":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"is_global":{"type":"boolean"},"is_default":{"type":"boolean"},"sites":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}}},"required":["id","name","is_global","is_default","sites"]},"Document":{"type":"object","properties":{"id":{"type":"string"},"source_id":{"type":"string"},"external_id":{"type":["string","null"]},"folder_id":{"type":["string","null"],"description":"null はフォルダに割り当てる前に登録した文書。サイト別の出し分けを有効にすると既定のフォルダに入る"},"filename":{"type":"string"},"mime":{"type":["string","null"]},"size":{"type":["integer","null"]},"status":{"type":"string","enum":["processing","pending","ready","error"]},"current_revision":{"anyOf":[{"$ref":"#/components/schemas/RevisionRef"},{"type":"null"}],"description":"公開中の版。公開した版がまだ無い文書では null"},"head_revision":{"$ref":"#/components/schemas/RevisionRef"},"created_at":{"type":"string","format":"date-time","examples":["2026-09-29T02:31:07.000Z"]},"updated_at":{"type":"string","format":"date-time","examples":["2026-09-29T02:31:07.000Z"]}},"required":["id","source_id","external_id","folder_id","filename","mime","size","status","current_revision","head_revision","created_at","updated_at"]},"RevisionRef":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"integer"},"state":{"type":"string","enum":["queued","processing","indexing","live","failed","superseded","abandoned"]},"error_message":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time","examples":["2026-09-29T02:31:07.000Z"]}},"required":["id","number","state","error_message","created_at"]},"Revision":{"allOf":[{"$ref":"#/components/schemas/RevisionRef"},{"type":"object","properties":{"filename":{"type":"string"},"mime":{"type":"string"},"size":{"type":"integer"},"content_sha256":{"type":["string","null"]},"origin":{"type":"string","enum":["dashboard","api","mcp","sync","draft","restore","system"]},"actor":{"type":"object","properties":{"type":{"type":"string","enum":["operator","api_key","system"]},"id":{"type":["string","null"]}},"required":["type","id"]},"live_at":{"type":["string","null"],"format":"date-time","examples":["2026-09-29T02:31:07.000Z"]},"superseded_at":{"type":["string","null"],"format":"date-time","examples":["2026-09-29T02:31:07.000Z"]},"original_available":{"type":"boolean"}},"required":["filename","mime","size","content_sha256","origin","actor","live_at","superseded_at","original_available"]}]},"DocumentAccepted":{"type":"object","properties":{"document_id":{"type":"string"},"revision_id":{"type":"string"},"created":{"type":"boolean","description":"新しい文書（POST）か新しい版（PATCH・復元）を作ったか。同じ内容なら false で、状態は 200"}},"required":["document_id","revision_id","created"]},"CreateDocument":{"type":"object","properties":{"source_id":{"type":"string","minLength":1,"maxLength":64},"folder_id":{"type":"string","minLength":1,"maxLength":64},"external_id":{"type":"string","maxLength":512,"description":"外部 ID は、ソースの中で一意の文字列です。UTF-8 で 512 バイトまで、Unicode の NFC にそろえ、`/` で区切れます。空の区切り・`.`・`..`・区切りの前後の空白・制御文字・`\\` は使えません。例：`faq/shipping`、`渋谷店/営業時間.md`","examples":["faq/shipping"]},"filename":{"type":"string","minLength":1,"maxLength":40},"content":{"type":"string","minLength":1},"content_type":{"type":"string","enum":["text/markdown","text/plain","application/json"]}},"required":["filename","content","content_type"],"additionalProperties":false},"CreateDocumentMultipart":{"type":"object","properties":{"file":{"type":"string","format":"binary"},"source_id":{"type":"string","minLength":1,"maxLength":64},"folder_id":{"type":"string","minLength":1,"maxLength":64},"external_id":{"type":"string","maxLength":512,"description":"外部 ID は、ソースの中で一意の文字列です。UTF-8 で 512 バイトまで、Unicode の NFC にそろえ、`/` で区切れます。空の区切り・`.`・`..`・区切りの前後の空白・制御文字・`\\` は使えません。例：`faq/shipping`、`渋谷店/営業時間.md`","examples":["faq/shipping"]}},"required":["file"],"additionalProperties":false},"UpsertResult":{"type":"object","properties":{"document_id":{"type":"string"},"revision_id":{"type":"string"},"outcome":{"type":"string","enum":["created","updated","unchanged"]}},"required":["document_id","revision_id","outcome"]},"UpsertDocument":{"type":"object","properties":{"filename":{"type":"string","minLength":1,"maxLength":40},"content":{"type":"string","minLength":1},"content_type":{"type":"string","enum":["text/markdown","text/plain","application/json"]}},"required":["filename","content","content_type"],"additionalProperties":false},"PatchDocument":{"type":"object","properties":{"content":{"type":"string","minLength":1},"content_type":{"type":"string","enum":["text/markdown","text/plain","application/json"]},"edits":{"type":"array","items":{"type":"object","properties":{"old_text":{"type":"string","minLength":1},"new_text":{"type":"string"}},"required":["old_text","new_text"],"additionalProperties":false},"minItems":1,"maxItems":20},"filename":{"type":"string","minLength":1,"maxLength":40},"folder_id":{"type":"string","minLength":1,"maxLength":64},"source_id":{"type":"string","minLength":1,"maxLength":64},"external_id":{"type":["string","null"],"maxLength":512,"description":"外部 ID は、ソースの中で一意の文字列です。UTF-8 で 512 バイトまで、Unicode の NFC にそろえ、`/` で区切れます。空の区切り・`.`・`..`・区切りの前後の空白・制御文字・`\\` は使えません。例：`faq/shipping`、`渋谷店/営業時間.md`","examples":["faq/shipping"]}},"additionalProperties":false},"DeleteResult":{"type":"object","properties":{"document_id":{"type":"string"},"outcome":{"type":"string","enum":["deleted","already_deleted"]}},"required":["document_id","outcome"]},"RetryResult":{"type":"object","properties":{"document_id":{"type":"string"},"revision_id":{"type":"string"}},"required":["document_id","revision_id"]},"Draft":{"type":"object","properties":{"id":{"type":"string"},"operation":{"type":"string","enum":["create","update","delete"]},"state":{"type":"string","enum":["open","published","discarded"]},"summary":{"type":"string"},"rationale":{"type":"string"},"evidence":{"type":"object","properties":{"conversation_ids":{"type":"array","items":{"type":"string"}},"unanswered_question_ids":{"type":"array","items":{"type":"string"}}},"required":["conversation_ids","unanswered_question_ids"]},"document_id":{"type":["string","null"],"description":"更新・削除の対象の文書。作成では null"},"base_revision_id":{"type":["string","null"],"description":"下書きを作ったときの、対象の文書の head の版"},"stale":{"type":"boolean","description":"下書きを作った後に、対象の文書が変わったか消えた。公開する人が置き換えを選ばないと公開できない"},"target":{"type":["object","null"],"properties":{"exists":{"type":"boolean"},"filename":{"type":["string","null"]},"head_revision_id":{"type":["string","null"]}},"required":["exists","filename","head_revision_id"],"description":"対象の文書の今の状態。作成では null"},"source_id":{"type":["string","null"]},"folder_id":{"type":["string","null"]},"external_id":{"type":["string","null"]},"filename":{"type":["string","null"],"description":"提案のファイル名。削除では null"},"mime":{"type":["string","null"]},"size":{"type":["integer","null"]},"content_sha256":{"type":["string","null"]},"author":{"type":"object","properties":{"type":{"type":"string","enum":["operator","api_key"]},"id":{"type":["string","null"]},"via":{"type":"string","enum":["mcp","api"]}},"required":["type","id","via"]},"published_document_id":{"type":["string","null"]},"published_revision_id":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time","examples":["2026-09-29T02:31:07.000Z"]},"decided_at":{"type":["string","null"],"format":"date-time","examples":["2026-09-29T02:31:07.000Z"]}},"required":["id","operation","state","summary","rationale","evidence","document_id","base_revision_id","stale","target","source_id","folder_id","external_id","filename","mime","size","content_sha256","author","published_document_id","published_revision_id","created_at","decided_at"]},"CreateDraft":{"oneOf":[{"$ref":"#/components/schemas/CreateDraftOfCreate"},{"$ref":"#/components/schemas/CreateDraftOfUpdate"},{"$ref":"#/components/schemas/CreateDraftOfDelete"}],"discriminator":{"propertyName":"operation","mapping":{"create":"#/components/schemas/CreateDraftOfCreate","update":"#/components/schemas/CreateDraftOfUpdate","delete":"#/components/schemas/CreateDraftOfDelete"}}},"CreateDraftOfCreate":{"type":"object","properties":{"operation":{"type":"string","enum":["create"]},"source_id":{"type":"string","minLength":1,"maxLength":64},"folder_id":{"type":"string","minLength":1,"maxLength":64},"external_id":{"type":"string","maxLength":512,"description":"外部 ID は、ソースの中で一意の文字列です。UTF-8 で 512 バイトまで、Unicode の NFC にそろえ、`/` で区切れます。空の区切り・`.`・`..`・区切りの前後の空白・制御文字・`\\` は使えません。例：`faq/shipping`、`渋谷店/営業時間.md`","examples":["faq/shipping"]},"filename":{"type":"string","minLength":1,"maxLength":40},"content":{"type":"string","minLength":1},"content_type":{"type":"string","enum":["text/markdown","text/plain","application/json"]},"summary":{"type":"string","minLength":1,"maxLength":120},"rationale":{"type":"string","minLength":1,"maxLength":2000},"evidence":{"type":"object","properties":{"conversation_ids":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"maxItems":10,"default":[]},"unanswered_question_ids":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"maxItems":20,"default":[]}},"additionalProperties":false,"description":"提案の根拠。組織に無い ID と、内部の会話の ID は 422。公開すると根拠の未回答はアーカイブされる"}},"required":["operation","filename","content","content_type","summary","rationale"],"additionalProperties":false},"CreateDraftOfUpdate":{"type":"object","properties":{"operation":{"type":"string","enum":["update"]},"document_id":{"type":"string","minLength":1,"maxLength":64},"base_revision_id":{"type":"string","minLength":1,"maxLength":64,"description":"読んだ版（GET の ETag の中身）。今の版と違えば 412。無ければ今の head を基準にする"},"filename":{"type":"string","minLength":1,"maxLength":40},"content":{"type":"string","minLength":1},"content_type":{"type":"string","enum":["text/markdown","text/plain","application/json"]},"edits":{"type":"array","items":{"type":"object","properties":{"old_text":{"type":"string","minLength":1},"new_text":{"type":"string"}},"required":["old_text","new_text"],"additionalProperties":false},"minItems":1,"maxItems":20},"summary":{"type":"string","minLength":1,"maxLength":120},"rationale":{"type":"string","minLength":1,"maxLength":2000},"evidence":{"type":"object","properties":{"conversation_ids":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"maxItems":10,"default":[]},"unanswered_question_ids":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"maxItems":20,"default":[]}},"additionalProperties":false,"description":"提案の根拠。組織に無い ID と、内部の会話の ID は 422。公開すると根拠の未回答はアーカイブされる"}},"required":["operation","document_id","summary","rationale"],"additionalProperties":false},"CreateDraftOfDelete":{"type":"object","properties":{"operation":{"type":"string","enum":["delete"]},"document_id":{"type":"string","minLength":1,"maxLength":64},"base_revision_id":{"type":"string","minLength":1,"maxLength":64,"description":"読んだ版（GET の ETag の中身）。今の版と違えば 412。無ければ今の head を基準にする"},"summary":{"type":"string","minLength":1,"maxLength":120},"rationale":{"type":"string","minLength":1,"maxLength":2000},"evidence":{"type":"object","properties":{"conversation_ids":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"maxItems":10,"default":[]},"unanswered_question_ids":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"maxItems":20,"default":[]}},"additionalProperties":false,"description":"提案の根拠。組織に無い ID と、内部の会話の ID は 422。公開すると根拠の未回答はアーカイブされる"}},"required":["operation","document_id","summary","rationale"],"additionalProperties":false},"DiscardResult":{"type":"object","properties":{"draft_id":{"type":"string"},"state":{"type":"string","enum":["discarded"]}},"required":["draft_id","state"]}},"parameters":{}},"paths":{"/knowledge/sources":{"get":{"operationId":"list_knowledge_sources","tags":["Sources"],"summary":"ソースの一覧","security":[{"ApiKey":[]}],"responses":{"200":{"description":"組織のソース（既定のソースが先頭）","content":{"application/json":{"schema":{"type":"object","properties":{"sources":{"type":"array","items":{"$ref":"#/components/schemas/Source"}}},"required":["sources"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/knowledge/sources/{source_id}":{"get":{"operationId":"get_knowledge_source","tags":["Sources"],"summary":"ソースの取得","security":[{"ApiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64,"examples":["k9x2m4q7w1e5r8t3y6u0i2o4"]},"required":true,"name":"source_id","in":"path"}],"responses":{"200":{"description":"ソース","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Source"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/knowledge/sources/{source_id}/sync":{"post":{"operationId":"sync_knowledge_source","tags":["Sync"],"summary":"同期のソースに一式を送る","description":"送った一式と、ソースの今の文書を external_id で突き合わせ、作成・更新・名前の変更・移動・削除を計画して実行する。一式は items か files のどちらか一方で送る。\n\nfiles の項目は、テキスト（md・txt・json）なら本文（content）ごと、それ以外（html・csv・pdf・docx。テキストも可）は参照（sha256・size・content_type）で送る。参照の項目は計画の uploads_required に出たファイルを PUT …/uploads/{sha256} で上げてから実行する。足りないまま実行すると 409 upload_required になる。参照の項目の作成・更新は 1 回の実行で 10 件まで（残りは remaining）。\n\nfiles で送ると、パスの最初の階層をフォルダ、最後をファイル名として扱う（2 階層まで）。leafchat に無いフォルダは、サイトごとにナレッジを分けていない組織なら実行のときに作り、分けている組織では 409 folder_not_found で止める。client には送り手の名前・版・CI・実行の URL を入れる。ダッシュボードのソースの画面に出る。\n\nfiles で送ると、消える文書と現れる文書の中身の SHA-256 が一致し、組が 1 つに決まるものは、削除と作成ではなく名前の変更（rename）として扱う。文書 ID と版の履歴が続く。名前と中身を同時に変えると削除と作成になる。\n\ndry_run が true なら計画だけを返し、文書を書かない（読み取りの用途の鍵でも使える）。用途「同期の確認」の鍵は、対象のソースの dry-run だけができる（PR の確認に使う）。warnings には、止めずに知らせる注意（別のフォルダの同じファイル名・Markdown の節の途中の切れ目）が入る。\n\n実行は 1 回で最大 100 操作・25 秒前後（時間を使い切ると、新しい操作を始めずに残りを remaining に返す）。remaining が 0 になるまで同じ一式で呼び直す。最終同期のまとめ（ダッシュボードのソースの一覧）は、呼び出しをまたいだ同期の全体を数える。\n\n一式に無い文書の削除は、確認なしで消せる数を超えると 409 delete_limit_exceeded になる。消してよい external_id を confirmed_deletes に入れる。\n\n実行は API キーごとに 1 分 10 回まで（dry-run は数えない）。本文は 8 MiB まで。\n\n変更点（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）。","security":[{"ApiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64,"examples":["k9x2m4q7w1e5r8t3y6u0i2o4"]},"required":true,"name":"source_id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"examples":{"files":{"summary":"files で送る（パスの最初の階層がフォルダ、最後がファイル名になる）","value":{"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":{"summary":"items で送る（フォルダを ID で指定する、前からの形）","value":{"items":[{"external_id":"faq/shipping","filename":"送料.md","content":"# 送料\n\n全国一律で無料です。","content_type":"text/markdown"}],"dry_run":false}}},"schema":{"$ref":"#/components/schemas/SyncRequest"}}}},"responses":{"200":{"description":"計画と、実行した操作","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncResponse"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"},"502":{"$ref":"#/components/responses/BadGateway"}}}},"/knowledge/sources/{source_id}/uploads/{sha256}":{"put":{"operationId":"upload_knowledge_source_file","tags":["Sync"],"summary":"同期のファイルを上げる","description":"同期の計画（POST …/sync）が uploads_required で求めたファイルを 1 件ずつ上げる。計画が求めていないファイルは受けない。\n\n本文はファイルのバイト列そのまま。Content-Type に形式、Content-Length に大きさを付ける。中身の SHA-256 が URL と違えば 422 upload_mismatch。\n\n同じファイルを 2 度上げると、2 度目は 200 で何もしない。受け取ったファイルは 24 時間で消える（その間に実行の同期を呼ぶ）。","security":[{"ApiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64,"examples":["k9x2m4q7w1e5r8t3y6u0i2o4"]},"required":true,"name":"source_id","in":"path"},{"schema":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"ファイルの中身の SHA-256（16 進の小文字）","examples":["9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"]},"required":true,"description":"ファイルの中身の SHA-256（16 進の小文字）","name":"sha256","in":"path"}],"requestBody":{"required":true,"content":{"text/plain":{"schema":{"type":"string","format":"binary"}},"text/markdown":{"schema":{"type":"string","format":"binary"}},"application/json":{"schema":{"type":"string","format":"binary"}},"text/html":{"schema":{"type":"string","format":"binary"}},"text/csv":{"schema":{"type":"string","format":"binary"}},"application/pdf":{"schema":{"type":"string","format":"binary"}},"application/vnd.openxmlformats-officedocument.wordprocessingml.document":{"schema":{"type":"string","format":"binary"}}}},"responses":{"200":{"description":"受け取り済み（何もしない）","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadAccepted"}}}},"201":{"description":"受け取った","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadAccepted"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"411":{"$ref":"#/components/responses/LengthRequired"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/knowledge/folders":{"get":{"operationId":"list_knowledge_folders","tags":["Folders"],"summary":"フォルダの一覧","description":"既定のフォルダが先頭。is_global のフォルダはすべてのサイトから参照され、それ以外は sites に挙げたサイトだけが参照する","security":[{"ApiKey":[]}],"responses":{"200":{"description":"組織のフォルダ","content":{"application/json":{"schema":{"type":"object","properties":{"folders":{"type":"array","items":{"$ref":"#/components/schemas/Folder"}}},"required":["folders"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/knowledge/documents":{"get":{"operationId":"list_knowledge_documents","tags":["Documents"],"summary":"文書の一覧","description":"作成の新しい順。next_cursor が null でなければ、cursor に入れて次のページを取る","security":[{"ApiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":false,"name":"source_id","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":64},"required":false,"name":"folder_id","in":"query"},{"schema":{"type":"string","maxLength":512,"description":"source_id と一緒のときだけ指定できる"},"required":false,"description":"source_id と一緒のときだけ指定できる","name":"external_id","in":"query"},{"schema":{"type":"string","enum":["processing","pending","ready","error"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","maxLength":512,"description":"前の応答の next_cursor"},"required":false,"description":"前の応答の next_cursor","name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"文書の 1 ページ","content":{"application/json":{"schema":{"type":"object","properties":{"documents":{"type":"array","items":{"$ref":"#/components/schemas/Document"}},"next_cursor":{"type":["string","null"]}},"required":["documents","next_cursor"]}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}},"post":{"operationId":"create_knowledge_document","tags":["Documents"],"summary":"文書の作成","description":"テキストは JSON（content と content_type）、PDF などのリッチの形式は multipart/form-data（file）で送る。\n\nsource_id を省くと既定のソースに入る。同じ external_id で同じ内容をもう一度送ると、作らずに 200 で既存を返す。\n\n本文の上限は JSON 6 MiB・multipart 16 MiB。テキストは分割の上限が先に効き、実際は約 1.5 MiB まで。","security":[{"ApiKey":[]}],"requestBody":{"content":{"application/json":{"examples":{"text":{"summary":"テキストの文書を作る","value":{"external_id":"faq/shipping","filename":"送料.md","content":"# 送料\n\n全国一律で無料です。","content_type":"text/markdown"}}},"schema":{"$ref":"#/components/schemas/CreateDocument"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/CreateDocumentMultipart"}}}},"responses":{"200":{"description":"同じ外部 ID・同じ内容の文書が既にあった","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentAccepted"}}}},"202":{"description":"受け付けた。反映の状態は Location の文書で確かめる","headers":{"Location":{"description":"文書の URL","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentAccepted"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/knowledge/documents/{document_id}":{"get":{"operationId":"get_knowledge_document","tags":["Documents"],"summary":"文書の取得","description":"反映の状態は current_revision（公開中の版）と head_revision（最新の版）で確かめる。書き込みの応答の revision_id が current_revision.id になれば公開されている","security":[{"ApiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64,"examples":["p3l8n1b6v9c2x5z7m0q4w8e1"]},"required":true,"name":"document_id","in":"path"}],"responses":{"200":{"description":"文書","headers":{"ETag":{"description":"\"<版の ID>\"。If-Match にそのまま入れる","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}},"patch":{"operationId":"update_knowledge_document","tags":["Documents"],"summary":"文書の変更","description":"次の 3 つの組のうち 1 つだけを送る。組を混ぜると 400。\n\n- 本文：content と content_type、または edits（どちらか一方）。filename は任意。If-Match が必須（無ければ 428）\n\n- フォルダ：folder_id\n\n- ソース：source_id（同期のソースへ移すときは external_id も）","security":[{"ApiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64,"examples":["p3l8n1b6v9c2x5z7m0q4w8e1"]},"required":true,"name":"document_id","in":"path"},{"schema":{"type":"string","examples":["\"r7t2y5u8i1o4p6a9s3d0f2g5\""]},"required":false,"name":"if-match","in":"header","description":"GET で受け取った ETag（\"<版の ID>\"）。強い比較の 1 つの値だけを受ける"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchDocument"}}}},"responses":{"200":{"description":"フォルダ・ソースを変えた（文書を返す）。本文が同じで版を作らなかったときは DocumentAccepted（created: false）","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Document"},{"$ref":"#/components/schemas/DocumentAccepted"}]}}}},"202":{"description":"本文の変更を受け付けた","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentAccepted"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"412":{"$ref":"#/components/responses/PreconditionFailed"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/Unprocessable"},"428":{"$ref":"#/components/responses/PreconditionRequired"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"delete":{"operationId":"delete_knowledge_document","tags":["Documents"],"summary":"文書の削除","description":"削除を受け付け、実体は裏で消す。消した文書をもう一度消すと、削除の起票が保守の GC で消えるまでは already_deleted、その後は 404","security":[{"ApiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64,"examples":["p3l8n1b6v9c2x5z7m0q4w8e1"]},"required":true,"name":"document_id","in":"path"},{"schema":{"type":"string","examples":["\"r7t2y5u8i1o4p6a9s3d0f2g5\""]},"required":false,"name":"if-match","in":"header","description":"GET で受け取った ETag（\"<版の ID>\"）。強い比較の 1 つの値だけを受ける"}],"responses":{"202":{"description":"削除を受け付けた","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteResult"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"412":{"$ref":"#/components/responses/PreconditionFailed"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/knowledge/documents/{document_id}/content":{"get":{"operationId":"get_knowledge_document_content","tags":["Documents"],"summary":"文書の原本","description":"revision_id が無ければ公開中の版の原本を返す。公開中の版がまだ無い文書は 404（revision_id で版を指定する）","security":[{"ApiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64,"examples":["p3l8n1b6v9c2x5z7m0q4w8e1"]},"required":true,"name":"document_id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":64,"description":"無ければ公開中の版"},"required":false,"description":"無ければ公開中の版","name":"revision_id","in":"query"}],"responses":{"200":{"description":"原本のバイト列（Content-Disposition: attachment）","headers":{"ETag":{"description":"\"<版の ID>\"。If-Match にそのまま入れる","schema":{"type":"string"}}},"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/knowledge/documents/{document_id}/revisions":{"get":{"operationId":"list_knowledge_document_revisions","tags":["Documents"],"summary":"版の履歴","description":"新しい順。以前の版は 20 版まで原本が残り、復元できる","security":[{"ApiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64,"examples":["p3l8n1b6v9c2x5z7m0q4w8e1"]},"required":true,"name":"document_id","in":"path"}],"responses":{"200":{"description":"版の一覧","content":{"application/json":{"schema":{"type":"object","properties":{"revisions":{"type":"array","items":{"$ref":"#/components/schemas/Revision"}}},"required":["revisions"]}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/knowledge/sources/{source_id}/documents/{external_id}":{"put":{"operationId":"upsert_knowledge_document","tags":["Documents"],"summary":"外部 ID で文書を作成・更新する","description":"external_id は encodeURIComponent で符号化してパスに入れる（faq/shipping は faq%2Fshipping）。If-Match は任意で、指定すると head の版が違えば 412 になる","security":[{"ApiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64,"examples":["k9x2m4q7w1e5r8t3y6u0i2o4"]},"required":true,"name":"source_id","in":"path"},{"schema":{"type":"string","maxLength":512,"description":"外部 ID は、ソースの中で一意の文字列です。UTF-8 で 512 バイトまで、Unicode の NFC にそろえ、`/` で区切れます。空の区切り・`.`・`..`・区切りの前後の空白・制御文字・`\\` は使えません。例：`faq/shipping`、`渋谷店/営業時間.md`","examples":["faq%2Fshipping"]},"required":true,"description":"encodeURIComponent で符号化して送る（faq/shipping は faq%2Fshipping）。サーバーは復号した値を検査する","name":"external_id","in":"path"},{"schema":{"type":"string","examples":["\"r7t2y5u8i1o4p6a9s3d0f2g5\""]},"required":false,"name":"if-match","in":"header","description":"GET で受け取った ETag（\"<版の ID>\"）。強い比較の 1 つの値だけを受ける"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpsertDocument"}}}},"responses":{"200":{"description":"内容が同じで、何も変えなかった","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpsertResult"}}}},"202":{"description":"作成か更新を受け付けた","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpsertResult"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"412":{"$ref":"#/components/responses/PreconditionFailed"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/knowledge/documents/{document_id}/revisions/{revision_id}/restore":{"post":{"operationId":"restore_knowledge_document_revision","tags":["Documents"],"summary":"以前の版に戻す","description":"指定した版の内容で新しい版を作る。If-Match は任意","security":[{"ApiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64,"examples":["p3l8n1b6v9c2x5z7m0q4w8e1"]},"required":true,"name":"document_id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":64,"examples":["r7t2y5u8i1o4p6a9s3d0f2g5"]},"required":true,"name":"revision_id","in":"path"},{"schema":{"type":"string","examples":["\"r7t2y5u8i1o4p6a9s3d0f2g5\""]},"required":false,"name":"if-match","in":"header","description":"GET で受け取った ETag（\"<版の ID>\"）。強い比較の 1 つの値だけを受ける"}],"responses":{"200":{"description":"今の版と同じ内容で、版を作らなかった","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentAccepted"}}}},"202":{"description":"新しい版を受け付けた","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentAccepted"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"412":{"$ref":"#/components/responses/PreconditionFailed"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/knowledge/documents/{document_id}/retry":{"post":{"operationId":"retry_knowledge_document","tags":["Documents"],"summary":"取り込みに失敗した最新の版を取り込み直す","security":[{"ApiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64,"examples":["p3l8n1b6v9c2x5z7m0q4w8e1"]},"required":true,"name":"document_id","in":"path"}],"responses":{"202":{"description":"取り込み直しを受け付けた","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetryResult"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/knowledge/drafts":{"get":{"operationId":"list_knowledge_drafts","tags":["Drafts"],"summary":"下書きの一覧","description":"作成の新しい順。state の既定は open（未処理）。next_cursor が null でなければ、cursor に入れて次のページを取る","security":[{"ApiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["open","published","discarded"],"default":"open"},"required":false,"name":"state","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":64},"required":false,"name":"target_document_id","in":"query"},{"schema":{"type":"string","maxLength":512,"description":"前の応答の next_cursor"},"required":false,"description":"前の応答の next_cursor","name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"下書きの 1 ページ","content":{"application/json":{"schema":{"type":"object","properties":{"drafts":{"type":"array","items":{"$ref":"#/components/schemas/Draft"}},"next_cursor":{"type":["string","null"]}},"required":["drafts","next_cursor"]}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}},"post":{"operationId":"create_knowledge_draft","tags":["Drafts"],"summary":"下書きを作る","description":"AI エージェントの用途の API キーで、ナレッジの変更の提案を作る。公開はダッシュボードで人が行う（API からは公開できない）。\n\noperation ごとに必須の欄：create は filename・content・content_type、update は document_id と content（content_type と一緒に）か edits のどちらか一方、delete は document_id。\n\nedits は今の本文に当てた全文として保存する。base_revision_id を渡すと、今の版と違うときに 412 になる。\n\nevidence には、提案の根拠の会話と未回答の ID を入れる（組織に無い ID と、内部の会話の ID は 422）。公開すると根拠の未回答はアーカイブされる。\n\n未処理の下書きは組織で 100 件まで（409 draft_limit_exceeded）。本文は 6 MiB まで。","security":[{"ApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"examples":{"update_with_edits":{"summary":"既存の文書の一部を直す提案","value":{"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"]}}}},"schema":{"$ref":"#/components/schemas/CreateDraft"}}}},"responses":{"201":{"description":"作った下書き","headers":{"Location":{"description":"作った下書きの URL","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Draft"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"412":{"$ref":"#/components/responses/PreconditionFailed"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/knowledge/drafts/{draft_id}":{"get":{"operationId":"get_knowledge_draft","tags":["Drafts"],"summary":"下書きの取得","security":[{"ApiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64,"examples":["d4f7h1j3k6l9z2x5c8v0b3n6"]},"required":true,"name":"draft_id","in":"path"}],"responses":{"200":{"description":"下書き","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Draft"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}},"delete":{"operationId":"discard_knowledge_draft","tags":["Drafts"],"summary":"下書きを破棄する","description":"下書きを作った API キーだけが破棄できる。公開済み・破棄済みの下書きは 409 already_decided","security":[{"ApiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64,"examples":["d4f7h1j3k6l9z2x5c8v0b3n6"]},"required":true,"name":"draft_id","in":"path"}],"responses":{"200":{"description":"破棄した","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DiscardResult"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/knowledge/drafts/{draft_id}/content":{"get":{"operationId":"get_knowledge_draft_content","tags":["Drafts"],"summary":"下書きの提案の本文","description":"削除の下書きは本文を持たないので 404","security":[{"ApiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64,"examples":["d4f7h1j3k6l9z2x5c8v0b3n6"]},"required":true,"name":"draft_id","in":"path"}],"responses":{"200":{"description":"提案の本文（Content-Disposition: attachment）","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}},"webhooks":{}}