Versions & Labels

A version is a snapshot, a label is a pointer

A prompt template accumulates two different kinds of object as you work on it. A version is a saved snapshot of the template, created the moment you commit: the action that freezes your current draft into a permanent, numbered step. A label is a named pointer that sits on top of one version and marks it as the one you actually want live right now. Promoting and rolling back both come down to reassigning a label rather than editing the template again, which is why your application can fetch by label instead of hardcoding a version name.

Versions

Until you commit, your edits are a draft: an in-progress, uncommitted state that isn’t a version yet. Each version:

• Gets a name the platform assigns automatically, v1, v2, v3 and so on, matching the pattern ^v\d+$. You don’t type a version name yourself
• Is unique within its template: the same template can’t have two versions sharing a name
• Can be marked the template’s default, the version a fetch falls back to when nothing more specific points at one. Only one version is the default at a time

Saving a new version as default automatically takes it off whichever version had it before, without you touching that older version directly.

To commit a draft and set a default, see Commit & compare versions.

Labels

A label is a pointer, not a copy. It’s defined once for your workspace and reused across every template there. On any one template it sits on exactly one version at a time, and assigning it to a different version removes it from whichever version it was on before.

• System labels: Production, Staging, and Development are created automatically and available in every workspace. The names are reserved in every workspace too, so nobody can create a second label called Production (or Staging, or Development)
• Custom labels: create your own, one per region or per customer tier for example. The name is claimed once across your organization and workspace

For fetching and reassigning labels from your own code, see the SDK & API reference.

Promoting and rolling back

flowchart TD
accTitle: Commits build a version chain on the support-agent template, labels point at one version each
accDescr: The support-agent template already has v1, v2, and v3 in its version chain. The current draft is not part of that chain yet, committing it would add the next version after v3. The Production, Staging, and Development labels each point at exactly one version, and moving a label just redraws its arrow, it does not touch the chain.
subgraph CHAIN["support-agent template"]
  V1["v1"] -->|commit| V2["v2"] -->|commit| V3["v3"]
end
Dr["Draft · in-progress edit"] -->|commit| V3
subgraph LABELS["Labels"]
  Prod["Production"]
  Stg["Staging"]
  Dev["Development"]
end
Prod -.-> V2
Stg -.-> V3
Dev -.-> V1

The chain only grows one commit at a time.

Say you edit the support-agent template’s system message. That’s a draft, invisible to anything reading by label. You commit it and it becomes v4. You point Staging at v4 to try it out, and once it looks good you move Production there too. A week later it regresses, so you point Production back at v2. The chain still has v4 in it, you’ve just moved a pointer.

Keep exploring