---
title: Manage template versions
canonical: "https://agentbarn.dev/guides/templates-and-skills/template-versions"
pubDate: "2026-08-29T00:00:00.000Z"
updatedDate: "2026-09-14T04:31:13.000Z"
author: Agent Barn
description: "Publish immutable Template versions from drafts, restore historical content, and explicitly update Agent pins."
tags: [Templates and Skills, Concept, "Template authors, Agent operators, Organization administrators, and platform administrators", lineage history, source scope, Template versions, draft, publish, restore, Agent pins]
categories: [Guides, Templates and Skills]
---

-   Templates and Skills
-   12–15 minutes

Template Versions let you improve an Agent definition without changing the configuration of Agents that already use it.

Every immutable Template Version snapshots its description, all eight Template artifacts, standalone and grouped Skill requirements, and the exact required Skill Version for every required Skill. Publishing a change creates another version instead of modifying the existing one, and each Agent remains pinned until someone explicitly moves it.

**Core principle**

Publishing a template version and applying a template version are separate operations. Publishing never automatically updates existing agents.

## Before you begin

You need:

-   Access to the organization containing the template
-   `template.read` permission to inspect templates and their history
-   `template.manage` permission to publish Organization Template versions
-   Permission to update an agent when changing its selected version
-   Lifecycle permission when applying a version to a running agent

Platform Templates require separate Platform Administrator permissions.

This guide assumes that you already understand how to create and edit templates. If not, begin with [Work with templates](/guides/templates-and-skills/templates).

## How template versioning works

A template lineage has a stable template key, such as `tpl-4f6a71b29c83`. The key identifies the template across its published versions, and the template name and key remain stable while the version number increases.

Each version is a complete snapshot containing the description, all eight Markdown artifacts, standalone and grouped Skill requirements, and the exact Skill Version required for every Skill:

-   Description
-   `SOUL.md`
-   `IDENTITY.md`
-   `USER.md`
-   `TOOLS.md`
-   `AGENTS.md`
-   `BOOT.md`
-   `BOOTSTRAP.md`
-   `HEARTBEAT.md`
-   Standalone and grouped required Skill rules with exact Skill Version pins

Versions are immutable, and agents pin them independently:

1.  **v1** Initial published snapshot
    -   Agent A
    -   Agent C
2.  **v2** Revised escalation behavior
    -   Agent B
3.  **v3** Latest published version
    -   New agents, when no version is specified

You cannot overwrite `v2` after it has been published. A new change becomes `v4`.

## Latest does not mean active

A template does not have one globally active version.

“Latest” means the highest published version available in a particular template lineage and source. “Active” refers to the exact version currently selected by an individual agent.

| Agent | Selected version | Latest version | Status |
| --- | --- | --- | --- |
| Support East | `v2` | `v4` | Update available |
| Support West | `v4` | `v4` | Latest |
| Support Test | `v3` | `v4` | Update available |

This lets you test a version with one agent before applying it to others.

## Understand the version sources

Agent Barn can show versions from several sources. Their version numbers are independent sequences.

**Platform Template**

-   v1
-   v2
-   v3
-   v4
-   v5

**Organization fork: _created from Platform v3_**

-   Org v1
-   Org v2
-   Org v3

**Agent Override: _created from Organization v3_**

-   v1
-   v2

| Source | Scope | Version sequence |
| --- | --- | --- |
| Built-in platform | Available globally | Platform-managed |
| Organization-owned | Available within one organization | Organization-managed |
| Organization fork | Organization copy of a Platform Template | Independent Organization sequence |
| Agent override | Available only to one agent | Independent Agent sequence |

An Organization fork created from Platform `v3` starts at Organization `v1`. It does not become Platform `v4`.

**Important**

Because version numbers can overlap, always check both the source label and the version number. “Built-in platform v2” and “Organization fork v2” may represent completely different snapshots.

## View version history

To inspect a template’s history:

1.  Open your organization.
2.  Go to **Templates**.
3.  Select the template.
4.  Open the version selector or history view.
5.  Select a version to preview its artifacts and frozen required Skills.

