Version control for AI agent prompts in production: Sume Formats

Sume versions the recipe, not the call: every edit to a Format bumps its version, and every run receipt records format.version, the version that actually ran. A run cannot be pinned to an earlier version, and there is no rollback API, so log the version of every run and keep your own copy of the files you commit.

A Format is a saved recipe (a SKILL.md plus reference files) that your backend calls by name; What is a Sume Format? covers the basics. The facts below come from Format API, Runs and results, and Editing a Format package, read on 2026-09-26.

What creates a new Format version?

Any edit: version bumps on every edit, whether the Format was changed in the Agents dashboard, in chat, or over the Contents API. A Contents write answers with commit.tree.sha, the Format's new package identity (the same value the Format record reports as package_sha), and version, the display counter the dashboard shows.

A single-file PUT is one commit. A PUT at the package root with a files list writes all of them as one commit, one version bump, and one new package_sha, so related changes can ship as a single version.

How do I know which version made a video?

Read format.version on the run receipt. It is the Format version that actually ran, and later edits do not change it. The terminal webhook carries the same receipt, so you can store the version when the result arrives.

Do edits change runs that are already running?

No. Editing a package is authoring, not execution, and it never touches a run already in flight: each run reads the package it started with.

The receipt's format object carries id, slug, title, and version, but not the package sha. If you need to know exactly which files made a video, record version next to commit.tree.sha each time you commit.

Can I pin a run to a version or roll back an edit?

No to both, today. The run request has no version field, and an unknown top-level field is refused with 400 unknown_parameter. Reverting, blame, and history browsing are not part of the Contents API yet, and there is no public git endpoint or clone URL.

• To undo an edit, commit the earlier file bodies again. That is a new commit and a new version, not the old one back.
• Keep the files you commit in your own repository, since the API will not show you an older version's contents.
• If production needs a fixed recipe while you iterate, keep drafts in a second Format with its own slug and call only the stable one from production.
• Guard concurrent edits with If-Match and the current package_sha, as in Edit Sume Format files with If-Match.

How do versions interact with idempotency keys?

A replay with the same Idempotency-Key and the same body returns the original run, with no second run and no second charge, so it still shows the version that ran the first time. Keys are scoped to one Format.

The docs recommend deriving the key from the thing being made, such as your order id plus a version you bump when you deliberately want a re-run. After you edit a Format and want the new recipe applied, bump that part of the key. More on key design: idempotency keys for AI video APIs.