Anatomy of a Template

Understanding the structure of an Orshot Studio template

This guide explains the data structure of an Orshot Studio template. Understanding this structure is essential when creating templates via the API or working with template data programmatically.

Template Overview#

A Studio template consists of metadata, canvas settings, and pages containing elements. Templates support multi-page designs (like carousels) with each page having its own canvas settings and elements.

{
  "id": 12345,
  "name": "Summer Sale Banner",
  "description": "Promotional banner for summer campaign",
  "tags": ["sale", "summer"],
  "canvas_width": 1080,
  "canvas_height": 1080,
  "pages_data": [...],
  "modifications": [...],
  "modifications_json": {...},
  "thumbnail_url": "https://..."
}

Top-Level Fields#

Field	Type	Description
`id`	Integer	Unique template identifier (auto-generated)
`name`	String	Template name (max 255 characters)
`description`	String	Optional template description
`tags`	Array	Array of tag strings for categorization
`canvas_width`	Integer	Width of the first page in pixels (1-5000)
`canvas_height`	Integer	Height of the first page in pixels (1-5000)
`pages_data`	Array	Array of page objects
`modifications`	Array	Flattened list of all parameterizable elements
`modifications_json`	Object	Key-value map of parameter IDs to default values
`thumbnail_url`	String	URL to template preview thumbnail

Pages Data Structure#

The pages_data array contains page objects. Each page represents a slide in a carousel or a single canvas in a multi-page template.

{
  "pages_data": [
    {
      "id": "uuid-page-1",
      "name": "Page 1",
      "canvas": {
        "width": 1080,
        "height": 1080,
        "backgroundColor": "#ffffff"
      },
      "elements": [...],
      "modifications": [...],
      "thumbnail_url": "https://..."
    }
  ]
}

Page Object Fields#

Field	Type	Description
`id`	String	Unique page identifier (UUID recommended)
`name`	String	Display name for the page (e.g., "Page 1", "Cover Slide")
`canvas`	Object	Canvas settings for this page
`elements`	Array	Array of element objects on this page
`modifications`	Array	Parameterizable elements on this page
`thumbnail_url`	String	URL to page thumbnail preview

Canvas Object#

Each page has its own canvas settings, allowing different dimensions per page:

{
  "canvas": {
    "width": 1080,
    "height": 1080,
    "backgroundColor": "#ffffff",
    "backgroundImage": "",
    "borderWidth": 0,
    "borderColor": "rgba(0, 0, 0, 1)",
    "borderStyle": "solid"
  }
}

Field	Type	Description
`width`	Integer	Canvas width in pixels (1-5000)
`height`	Integer	Canvas height in pixels (1-5000)
`backgroundColor`	String	Background color (hex, rgb, rgba)
`backgroundImage`	String	Optional background image URL
`borderWidth`	Integer	Border width in pixels
`borderColor`	String	Border color
`borderStyle`	String	Border style (solid, dashed, etc.)

Elements#

Elements are the building blocks of a template. Each element has a type, position, dimensions, and type-specific properties.

Common Element Properties#

All elements share these base properties:

{
  "id": "uuid-element-1",
  "type": "text",
  "name": "Headline",
  "x": 50,
  "y": 100,
  "width": 400,
  "height": 80,
  "rotation": 0,
  "opacity": 1,
  "visible": true,
  "locked": false,
  "parameterizable": true,
  "parameterId": "headline"
}

Field	Type	Description
`id`	String	Unique element identifier (UUID)
`type`	String	Element type: `text`, `image`, `rectangle`, `ellipse`, `shape`
`name`	String	Display name for the element
`x`	Number	X position from left edge
`y`	Number	Y position from top edge
`width`	Number	Element width in pixels
`height`	Number	Element height in pixels
`rotation`	Number	Rotation in degrees (0-360)
`opacity`	Number	Opacity (0-1)
`visible`	Boolean	Whether element is visible
`locked`	Boolean	Whether element is locked from editing
`parameterizable`	Boolean	Whether element can be modified via API
`parameterId`	String	Unique ID for API modifications (when parameterizable)

