# Editor documents

> The draft behind the template.

An editor document is the v2 draft of a template: its layers, its groups and every design-time property the editor shows. A template renders from that draft, so a change here changes what the next render draws.

Every write is a compare-and-swap. Read the document, keep the `revision` it returns, and send that revision back. If the stored revision moved, the write returns `409` with the current revision and the current document. Rebuild the change on top of them and send the write again. Never resend the same body with the returned revision.

`PATCH` applies a closed list of operations and changes only the properties you name. `PUT` replaces the whole document and drops every property you leave out. `GET /v1/guides/editor-document` carries the constraints both accept.

## Get the editor document

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

Returns the stored v2 editor document and its revision. A template with no draft returns a null document and revision 0. Read this before every write.

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

### Parameters

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

### Responses

**200** — The document and its revision.

```json
{
    "document": {
        "version": 2,
        "layers": [
            {
                "key": "headline",
                "type": "text",
                "properties": [
                    {
                        "name": "fontWeight",
                        "value": 700
                    }
                ]
            }
        ],
        "groups": []
    },
    "revision": 4
}
```

**403** — Your account is not allowed to read templates.

```json
{
    "message": "This action is unauthorized."
}
```

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

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

> The read gate and the write gate name the same people. Every account in your company that can write the document can also read it.

### Examples

*Curl*

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

## Apply editor operations

```http
PATCH /v1/templates/{templateUuid}/document
```

Applies a closed list of layer operations and saves the result under the next revision. `set_layer_property` takes `layer_key`, `property` and `value`. `set_layer_type` takes `layer_key` and `type`. Every operation in one call applies together, or none of them applies.

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

### Parameters

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

### Request body

Content-Type: `application/json`

| Field | Type | Required | Validation | Description |
| --- | --- | --- | --- | --- |
| `revision` | integer | Yes | required\|integer\|min:0 | The revision the last read returned. |
| `operations` | array | Yes | required\|array\|max:100 | One to 100 operation objects, applied in order. |

### Responses

**200** — The saved document and its new revision.

```json
{
    "document": {
        "version": 2,
        "layers": [
            {
                "key": "headline",
                "type": "text",
                "properties": [
                    {
                        "name": "fontWeight",
                        "value": 700
                    }
                ]
            }
        ],
        "groups": []
    },
    "revision": 5
}
```

**409** — The stored revision moved. Nothing was saved.

```json
{
    "code": "editor_document_conflict",
    "current_revision": 5,
    "current_document": {
        "version": 2,
        "layers": [],
        "groups": []
    }
}
```

**422** — The body is malformed, or the document rejects an operation.

```json
{
    "code": "editor_operation_layer_not_found"
}
```

> A rejected operation returns a stable `code`, for example `editor_operation_layer_not_found` or `editor_operation_invalid_value`. Correct the operation and call again.

> A malformed body returns the standard validation shape instead, with a message under `errors.revision` or `errors.operations`.

> The route allows 30 calls a minute for one token and 180 a minute for one company.

### Examples

*Curl*

```bash
curl -X PATCH https://snapsbrew.com/api/v1/templates/<uuid>/document \
  -H 'Authorization: Bearer <your-token>' \
  -H 'Content-Type: application/json' \
  -d '{"revision":4,"operations":[{"operation":"set_layer_property","layer_key":"headline","property":"fontWeight","value":700}]}'
```

## Replace the editor document

```http
PUT /v1/templates/{templateUuid}/document
```

Replaces the whole v2 editor document and saves it under the next revision. Send the document you read, with your change applied to it. Any layer or property you leave out is gone. Prefer `PATCH` unless you rebuild the document.

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

### Parameters

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

### Request body

Content-Type: `application/json`

| Field | Type | Required | Validation | Description |
| --- | --- | --- | --- | --- |
| `revision` | integer | Yes | required\|integer\|min:0 | The revision the last read returned. |
| `document` | object | Yes | required\|array | The complete v2 document, with `layers` and `groups`. |

### Responses

**200** — The saved document and its new revision.

```json
{
    "document": {
        "version": 2,
        "layers": [],
        "groups": []
    },
    "revision": 5
}
```

**409** — The stored revision moved. Nothing was saved.

```json
{
    "code": "editor_document_conflict",
    "current_revision": 5,
    "current_document": {
        "version": 2,
        "layers": [],
        "groups": []
    }
}
```

**422** — The body is malformed, or the document breaks a limit.

```json
{
    "message": "The given data was invalid.",
    "errors": {
        "document": [
            "editor_document_too_large"
        ]
    }
}
```

> The document is bounded: 262144 bytes, 1000 nodes, depth 12, and 16384 characters for one string. A document over a limit returns `editor_document_too_large` or `editor_document_budget_exceeded` under `errors.document`.

> The route allows 30 calls a minute for one token and 180 a minute for one company.

### Examples

*Curl*

```bash
curl -X PUT https://snapsbrew.com/api/v1/templates/<uuid>/document \
  -H 'Authorization: Bearer <your-token>' \
  -H 'Content-Type: application/json' \
  -d '{"revision":4,"document":{"version":2,"layers":[],"groups":[]}}'
```

## Inspect the editor document

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

Reads the stored document and returns the known draft problems it carries, each with a code, a JSON pointer and a message. An empty `issues` list means the known checks pass. It does not guarantee that the render looks right.

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

### Parameters

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

### Responses

**200** — The issues and the revision they were read from.

```json
{
    "issues": [
        {
            "code": "image_asset_missing",
            "path": "/layers/0/source",
            "message": "Image layers require a pinned asset id."
        }
    ],
    "revision": 4
}
```

**403** — Your account is not allowed to read templates.

```json
{
    "message": "This action is unauthorized."
}
```

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

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

> Run it after the last write and before you publish the template.

### Examples

*Curl*

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