Versioning your team (API)

How to update a published team, manage version drafts, and roll back regressions — all via the API.

Authenticate every request with your API key:

Authorization: Bearer <your-api-key>

All endpoints are prefixed with /api. The base URL is your Envelope instance origin (e.g. https://openenvelope.org/api).

How versioning works

Every published team has a stable id and slug that never change across versions. Deployers install once using that identifier and keep pointing at it forever. When you publish an update, they are not migrated automatically — they continue running on their installed version until they choose to upgrade.

Updates flow through a draft cycle:

1. Create a version draft from the published team — POST /templates/:id/new-version
2. Edit the draft freely — PATCH /templates/:draftId
3. Publish the draft — POST /templates/:draftId/publish

Envelope merges the draft into the published parent, increments the version number, and deletes the draft. The parent's id and slug remain unchanged. You can only have one active version draft per team at a time.

Version numbering

Versions follow semver (MAJOR.MINOR.PATCH).

Deployers with existing installs receive notifications on MAJOR bumps. When in doubt, bump MAJOR.

1. Create a version draft

POST /templates/:id/publish

Wait — first create the draft:

POST /templates/:id/new-version

No request body. :id must be a published template. Calling this on a draft returns 409.

Response: 201 Created

{
  "id": "tpl_draft456",
  "slug": "support-triage-v2",
  "parentTemplateId": "tpl_abc123",
  "version": 2,
  "status": "draft"
}

The draft inherits all content from the published parent — name, description, agents, prompts, pricing, access policy. Store the draft id. All edits and the eventual publish use this ID, not the parent's.

2. Edit the draft

PATCH /templates/:draftId

{
  "definition": { ... },
  "changeLog": "v2: Added escalation specialist for P1 tickets."
}

The published parent is completely unaffected while you work. Edit prompts, restructure the agent hierarchy, update pricing — none of it touches live installs.

Attempting to PATCH the published parent directly returns 409 Conflict.

3. Publish the update

POST /templates/:draftId/publish

{
  "changeLog": "v2: Added escalation specialist. P1 detection improved with urgency classifier."
}

Always include a changeLog string. It appears in every deployer's version history and is the primary signal they use to decide whether to upgrade.

Envelope:

1. Copies the draft's content into the published parent
2. Increments the parent's version number
3. Deletes the draft
4. Leaves the parent's id and slug unchanged

Response: Returns the updated parent template with the new version number.

Existing installs continue running on their previous version. They are never updated automatically.

4. Roll back to a previous version

If a new version introduces a regression, restore any prior version from its snapshot:

POST /templates/:id/rollback

{
  "version": 1
}

:id is the published parent template ID. version is the version number to restore.

Response: 201 Created — returns a new draft pre-loaded with that version's full definition.

The published parent keeps running while you review the restored draft. Adjust it if needed, then publish it as you would any update. This is non-destructive — rolling back never overwrites the live team.

Snapshots are only stored for versions published after this feature was introduced. Older versions cannot be restored.

5. Archive a team

Archiving delists the team from the Library and blocks new installs. Existing installs keep running until the deployer removes them.

POST /templates/:id/archive

No request body. :id must be a published template. Archiving a draft returns 409 — delete drafts instead.

Response: Returns the updated template with status: "archived".

Use archiving when you want to retire a team that still has active installs. You cannot delete a published template with active installs.

6. Delete a team

DELETE /templates/:id

Permanently removes the template. No response body — returns 204 No Content on success.

Only available for:

• Draft templates (any install count)
• Published or archived templates with zero active installs

Attempting to delete a template with active installs returns 409 with "canArchive": true. Archive first, wait for deployers to remove their installs, then delete.

Lifecycle reference

Impact on installs

Frequently asked questions

Can I run an older version of AI agents after publishing a new one? Existing installs continue running the version they were installed from. New installs always use the current published version. To run an old version again, create a new install pinned to that version via the API.

What happens to in-progress runs when I publish a new version? In-progress runs complete on the version they started on. New runs triggered after publishing use the new version automatically. There's no forced cutover — no active workflow is interrupted.

Is there a limit to how many versions a team can have? There's no hard cap on draft or published versions. Archived versions count toward storage but don't affect run limits. Use archive rather than delete to preserve history without cluttering the active library.

Can I compare two versions of an agent spec? Yes — the spec exports as plain JSON, so you can diff any two versions using standard tools: git diff, VS Code's diff view, or any JSON diffing tool. Storing specs in Git makes version comparison straightforward.