The newest versions appear first. Before applying a version, review:

-   Its source
-   Its version number
-   Its description
-   Each Markdown artifact
-   Each required Skill’s name, exact version such as `v3`, and whether it is standalone or in a requirement group
-   Whether the agent already uses that version
-   Whether a newer Platform or Organization version is available

These are frozen requirements from that Template Version, not the latest versions of those Skills.

| Skill | Required version | Requirement |
| --- | --- | --- |
| Jira | `v3` | Standalone |
| GitHub | `v2` | `code-host` group |

**Tip**

Search by template name, template key, or version when the history contains multiple similarly named entries.

## Publish a new Organization version

Direct `PATCH /{template_key}` is no longer the Template content-update endpoint. Save changes through the draft endpoint, then publish explicitly. Both Platform and Organization Templates have at most one mutable draft. Save the draft, then publish explicitly to create the next immutable version and clear the draft. Explicitly apply the published version to each Agent that should use it.

| Endpoint | Behavior |
| --- | --- |
| `POST /api/v1/organizations/{organization_id}/templates` | Create a new unpublished Template draft |
| `GET /api/v1/organizations/{organization_id}/templates/lineages` | List lineage summaries, including draft-only lineages |
| `GET /api/v1/organizations/{organization_id}/templates/{template_key}/versions` | Read published lineage versions |
| `GET /api/v1/organizations/{organization_id}/templates/{template_key}/draft` | Read the current draft |
| `POST /api/v1/organizations/{organization_id}/templates/{template_key}/draft` | Start or continue a draft |
| `POST /api/v1/organizations/{organization_id}/templates/{template_key}/draft?source_version=2` | Seed a draft from the selected published version |
| `PATCH /api/v1/organizations/{organization_id}/templates/{template_key}/draft` | Edit the unpublished draft |
| `DELETE /api/v1/organizations/{organization_id}/templates/{template_key}/draft` | Discard the draft |
| `POST /api/v1/organizations/{organization_id}/templates/{template_key}/draft/publish` | Publish the next immutable version |
| `POST /api/v1/organizations/{organization_id}/templates/{template_key}/platform-update` | Apply the separate Platform Update operation |

## Choose the correct version action

Different actions have different effects.

| Action | Creates a version? | Moves an agent? | Changes previous history? |
| --- | --- | --- | --- |
| Publish an Organization change | Yes | No | No |
| Apply a version to one agent | No | Yes | No |
| Roll back one agent | No | Yes | No |
| Republish historical content | Yes | No | No |
| Apply a Platform update to a fork | Yes | No | No |
| Delete a custom template lineage | No | Not allowed while in use | Deletes its complete history |

Use **Apply** when you want one agent to use an existing version. Publish a new version when you want to create a new reusable snapshot.

## Test and release a new version

Treat template changes like application releases.

1.  **Publish next version** Publishing a saved Organization draft creates the next immutable version
    
2.  **Apply to a stopped test agent** Nothing moves until you apply it
    
3.  **Verify Skills and credentials** The exact version being applied is validated
    
4.  **Start the agent and run a test conversation** Exercise representative tasks
    
5.  **Review health, activity, and logs** Confirm the behavior change and look for regressions
    
6.  **Apply to a small group of agents** Monitor the canary group
    
7.  **Roll out to the remaining agents** Each agent moves only when you apply the version
    

Recommended steps:

1.  Publish the next template version.
2.  Preview the complete snapshot.
3.  Confirm that its required Skills are installed.
4.  Apply it to a stopped test agent.
5.  Start the agent.
6.  Run representative conversations or tasks.
7.  Review agent health and logs.
8.  Apply it to a small set of production agents.
9.  Monitor the canary agents.
10.  Roll it out to the remaining agents.

There is no automatic rollout when a version is published.

## Apply a version to an agent

To move an agent to another published version:

