List Template Versions

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

Updated Sep 15, 2026

GET

/v1/studio/templates/{templateId}/versions

curl -X GET "https://api.orshot.com/v1/studio/templates/<TEMPLATE_ID>/versions" \
  -H "Authorization: Bearer <ORSHOT_API_KEY>"

const res = await fetch("https://api.orshot.com/v1/studio/templates/<TEMPLATE_ID>/versions", {
  method: "GET",
  headers: {
    Authorization: "Bearer <ORSHOT_API_KEY>",
  },
});

const data = await res.json();

$ch = curl_init("https://api.orshot.com/v1/studio/templates/<TEMPLATE_ID>/versions");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer <ORSHOT_API_KEY>",
]);

$data = json_decode(curl_exec($ch), true);
curl_close($ch);

require "net/http"
require "json"

uri = URI("https://api.orshot.com/v1/studio/templates/<TEMPLATE_ID>/versions")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer <ORSHOT_API_KEY>"

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)

Enterprise Only

Version history endpoints are available to first party clients like the Orshot MCP server and workspaces on the Enterprise plan. Checkout the Enterprise 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 for how versions are captured and kept.

Endpoint#

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#

JavaScript

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

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

Was this page helpful?

Ready to automate?

Start rendering images, PDFs and videos from your templates in under 2 minutes. Free plan, no credit card.

Get your API key

Image, PDF and video generation via API
Visual editor with AI and smart layouts
Zapier, Make, MCP and 50+ integrations
White-label embed for your own app
30 free credits — no credit card required