Update Template

Update template metadata, dimensions or complete page structure

Updated Aug 30, 2026

PATCH

/v1/studio/templates/{templateId}/update

curl -X PATCH "https://api.orshot.com/v1/studio/templates/<TEMPLATE_ID>/update" \
  -H "Authorization: Bearer <ORSHOT_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "<NAME>",
    "description": "<DESCRIPTION>",
    "tags": [],
    "canvas_width": 1
  }'

const res = await fetch("https://api.orshot.com/v1/studio/templates/<TEMPLATE_ID>/update", {
  method: "PATCH",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer <ORSHOT_API_KEY>",
  },
  body: JSON.stringify({
    "name": "<NAME>",
    "description": "<DESCRIPTION>",
    "tags": [],
    "canvas_width": 1
  }),
});

const data = await res.json();

import requests

response = requests.patch(
    "https://api.orshot.com/v1/studio/templates/<TEMPLATE_ID>/update",
    headers={"Authorization": "Bearer <ORSHOT_API_KEY>"},
    json={
      "name": "<NAME>",
      "description": "<DESCRIPTION>",
      "tags": [],
      "canvas_width": 1
    },
)

data = response.json()

$ch = curl_init("https://api.orshot.com/v1/studio/templates/<TEMPLATE_ID>/update");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PATCH");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer <ORSHOT_API_KEY>",
    "Content-Type: application/json",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
  "name" => "<NAME>",
  "description" => "<DESCRIPTION>",
  "tags" => [],
  "canvas_width" => 1
]));

$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>/update")
req = Net::HTTP::Patch.new(uri)
req["Authorization"] = "Bearer <ORSHOT_API_KEY>"
req["Content-Type"] = "application/json"
req.body = {
  "name": "<NAME>",
  "description": "<DESCRIPTION>",
  "tags": [],
  "canvas_width": 1
}.to_json

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

Enterprise Only

This endpoint is available only to first party clients like the Orshot MCP server and workspaces on the Enterprise plan. Checkout the Enterprise Pricing to get access.

Update an existing studio template. You can update metadata (name, description, tags), canvas dimensions, or the full page structure including elements.

Endpoint#

Endpoint

https://api.orshot.com/v1/studio/templates/:templateId/update

Query Parameters#

Parameter	Type	Required	Default	Description
`includeThumbnails`	Boolean	No	`false`	When `true`, the endpoint renders thumbnails synchronously and waits for all uploads before responding. When `false` or absent, thumbnails are generated asynchronously if visual content changed.

Request Examples#

JavaScript

// Update name, description, and tags
await fetch("https://api.orshot.com/v1/studio/templates/12345/update", {
  method: "PATCH",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer <ORSHOT_API_KEY>",
  },
  body: JSON.stringify({
    name: "Summer Sale Banner - Updated",
    description: "Updated promotional banner for the summer 2026 campaign",
    tags: ["sale", "summer", "promotional"]
  }),
});

JavaScript

// Update canvas dimensions and pages
await fetch("https://api.orshot.com/v1/studio/templates/12345/update?includeThumbnails=true", {
  method: "PATCH",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer <ORSHOT_API_KEY>",
  },
  body: JSON.stringify({
    canvas_width: 1200,
    canvas_height: 628,
    pages_data: [
      {
        id: "page-1-uuid",
        name: "Page 1",
        canvas: { width: 1200, height: 628, backgroundColor: "#ffffff" },
        elements: [
          {
            id: "headline-element",
            type: "text",
            position: { x: 100, y: 200 },
            dimensions: { width: 880, height: 100 },
            content: "Your Headline Here",
            parameterId: "headline",
            parameterizable: true
          }
        ]
      }
    ]
  }),
});

JSON

{
  "success": true,
  "template": {
    "id": 12345,
    "name": "Summer Sale Banner - Updated",
    "description": "Updated promotional banner for the summer 2026 campaign",
    "tags": ["sale", "summer", "promotional"],
    "updated_at": "2026-01-29T12:00:00.000Z"
  }
}