Text Elements#

Text elements display text content with styling options:

{
  "id": "uuid-text-1",
  "type": "text",
  "content": "Summer Sale!",
  "x": 50,
  "y": 100,
  "width": 400,
  "height": 80,
  "style": {
    "fontSize": 48,
    "fontFamily": "Inter",
    "fontWeight": "bold",
    "color": "#000000",
    "textAlign": "center",
    "verticalAlign": "center",
    "letterSpacing": 0,
    "lineHeight": 1.2,
    "textMode": "fit"
  },
  "parameterizable": true,
  "parameterId": "headline"
}

Style Property	Type	Description
`fontSize`	Number	Font size in pixels
`fontFamily`	String	Font family name
`fontWeight`	String/Number	Font weight (normal, bold, 100-900)
`color`	String	Text color
`textAlign`	String	Horizontal alignment: `left`, `center`, `right`
`verticalAlign`	String	Vertical alignment: `flex-start`, `center`, `flex-end`
`letterSpacing`	Number	Letter spacing in pixels
`lineHeight`	Number	Line height multiplier
`textMode`	String	`fit` (scales to fit), `overflow` (wraps naturally), `truncate` (clips with ellipsis), or `flow` (splits across pages)

Flow Mode Properties

When textMode is set to "flow", these additional properties control how text splits across pages:

Property	Type	Description
`repeatOnOverflow`	Boolean	When `true`, this element appears on every overflow page
`flowZones`	Array	Custom zones for text placement on overflow pages (see below)
`flowBreakBehavior`	String	`"line"` (default), `"word"`, or `"char"` — where to split text
`flowMinLinesBeforeBreak`	Integer	Min lines at bottom of page before a break (default: 2)
`flowMinLinesAfterBreak`	Integer	Min lines at top of next page after a break (default: 2)

Each entry in flowZones has { y, height } — the Y position and height of the text area on that overflow page. The last zone repeats for all further pages. See Flowing Content for details.

Image Elements#

Image elements display images with fit options:

{
  "id": "uuid-image-1",
  "type": "image",
  "src": "https://cdn.example.com/product.png",
  "src_url": "https://cdn.example.com/product.png",
  "x": 100,
  "y": 200,
  "width": 300,
  "height": 300,
  "style": {
    "objectFit": "contain",
    "borderRadius": 8
  },
  "parameterizable": true,
  "parameterId": "product_image"
}

Property	Type	Description
`src`	String	Image source URL
`src_url`	String	Original image URL
`objectFit`	String	How image fits: `contain`, `cover`, `fill`
`borderRadius`	Number	Corner radius in pixels

Shape Elements#

Shapes include rectangles, ellipses, and custom shapes:

{
  "id": "uuid-shape-1",
  "type": "rectangle",
  "x": 0,
  "y": 0,
  "width": 1080,
  "height": 200,
  "style": {
    "fill": "#ff5733",
    "backgroundColor": "#ff5733",
    "borderRadius": 0,
    "borderWidth": 0,
    "borderColor": "#000000"
  }
}

Modifications#

The modifications array at the template level contains all parameterizable elements across all pages in a lean format. Each entry stores the parameter metadata without duplicating the full element object.

{
  "modifications": [
    {
      "id": "headline",
      "type": "text",
      "default_value": "Summer Sale!",
      "element_id": "uuid-element-1",
      "element_name": "Headline",
      "element_type": "text",
      "is_hidden": false,
      "page_number": 1
    },
    {
      "id": "product_image",
      "type": "imageUrl",
      "default_value": "https://cdn.example.com/product.png",
      "element_id": "uuid-image-1",
      "element_name": "Product Image",
      "element_type": "image",
      "is_hidden": false,
      "page_number": 1
    }
  ]
}

Modification Fields (stored format)#

