# Anatomy of a Template

> Understanding the structure of an Orshot Studio template

- **URL**: https://orshot.com/docs/definitions/template-anatomy

---

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.```json
{
  "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.```json
{
  "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:```json
{
  "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:```json
{
  "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:```json
{
  "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 `` — the Y position and height of the text area on that overflow page. The last zone repeats for all further pages. See [Flowing Content](https://orshot.com/docs/orshot-studio/flowing-content) for details.

### Image Elements

Image elements display images with fit options:```json
{
  "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:```json
{
  "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.```json
{
  "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](https://orshot.com/docs/api-reference/studio-template-get) for the response format.

## Modifications JSON

The `modifications_json` object provides a simple key-value map of parameter IDs to their default values:```json
{
  "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:```json
{
  "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"
  }
}
```## Related

- [Template ID](https://orshot.com/docs/definitions/template-id) - Finding your template ID
- [Modifications](https://orshot.com/docs/definitions/modifications) - Using modifications to customize templates
- [Create Template (Enterprise)](https://orshot.com/docs/api-reference/enterprise-template-create) - Create templates via API