# Templates

> The menu you render from.

Templates are reusable designs with addressable layers. List and read them, or manage them programmatically. All template endpoints are scoped to your company.

## List templates

```http
GET /v1/templates
```

Returns a cursor-paginated list of your templates.

- **Auth:** Bearer token
- **Token abilities:** `api_requests`
- **Gates:** logApiRequest
- **Credits:** Free — no credits consumed.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `cursor` | query | string | No | Cursor token from a previous response's meta.next_cursor. |

### Responses

**200** — A page of templates.

```json
{
    "data": [
        {
            "uuid": "141e8454-8aa1-420a-bd0b-18a85ba949a2",
            "title": "Template 1",
            "width": 1200,
            "height": 630,
            "layers": [
                {
                    "layer": "review_title",
                    "type": "text",
                    "available_modifications": {
                        "text": "The worst Time-Travel movie ever made"
                    }
                }
            ],
            "created_at": "2026-05-01T12:00:00Z"
        }
    ],
    "meta": {
        "previous_cursor": null,
        "next_cursor": "eyJpZCI6MTB9"
    }
}
```

### Examples

*Curl*

```bash
curl https://app.snapsbrew.com/api/v1/templates \
  -H 'Authorization: Bearer <your-token>'
```

## List canvas size presets

```http
GET /v1/templates/sizes
```

Returns every canvas size preset a template write accepts as `size` — Instagram, Facebook, X, LinkedIn, Threads, Pinterest, TikTok, YouTube, Snapchat, WhatsApp, web and email, display ads, and print. Each preset gives its dimensions, aspect ratio, and the safe margin to keep content away from the edges.

- **Auth:** Bearer token
- **Token abilities:** `api_requests`
- **Gates:** logApiRequest
- **Credits:** Free — no credits consumed.

### Responses

**200** — The preset catalog.

```json
{
    "data": [
        {
            "size": "instagram_story",
            "name": "Instagram Story (1080x1920)",
            "platform": "Instagram",
            "width": 1080,
            "height": 1920,
            "aspect_ratio": "9:16",
            "safe_margin_px": 97
        },
        {
            "size": "open_graph",
            "name": "Open Graph / Link Preview (1200x630)",
            "platform": "Web & email",
            "width": 1200,
            "height": 630,
            "aspect_ratio": "1.9:1",
            "safe_margin_px": 47
        }
    ]
}
```

### Examples

*Curl*

```bash
curl https://app.snapsbrew.com/api/v1/templates/sizes \
  -H 'Authorization: Bearer <your-token>'
```

## Get a template

```http
GET /v1/templates/{templateUuid}
```

Returns a single template, its parsed layers and its publish state. The layers are the draft, so read `has_unpublished_edits` to know whether the draft is what renders.

- **Auth:** Bearer token
- **Token abilities:** `api_requests`
- **Gates:** logApiRequest
- **Credits:** Free — no credits consumed.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `templateUuid` | path | string | Yes | UUID of the template. |

### Responses

**200** — The template.

```json
{
    "data": {
        "uuid": "141e8454-8aa1-420a-bd0b-18a85ba949a2",
        "title": "Template 1",
        "size": "open_graph",
        "width": 1200,
        "height": 630,
        "layers": [
            {
                "layer": "review_poster",
                "type": "image",
                "available_modifications": {
                    "image_url": "https://app.snapsbrew.com/crazy-doc-brown-jailed"
                }
            },
            {
                "layer": "review_title",
                "type": "text",
                "available_modifications": {
                    "text": "The worst Time-Travel movie ever made"
                }
            }
        ],
        "published_version": 2,
        "has_unpublished_edits": true,
        "created_at": "2026-05-01T12:00:00Z"
    }
}
```

**404** — Template not found in your company.

```json
{
    "message": "Not found."
}
```

> BREAKING CHANGE. The template fields moved under a `data` key. Read `data.uuid`, not `uuid`. Every success body of this API is `{"data": ...}`, a list adds `meta` and a write adds `message`.

