# 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://snapsbrew.com/api/v1/templates \
  -H 'Authorization: Bearer <your-token>'
```

## Get a template

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

Returns a single template and its parsed layers.

- **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
{
    "uuid": "141e8454-8aa1-420a-bd0b-18a85ba949a2",
    "title": "Template 1",
    "width": 1200,
    "height": 630,
    "layers": [
        {
            "layer": "review_poster",
            "type": "image",
            "available_modifications": {
                "image_url": "https://snapsbrew.com/crazy-doc-brown-jailed"
            }
        },
        {
            "layer": "review_title",
            "type": "text",
            "available_modifications": {
                "text": "The worst Time-Travel movie ever made"
            }
        }
    ],
    "created_at": "2026-05-01T12:00:00Z"
}
```

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

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

### Examples

*Curl*

```bash
curl https://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 | No | no server validation | Template name. |
| `width` | integer | No | no server validation | Canvas width in pixels. |
| `height` | integer | No | no server validation | Canvas height in pixels. |
| `layers` | array | No | no server validation | Layer definitions; stored JSON-encoded. |

### Responses

**200** — Template created.

```json
{
    "data": {
        "uuid": "...",
        "title": "New template"
    },
    "message": "Template created successfully"
}
```

> This endpoint does not validate input. Send well-formed values — bad data is persisted as-is.

### Examples

*Curl*

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

## Update a template

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

Updates a template and regenerates its preview image. The path segment is the numeric template ID, not the UUID.

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

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `templateId` | path | integer | Yes | Numeric template ID, scoped to your company. |

### Request body

Content-Type: `application/json`

| Field | Type | Required | Validation | Description |
| --- | --- | --- | --- | --- |
| `title` | string | No | no server validation | Template name. |
| `width` | integer | No | no server validation | Canvas width in pixels. |
| `height` | integer | No | no server validation | Canvas height in pixels. |
| `layers` | array | No | no server validation | Layer definitions; stored JSON-encoded. |

### Responses

**200** — Template updated.

```json
{
    "message": "template updated sucessfully"
}
```

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

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

### Examples

*Curl*

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

## Delete a template

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

Deletes a template. The path segment is the numeric template ID. 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 |
| --- | --- | --- | --- | --- |
| `templateId` | path | integer | Yes | Numeric template ID, scoped to your company. |

### Responses

**200** — Template deleted.

```json
{
    "message": "template deleted sucessfully"
}
```

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

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

### Examples

*Curl*

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