1.  Open the agent.
2.  Go to **Configuration**.
3.  Open the template selection interface.
4.  Find the required template and source.
5.  Select the exact version.
6.  Preview its artifacts and exact required Skill Versions.
7.  Select **Apply** or **Apply & Restart**.

For a stopped Agent, **Apply** changes the pinned version and leaves the Agent stopped. For a running Agent, **Apply & Restart** stops the Agent, changes its selected version, and starts it again. Applying requires the selected version’s exact Skill Version requirements to be available and satisfied.

**Why a restart is required**

Agent Barn generates runtime configuration when an agent starts. A running process must restart before it can load a newly selected template version.

### Apply a version with the API

The selection request identifies both the source and exact version:

```
POST /api/v1/organizations/{organization_id}/agents/{agent_id}/configuration/select
Content-Type: application/json
```

```
{
  "selection_type": "organization",
  "template_key": "tpl-4f6a71b29c83",
  "template_version": 4,
  "expected_agent_updated_at": "2026-08-29T09:40:12Z"
}
```

The `selection_type`, `template_key`, and `template_version` select the Template Version only. Selecting an older Template Version does not select the latest versions of its required Skills.

Valid selection types include `platform`, `organization`, and `override`. The explicit selection type prevents ambiguity when Platform and Organization sources have the same template key and version number.

The `expected_agent_updated_at` value provides optimistic concurrency protection. If another user changed the agent after you loaded it, refresh the agent and retry with its current timestamp.

**Warning**

The agent must be stopped before making this API request. In the web interface, use **Apply & Restart** for a running agent.

## Roll back one agent

Rolling back an agent does not create another template version. It changes the agent’s pin to a previously published snapshot.

1.  Open the affected agent.
2.  Go to **Configuration**.
3.  Open the template selector.
4.  Select the previous source and version.
5.  Preview the complete snapshot.
6.  Confirm that its exact required Skill Versions remain available and satisfied.
7.  Select **Apply** or **Apply & Restart**.
8.  Verify the agent after it starts.

Only the selected agent moves. Other agents remain on their existing versions.

### Before rollback

```
Agent A ── v4
Agent B ── v4
Agent C ── v3
```

### After rolling back Agent A

```
Agent A ── v3
Agent B ── v4
Agent C ── v3
```

This is the fastest way to reverse a problematic rollout, because it reuses an existing immutable snapshot and its exact Skill requirements.

## Restore historical content as a draft

To restore historical content, choose the intended published version and use the restore-as-draft action. Review or edit that draft, then publish it as the next version. The historical version remains unchanged. An existing draft must be discarded before restoring a different published source; an explicit source selection conflicts while a draft already exists. Restoring reusable content is separate from rolling an Agent back by selecting an existing immutable version.

## Restore a Platform Template version

Platform Templates use one mutable draft per lineage. Publishing a Platform draft creates the next immutable Template Version and clears that draft; Organization Templates use the same separate draft-save and explicit-publish workflow.

A Platform Administrator can:

1.  Open the Platform Template’s version history.
2.  Select a historical version.
3.  Choose **Restore vN as draft**.
4.  Review or edit the draft.
5.  Publish the draft.

Restoring an older Platform Template Version seeds a new draft; it never mutates or reactivates that historical version. Publishing creates the next Platform version. Neither workflow changes existing Agent pins automatically.

**Platform Administrator**

Only one draft can exist for a Platform Template lineage. Continue or discard the existing draft before restoring another historical version.

## Manage required Skills across versions

Required Skill rules belong to the individual template version. A newer version can:

-   Add a required Skill
-   Remove a required Skill
-   Change an “at least one of” Skill group
-   Keep the same artifacts but change its Skill requirements

Agent Barn validates the requirements of the exact version being applied. Every standalone Skill must be pinned to its exact required version, while a group passes when at least one member is assigned at that member’s exact required version. The right Skill at the wrong version does not satisfy the requirement.

Before applying a version:

1.  Inspect its required Skills.
2.  Confirm that the organization has access to them.
3.  Confirm that required provider credentials are configured.
4.  Resolve missing requirements.
5.  Apply the version.