> `size` is the canvas size preset the template is stored under, the same value POST /v1/templates returns. It reads `custom` when the dimensions match no preset. GET /v1/templates/sizes lists every preset.

> `published_version` is the version number snaps and previews render. It is null until you publish the template.

> `has_unpublished_edits` is true when the draft is not the same as the published version. A layer edit, a resize and an editor-document edit all set it. Call POST /v1/templates/{templateUuid}/publish to make the draft render.

### Examples

*Curl*

```bash
curl https://app.snapsbrew.com/api/v1/templates/<uuid> \
  -H 'Authorization: Bearer <your-token>'
```

## Create a template

```http
POST /v1/templates
```

Creates a template and generates its preview image. Requires the create-template policy.

- **Auth:** Bearer token
- **Token abilities:** `api_requests`
- **Gates:** policy:create,Template
- **Credits:** Free — no credits consumed.

### Request body

Content-Type: `application/json`

| Field | Type | Required | Validation | Description |
| --- | --- | --- | --- | --- |
| `title` | string | Yes | required\|string\|max:255 | Template name. |
| `size` | string | No | nullable\|in:<preset> | Canvas size preset, for example "instagram_story" or "youtube_thumbnail". It sets width and height for you. GET /v1/templates/sizes lists every preset. |
| `width` | integer | No | required_without:size\|numeric\|min:1\|max:4000 | Canvas width in pixels. Required when you send no size preset. Ignored when you send a size preset. |
| `height` | integer | No | required_without:size\|numeric\|min:1\|max:4000 | Canvas height in pixels. Required when you send no size preset. Ignored when you send a size preset. |
| `layers` | array | No | nullable\|array | Layer definitions; stored JSON-encoded. An absent or null list creates an empty canvas. |

### Responses

**200** — Template created.

```json
{
    "data": {
        "uuid": "141e8454-8aa1-420a-bd0b-18a85ba949a2",
        "title": "Launch card",
        "size": "open_graph",
        "width": 1200,
        "height": 630,
        "created_at": "2026-05-01T12:00:00Z"
    },
    "message": "Template created successfully"
}
```

**422** — The body names no canvas, or a field failed a rule.

```json
{
    "message": "Send a `size` preset or an explicit `width` and `height`.",
    "errors": {
        "width": [
            "Send a `size` preset or an explicit `width` and `height`."
        ],
        "height": [
            "Send a `size` preset or an explicit `width` and `height`."
        ]
    }
}
```

> Send a `size` preset or an explicit `width`/`height`. A template saved with dimensions that match a preset is stored under that preset.

> A body with no `size` and no `width`/`height` answers 422. A create has no stored canvas to fall back on.

> The response holds the six fields above and nothing more. Read GET /v1/templates/{templateUuid} for the parsed layers and the publish state.

### Examples

*Curl*

```bash
curl -X POST https://app.snapsbrew.com/api/v1/templates \
  -H 'Authorization: Bearer <your-token>' \
  -H 'Content-Type: application/json' \
  -d '{"title":"Launch card","size":"open_graph","layers":[]}'
```

## Update a template

```http
PATCH /v1/templates/{templateIdentifier}
```

Updates a template and regenerates its preview image. The path segment accepts the template UUID or the numeric template ID. GET /v1/templates returns the UUID.

- **Auth:** Bearer token
- **Token abilities:** `api_requests`
- **Credits:** Free — no credits consumed.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `templateIdentifier` | path | string | Yes | Template UUID or numeric template ID, scoped to your company. A value of only digits reads the numeric ID. Every other value reads the UUID. |

### Request body

Content-Type: `application/json`

