Commit several Sume Format files in one PUT: a change set
PUT a files list to a Sume Format's contents URL and it is one commit with one version bump. Files you do not name stay as they are. Existing paths need a sha.
PUT /v1/formats/{handle}/{slug}/contents with a files list writes all the named files as one commit, with one version increase and one new package_sha. The list is a change set, not the package: a path that the Format holds and that the body does not name stays as it is, so editing two of twelve files never removes the other ten. Existing paths need their current per-file sha. Source: Editing a Format package, read 2026-10-06.
Which guard fires when?
Two levels of sha, two kinds of conflict.
| Guard | Where | Conflict code |
|---|---|---|
Per-file sha | Inside each files entry | format_content_sha_mismatch; missing gives format_content_sha_required |
If-Match package sha | Request header | format_package_sha_mismatch |
What are the file rules?
Only .md, .json, .yaml, .yml and .txt files are accepted, with a 100 MiB limit and at most 1000 paths per batch. On a package conflict, error.details.package_sha holds the current value, so you can re-read and retry.
Sources
Related posts
More in Formats
- Create a Sume Format over the API: auto_init and the first package sha
POST /v1/formats with auto_init (default true) commits a minimal SKILL.md and returns package_sha, contents_url and vanity_invoke_url. Keep all three.
- enum and const in a Sume output schema: a status that cannot drift
Use enum and const in a Sume output_schema to pin a status field to values your publisher expects, since oneOf and allOf are rejected. Examples that pass.
- A failed Format run webhook still has the receipt: salvage artifacts
When a Sume Format run fails, the webhook has status ERROR but payload is still the full receipt, with artifacts and output_error. Read them before you retry.
- Format io is null on older Formats: pick by your own input kind
On Sume's Format list, the io block is null for Formats saved before the field existed. Do not route on it alone; read input_kind and output_kind when present.
Written by Sume