Publishing a newer Skill Version never changes existing Template snapshots or Agent pins. Deleting a Skill Version is blocked while a Template Version references it. A Skill cannot be both standalone and grouped, or belong to multiple groups, in one Template Version. The Apply action is blocked when requirements are unavailable or incorrectly pinned.

## Understand placeholders and runtime rendering

Template placeholders are resolved when an agent starts, not when the template is published.

That means two agents can use the same immutable template version while receiving different rendered values, based on their names, organization details, or start context. The stored template version remains unchanged.

When you apply a version to a running agent, restart it so Agent Barn can render and generate its new runtime configuration.

## Update an Organization fork from Platform

A Platform update is different from publishing a normal Organization edit. Applying a Platform update to an Organization fork:

-   Copies the latest complete Platform snapshot
-   Copies its exact required Skill Versions and grouped requirements
-   Creates the next Organization version
-   Replaces the fork’s Organization customizations
-   Advances the fork’s Platform baseline
-   Leaves all existing agent pins unchanged

It is a replacement operation, not a three-way merge.

```
POST /api/v1/organizations/{organization_id}/templates/{template_key}/platform-update
```

**Warning**

Review the fork before applying a Platform update. Organization-specific artifacts and Skill requirements are replaced by the latest Platform snapshot.

See [Manage forks and updates](/guides/templates-and-skills/forks-and-updates) for the complete workflow.

## Template deletion boundary

Individual published Template Versions cannot be deleted.

For an Organization-owned custom template, you can delete the entire lineage only when no live agent uses it:

```
DELETE /api/v1/organizations/{organization_id}/templates/{template_key}
```

Deleting the lineage permanently removes all of its versions.

You cannot delete:

-   One individual shared-template version
-   A built-in Platform Template
-   An Organization fork
-   A custom lineage still used by a non-deleted agent

Publishing a new version is allowed while older versions are in use. Live use blocks deletion of the lineage, not version creation. Do not confuse Template deletion with separately supported, reference-protected deletion of individual Skill Versions.

## API reference

### List lineage versions

```
GET /api/v1/organizations/{organization_id}/templates/{template_key}/versions
```

This endpoint returns the lineage's published history, newest first. Once the Organization has published any version for that key, the response contains its Organization versions. Before an Organization version exists, it falls back to the Platform lineage. An unpublished Organization draft is not a published version and does not by itself replace that fallback.

This endpoint does not combine Platform and Organization histories. The Agent configuration selector uses a separate shared-version lookup so it can offer both sources deliberately. Use the Agent configuration response's shared versions when building that selector; do not use the lineage-history endpoint as a complete list of its source options.

Version numbers are local to their source. Keep source labels when presenting a selected Agent version, even though an individual lineage-history response follows one scope.

| Situation | Published history returned |
| --- | --- |
| No published Organization version for the key | Platform history, when available |
| Organization has published a fork | That Organization's version sequence |
| Organization-owned custom Template | That Organization's version sequence |
| Agent configuration selection | Separate shared-version data can offer Platform and Organization sources |

Check fields such as:

-   `version`
-   `organization_id`
-   `template_source`
-   `forked_from_platform_template_id`
-   `fork_baseline_platform_version`
-   Creation and update timestamps

Do not identify a version using its number alone.

### Save a draft and publish an Organization version

```
PATCH /api/v1/organizations/{organization_id}/templates/{template_key}/draft
```

```
{
  "description": "Improve escalation behavior for urgent requests.",
  "agents_md": "# AGENTS.md\n\nEscalate urgent requests to the on-call operator.",
  "required_skill_ids": ["{standalone_skill_id}"],
  "required_skill_groups": [
    { "group_key": "code-host", "skill_ids": ["{github_skill_id}", "{bitbucket_skill_id}"] }
  ],
  "required_skill_versions": {
    "{standalone_skill_id}": 3,
    "{github_skill_id}": 2,
    "{bitbucket_skill_id}": 5
  }
}
```

