送った一式と、ソースの今の文書を 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）。

{
  "files": [
    {
      "path": "渋谷店/営業時間.md"
    }
  ],
  "client": {
    "run_url": "https://github.com/example/knowledge/actions/runs/1"
  }
}