Refresh last year's holiday Format: one commit, rerun with v2 keys

To refresh a Format for a new season, commit the changed files in one Contents API call, then re-run your SKUs with new Idempotency-Key values such as ...-v2. A commit bumps the Format version by one, and each run reads the package it started with, so finished runs are not changed.

The edit

PUT /v1/formats/{handle}/{slug}/contents takes a files list and writes it as one commit with one version increase and one new package_sha. files is a change set: paths you do not name stay as they are. Each existing path needs its current sha, and a stale one commits nothing.

Add If-Match with the package sha you last read, so a teammate's edit made after your read causes 409 format_package_sha_mismatch instead of a silent overlap.

curl -sS -X PUT "https://api.sume.com/v1/formats/acme/holiday/contents" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "If-Match: $PACKAGE_SHA" \
  -H "Content-Type: application/json" \
  -d '{"message": "2026 holiday offer copy",
       "files": [{"path": "references/offer.md",
                  "content": "<base64>", "sha": "<current file sha>"}]}'

The rerun

Idempotency keys should include a version you bump only when you want a re-run. If you reuse last year's key with the same body you get the original receipt back and no new run, and a different body with that key is 409 idempotency_conflict.

Order of operations

Read the whole package with recursive=true first, so you hold every file sha and the package sha. Edit locally, then commit once with If-Match. Run one SKU on the new version and read format.version on its receipt to confirm the edit took effect.

Only then queue the batch with fresh keys. If you queue first and edit second, items that start after the commit read the new package, so one batch can mix old and new recipes.

If you cannot rerun everything, rank the SKUs by what you will promote hardest this season and queue those first. A queue accepts up to 100 items, so a larger catalog becomes several queues, each with its own idempotency key.

Tradeoffs

The Contents API has no revert, blame or history browsing, so keep your own copy of the files in git before you edit. If the old season's look must stay reproducible, consider a second slug for the new season instead of editing in place.