Field	Type	Description
`id`	String	Parameter key. Multi-page templates use `page2@headline` format for pages beyond page 1
`type`	String	`text`, `imageUrl`, `videoUrl`, `backgroundColor`, `fill`, `color`, `stroke`
`default_value`	String	Default value extracted from the element
`element_id`	String	UUID of the source element
`element_name`	String	Layer name of the element (from `layerName` or `name`)
`element_type`	String	Element type (`text`, `image`, `rectangle`, etc.)
`is_hidden`	Boolean	Whether the element is hidden in the editor
`page_number`	Integer	1-based page number

When returned via API endpoints, modifications are formatted with additional fields (key, description, help_text, example, page_id) for convenience. See the API reference for the response format.

Modifications JSON#

The modifications_json object provides a simple key-value map of parameter IDs to their default values:

{
  "modifications_json": {
    "headline": "Summer Sale!",
    "subtitle": "Up to 50% off",
    "product_image": "https://cdn.example.com/product.png",
    "price": "$99.99"
  }
}

This format is useful for quickly understanding what parameters a template accepts and their default values.

Complete Example#

Here's a complete single-page template structure:

{
  "name": "Product Promo",
  "description": "Product promotion template",
  "tags": ["promo", "product"],
  "canvas_width": 1080,
  "canvas_height": 1080,
  "pages_data": [
    {
      "id": "page-1-uuid",
      "name": "Page 1",
      "canvas": {
        "width": 1080,
        "height": 1080,
        "backgroundColor": "#ffffff"
      },
      "elements": [
        {
          "id": "bg-uuid",
          "type": "rectangle",
          "name": "Background",
          "x": 0,
          "y": 0,
          "width": 1080,
          "height": 1080,
          "style": { "fill": "#f5f5f5" }
        },
        {
          "id": "headline-uuid",
          "type": "text",
          "name": "Headline",
          "content": "New Arrival",
          "x": 50,
          "y": 50,
          "width": 980,
          "height": 100,
          "style": {
            "fontSize": 72,
            "fontFamily": "Inter",
            "fontWeight": "bold",
            "color": "#000000",
            "textAlign": "center"
          },
          "parameterizable": true,
          "parameterId": "headline"
        },
        {
          "id": "product-uuid",
          "type": "image",
          "name": "Product Image",
          "src": "https://cdn.example.com/product.png",
          "x": 290,
          "y": 200,
          "width": 500,
          "height": 500,
          "style": { "objectFit": "contain" },
          "parameterizable": true,
          "parameterId": "product_image"
        },
        {
          "id": "price-uuid",
          "type": "text",
          "name": "Price",
          "content": "$99.99",
          "x": 50,
          "y": 750,
          "width": 980,
          "height": 80,
          "style": {
            "fontSize": 48,
            "fontFamily": "Inter",
            "fontWeight": "600",
            "color": "#ff5733",
            "textAlign": "center"
          },
          "parameterizable": true,
          "parameterId": "price"
        }
      ],
      "modifications": []
    }
  ],
  "modifications": [
    {
      "id": "headline",
      "type": "text",
      "default_value": "New Arrival",
      "element_id": "headline-uuid",
      "element_name": "Headline",
      "element_type": "text",
      "is_hidden": false,
      "page_number": 1
    },
    {
      "id": "product_image",
      "type": "imageUrl",
      "default_value": "https://cdn.example.com/product.png",
      "element_id": "product-uuid",
      "element_name": "Product Image",
      "element_type": "image",
      "is_hidden": false,
      "page_number": 1
    },
    {
      "id": "price",
      "type": "text",
      "default_value": "$99.99",
      "element_id": "price-uuid",
      "element_name": "Price",
      "element_type": "text",
      "is_hidden": false,
      "page_number": 1
    }
  ],
  "modifications_json": {
    "headline": "New Arrival",
    "product_image": "https://cdn.example.com/product.png",
    "price": "$99.99"
  }
}