# List Template Versions

> The version timeline of a studio template, with what each version changed and whether your plan can restore it

- **URL**: https://orshot.com/docs/api-reference/template-versions-list

---

Version history endpoints are available to first party clients like the
[Orshot MCP server](https://orshot.com/agents) and workspaces on the
Enterprise plan. Checkout the [Enterprise
Pricing](https://orshot.com/pricing) to get access.

Every design write on a studio template keeps the state it replaced. This endpoint returns that timeline, newest first: one row per editing session, explicit saves, API and agent writes, named versions, and restore steps. See [Version history](https://orshot.com/docs/orshot-studio/version-history) for how versions are captured and kept.

## Endpoint

```markdown tab="Endpoint"
https://api.orshot.com/v1/studio/templates/:templateId/versions
```

## URL Parameters

| Parameter    | Type    | Required | Description               |
| ------------ | ------- | -------- | ------------------------- |
| `templateId` | Integer | Yes      | ID of the studio template |

## Request

**Request**
```js
await fetch("https://api.orshot.com/v1/studio/templates/12345/versions", {
  headers: { Authorization: "Bearer <ORSHOT_API_KEY>" },
});
```

**Response**
```json
{
  "template_id": 12345,
  "total": 6,
  "named": 1,
  "hidden": 0,
  "plan": { "restore": true, "visible": 15, "restorable": 12, "named": 6 },
  "current": {
    "updated_at": "2026-09-15T10:37:45.459+00:00",
    "current_version": "95b4cf5f-0adb-4f13-a89f-703a3065fad7",
    "page_count": 3,
    "previews": ["https://storage.orshot.com/.../p1.png", "", ""]
  },
  "versions": [
    {
      "id": 51,
      "number": null,
      "kind": "checkpoint",
      "source": "studio",
      "actor_type": "user",
      "actor_id": "fc68…",
      "label": null,
      "protected": false,
      "ref_version_id": null,
      "row_updated_at": "2026-09-15T10:19:42.403+00:00",
      "page_count": 3,
      "previews": ["https://storage.orshot.com/.../p1.png", "", ""],
      "meta": { "summary": { "text": 1, "media": 0, "changed_pages": [{ "index": 0, "id": "p1", "name": "Cover" }] } },
      "restorable": true,
      "created_at": "2026-09-15T10:37:46.589+00:00"
    },
    {
      "id": 48,
      "number": 9,
      "kind": "session",
      "source": "studio",
      "label": null,
      "protected": false,
      "restorable": true,
      "row_updated_at": "2026-09-15T10:37:45.459+00:00",
      "created_at": "2026-09-15T11:08:41.120+00:00"
    },
    {
      "id": 10,
      "number": 7,
      "kind": "named",
      "source": "agent:claude",
      "label": "Approved for launch",
      "protected": true,
      "restorable": true
    },
    {
      "id": 7,
      "number": 4,
      "kind": "restored",
      "source": "restore",
      "ref_version_id": 3,
      "restorable": false
    }
  ]
}
```

## Response Fields

| Field                   | Type    | Description                                                                                                           |
| ----------------------- | ------- | --------------------------------------------------------------------------------------------------------------------- |
| `versions[].id`         | Integer | Version id, used by every other version endpoint                                                                      |
| `versions[].number`     | Integer | Position on the timeline (`v9`). `null` for the in-session checkpoint                                                |
| `versions[].kind`       | String  | `session`, `checkpoint`, `manual`, `named`, `api`, `restore` or `restored` (see below)                               |
| `versions[].source`     | String  | Who wrote the state that replaced (or produced) this one: `studio`, `studio-embed`, `api`, `agent:<client>`, `apply-render`, `variants`, `restore` |
| `versions[].label`      | String  | The name given to a named version, otherwise `null`                                                                   |
| `versions[].protected`  | Boolean | Named versions are never pruned                                                                                       |
| `versions[].ref_version_id` | Integer | For `restore` and `restored` rows: the version that was put back                                                  |
| `versions[].row_updated_at` | String | When the design in this version was last edited                                                                    |
| `versions[].previews`   | Array   | One thumbnail URL per page in page order (`""` when a page had none)                                                  |
| `versions[].meta.summary` | Object | What changed compared with the previous version: `pages`, `elements`, `text`, `media`, `canvas`, `name`, `changed_pages` |
| `versions[].restorable` | Boolean | Whether your plan may restore or copy this version                                                                   |
| `plan`                  | Object  | `restore` (restoring unlocked), `visible` (rows shown), `restorable` (newest N that can be restored), `named` (slots) |
| `hidden`                | Integer | Rows kept but not shown on the current plan                                                                           |
| `current`               | Object  | The live template's `updated_at`, `current_version`, page count and previews                                          |

### Version kinds

| Kind         | Meaning                                                                                                    |
| ------------ | ---------------------------------------------------------------------------------------------------------- |
| `session`    | The design as it was when an editing session ended (30 minutes without a write, or a different writer)     |
| `checkpoint` | Rolling in-session safety copy, refreshed every 10 minutes, replaced when the session closes                |
| `manual`     | An explicit Save in the studio                                                                             |
| `named`      | A version saved under a name; never pruned                                                                 |
| `api`        | The design before an API or agent write replaced it                                                        |
| `restore`    | The live design right before a restore replaced it                                                         |
| `restored`   | The design a restore produced; `ref_version_id` says which version was put back                            |

## Error Responses

| Status Code | Code                  | Description                                            |
| ----------- | --------------------- | ------------------------------------------------------ |
| 400         | `invalid_template_id` | `templateId` is not a numeric id                       |
| 403         | `enterprise_required` | API key without the Enterprise version history feature |
| 404         | —                     | Template not found in your workspace                   |
| 500         | `LIST_FAILED`         | Server-side error                                      |