sync_push_batch
Push MANY files into the primary vault in ONE call. Use this instead of looping sync_push whenever you have more than a couple of changed paths — the cost of sync_push is round trips, not bytes. Per-item semantics are identical to sync_push (Layer 3 base_sha CAS, superseded contract, content_b64 WAF fallback). Partial success is normal and returns HTTP 200: read results[] and match entries by path, NOT by position. A conflict result always carries remote_sha + conflict_reason so you can go straight to sync_merge. Request-level failures (duplicate paths in one batch, idempotency key reused with a different payload, >200 items, >4MB) return 4xx and apply NOTHING. Each item MUST carry content_sha (SHA1 hex of the decoded body, same algorithm as git_sha) — it powers both the integrity check and the retry-safe skipped_identical result. Newly created .md items may carry dedup_candidates (same merge/skip/store advisory as sync_push); a batch creating more than 10 new files skips the check entirely and reports dedup_skipped: "bulk".
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | Up to 200 push items, 4MB total, one entry per unique path. Duplicate paths reject the whole batch. | |
| device_id | No | Optional batch-level device identifier; per-item device_id overrides it. | |
| idempotency_key | Yes | REQUIRED. Opaque client-generated UUID, one per batch ATTEMPT-SET: reuse the same key when retrying the same items after a timeout (the server replays the stored results instead of re-applying), and generate a NEW key whenever the items change. Reusing a key with a different payload is a 400 collision, never a silent replay. Do not derive it from paths or content. | |
| supports_superseded | No | Same capability opt-in as sync_push, applied to every item in the batch. |