JSON

{
  "success": true,
  "template": {
    "id": 12345,
    "name": "Summer Sale Banner - Updated",
    "description": "Updated promotional banner for the summer 2026 campaign",
    "tags": ["sale", "summer", "promotional"],
    "updated_at": "2026-01-29T12:00:00.000Z",
    "thumbnails": {
      "success": true,
      "pages": [
        {
          "page": 1,
          "page_id": "page-1-uuid",
          "thumbnail_url": "https://storage.orshot.com/cloud/w-50/renders/thumbnails/abc123.png",
          "error": null
        }
      ]
    }
  }
}

Rate Limits#

Limit	Value
Requests per minute	30

URL Parameters#

Parameter	Type	Required	Description
`templateId`	Integer	Yes	The ID of the template to update

Request Body Parameters#

At least one of the following parameters must be provided:

Parameter	Type	Required	Description
`name`	String	No	New name for the template (max 255 characters)
`description`	String	No	New description for the template
`tags`	Array	No	Array of tag strings to categorize the template (e.g. `["social", "marketing"]`)
`canvas_width`	Integer	No	New canvas width in pixels
`canvas_height`	Integer	No	New canvas height in pixels
`pages_data`	Array	No	Full array of page objects with elements (replaces existing pages)

Element motion and page motion fields (Motion) are validated on write: structural problems (a missing or cyclic after reference, values over the engine caps) fail with a 400 listing each issue, while unknown or misspelled motion params are accepted and reported back in the response warnings array with a suggestion. Problems already present in the stored template never block an unrelated update.

When pages_data is provided, template-level modifications are automatically recalculated from the elements. Pure metadata updates (name, description, tags) do not trigger thumbnail regeneration.

Pages may include audio tracks, generated narration, ambient audio, subtitles, waveform elements, and a saved video duration. Generated narration and ambient audio are resolved when the template is saved. See Template Anatomy for the complete schema.

Response Fields#

Field	Type	Description
`success`	Boolean	Whether the update was successful
`template`	Object	Updated template information
`template.id`	Integer	Template ID
`template.name`	String	Updated template name
`template.description`	String	Updated template description
`template.tags`	Array	Updated tags array
`template.updated_at`	String	ISO 8601 timestamp of the update
`warnings`	Array	Non-blocking authoring warnings (e.g. an unknown motion param with a suggested fix). Present only when there is something to fix
`template.thumbnails`	Object	Only present when `?includeThumbnails=true`. See the Thumbnails Object Structure section

Thumbnails Object Structure#

When you pass ?includeThumbnails=true and the update includes visual changes (pages_data, canvas_width, or canvas_height), the response includes a thumbnails object:

Field	Type	Description
`success`	Boolean	`true` if at least one page rendered successfully
`pages[].page`	Integer	1-based page number
`pages[].page_id`	String	Stable UUID of the page
`pages[].thumbnail_url`	String\|null	Public URL of the uploaded thumbnail PNG. `null` if this specific page failed
`pages[].error`	String\|null	Error message if this page failed. `null` on success

Error Responses#

Status Code	Error	Description
400	At least one field required	Neither name nor description provided
400	name must be non-empty string	Empty or invalid name provided
400	name must be 255 characters or less	Name exceeds maximum length
400	description must be a string	Invalid description type
403	Access Forbidden	Invalid API key or template not in workspace
404	Template not found	Template ID doesn't exist
429	Rate limit exceeded	Too many requests (max 30/min)
500	Internal server error	Server-side error

Cache Invalidation#

When the template is updated:

Template render cache is automatically invalidated
Dynamic URL cache for the template is cleared

Use Cases#

Rename templates after generation or import
Update descriptions for better organization
Tag templates for filtering and categorization
Update canvas dimensions when resizing templates
Replace page structure with updated elements and layouts
Batch rename templates via programmatic naming conventions

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