```
POST /api/v1/organizations/{organization_id}/templates/{template_key}/draft/publish
```

Saving retains unpublished work. Publishing creates the next immutable version and clears the draft. Required Skill selections retain exact version pins and standalone or group requirements. Existing Agent pins do not move.

### Apply a version to an agent

```
POST /api/v1/organizations/{organization_id}/agents/{agent_id}/configuration/select
```

Example request:

```
{
  "selection_type": "platform",
  "template_key": "tpl-4f6a71b29c83",
  "template_version": 5,
  "expected_agent_updated_at": "2026-08-29T09:40:12Z"
}
```

### Apply the latest Platform snapshot to a fork

```
POST /api/v1/organizations/{organization_id}/templates/{template_key}/platform-update
```

This creates the next Organization version, but does not repin agents.

## Troubleshooting

### I published a version, but my agent still uses the old content

Expected: publishing never repins

Publishing does not move existing agents. Open the agent’s configuration and apply the new version.

Restart the agent if it is currently running.

### Two entries have the same version number

Sequences are independent

They may come from different sources. Check whether each entry is a Built-in platform version, Organization-owned version, Organization fork, or Agent override.

Version sequences are independent.

### Apply is blocked by missing Skills

The exact version is validated

The selected version requires Skills that are not available to the organization. Install or configure the required Skills, then retry.

### The Agent has the required Skill at the wrong version

Template requirements use exact pins

Repin the Skill to the exact version shown in the selected Template Version. A matching Skill lineage alone does not satisfy a standalone requirement or group member.

### A requested Skill Version is unpublished or missing

Requirements must reference published snapshots

Publish or restore an available Skill Version, then select or repin it deliberately. A Template Version cannot be applied until every required exact Skill Version is available.

### A retained Skill kept its previous pin

Expected: omitted requirements preserve pins

Retained requirements keep their exact Skill Version pins unless you supply `required_skill_versions` for those selected Skills. Repin intentionally instead of expecting a newer Skill Version to replace the snapshot.

### The agent changed while I was applying a version

Optimistic concurrency

The optimistic concurrency check rejected a stale request. Refresh the agent, review the latest configuration, and retry using its current `updated_at` value.

### I cannot apply a version through the API

The agent must be stopped

The agent must be stopped before the selection request. Stop it, apply the version, and start it again.

In the web interface, use **Apply & Restart** when that action is available.

### I cannot delete an old version

Shared versions are immutable

Shared-template versions are immutable and cannot be individually deleted. Old versions remain available for auditing and rollback.

You can delete an entire Organization-owned custom lineage only when no live agent uses it.

### Restoring historical content produced a mixed snapshot

Omitted fields inherit from latest

A partial Organization update inherits omitted fields from the current latest version. To reproduce a historical version exactly, submit all eight artifacts, its description, and its complete required Skill rules.

### My Organization fork lost its custom changes

Platform update replaces the snapshot

Applying a Platform update replaces the Organization fork snapshot; it does not merge customizations.

Select an older Organization version to recover an agent, or publish another Organization version containing the required customizations.

## Recommended operating practices

-   Treat every version as a release artifact
-   Use descriptions that explain the behavioral change
-   Test new versions with a dedicated agent
-   Roll out to a small canary group first
-   Review required Skills before applying a version
-   Record both the version number and its source
-   Keep agents pinned until their update is intentional
-   Roll back by selecting a known-good version
-   Republish historical content only when it must become the new latest version
-   Review Organization customizations before applying Platform updates

## Next steps

Continue to [Manage forks and updates](/guides/templates-and-skills/forks-and-updates) to learn how Organization forks track Platform changes, and how to safely adopt a new Platform snapshot.

-   [Work with templates](/guides/templates-and-skills/templates)
-   [Manage Skill versions](/guides/templates-and-skills/skill-versions)
-   [Use Agent overrides](/guides/templates-and-skills/agent-overrides)
-   [Configure an Agent](/guides/agents/configuration)
-   [Review Agent health and logs](/guides/agents/health-and-logs)