| Field | Type | Required | Validation | Description |
| --- | --- | --- | --- | --- |
| `title` | string | Yes | required\|string\|max:255 | Template name. |
| `size` | string | No | nullable\|in:<preset> | Canvas size preset, for example "instagram_story" or "youtube_thumbnail". It sets width and height for you. GET /v1/templates/sizes lists every preset. |
| `width` | integer | No | nullable\|numeric\|min:1\|max:4000 | Canvas width in pixels. Ignored when you send a size preset. |
| `height` | integer | No | nullable\|numeric\|min:1\|max:4000 | Canvas height in pixels. Ignored when you send a size preset. |
| `layers` | array | No | nullable\|array | Layer definitions; stored JSON-encoded. |

### Responses

**200** — Template updated.

```json
{
    "data": {
        "uuid": "141e8454-8aa1-420a-bd0b-18a85ba949a2",
        "title": "Updated title",
        "size": "open_graph",
        "width": 1200,
        "height": 630,
        "created_at": "2026-05-01T12:00:00Z"
    },
    "message": "Template updated successfully"
}
```

**404** — Template not found in your company.

```json
{
    "message": "Not found."
}
```

> `data` holds the same six fields POST /v1/templates returns. It is a new key, so a client that reads `message` still works.

> Read `data.size`, `data.width` and `data.height` after the write. A body that sends `size` sets the dimensions, and a body that sends the dimensions sets `size`.

### Examples

*Curl*

```bash
curl -X PATCH https://app.snapsbrew.com/api/v1/templates/<uuid> \
  -H 'Authorization: Bearer <your-token>' \
  -H 'Content-Type: application/json' \
  -d '{"title":"Updated title"}'
```

## Publish a template

```http
POST /v1/templates/{templateUuid}/publish
```

Publishes the current draft of a template as a new immutable version and returns that version number. Snaps and previews render the published version, so an edit takes effect only after this call. The call is safe to repeat: a draft with no new edits returns the version which is already live and creates no second version.

- **Auth:** Bearer token
- **Token abilities:** `api_requests`
- **Gates:** policy:update,Template
- **Credits:** Free — no credits consumed.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `templateUuid` | path | string | Yes | UUID of the template whose draft you want to publish. |

### Responses

**200** — The published version.

```json
{
    "data": {
        "id": "141e8454-8aa1-420a-bd0b-18a85ba949a2",
        "uuid": "141e8454-8aa1-420a-bd0b-18a85ba949a2",
        "published_version": 2
    },
    "message": "Template published. New snaps and previews now render this version."
}
```

**404** — Template not found in your company.

```json
{
    "message": "Not found."
}
```

> BREAKING CHANGE. The response fields moved under a `data` key. Read `data.published_version`, not `published_version`.

> `data.id` is deprecated. It repeats the value of `data.uuid`, which is the name every other template field uses. Read `data.uuid`. `data.id` stays until a major version removes it.

### Examples

*Curl*

```bash
curl -X POST https://app.snapsbrew.com/api/v1/templates/<uuid>/publish \
  -H 'Authorization: Bearer <your-token>'
```

## Delete a template

```http
DELETE /v1/templates/{templateIdentifier}
```

Deletes a template. The path segment accepts the template UUID or the numeric template ID. GET /v1/templates returns the UUID. Requires the delete-template policy.

- **Auth:** Bearer token
- **Token abilities:** `api_requests`
- **Gates:** policy:delete,Template
- **Credits:** Free — no credits consumed.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `templateIdentifier` | path | string | Yes | Template UUID or numeric template ID, scoped to your company. A value of only digits reads the numeric ID. Every other value reads the UUID. |

### Responses

**200** — Template deleted.

```json
{
    "message": "Template deleted successfully"
}
```

**404** — Template not found in your company.

```json
{
    "message": "Not found."
}
```

> This body carries no `data` key. Every other success body of this API holds one, and a delete is the exemption: the template is gone, so there is no resource to return.

### Examples

*Curl*

```bash
curl -X DELETE https://app.snapsbrew.com/api/v1/templates/<uuid> \
  -H 'Authorization: Bearer <your-token>'
```
