# Snaps

> Templates in, finished assets out.

A snap renders a template (or every template in a collection) into a finished image or PDF, with your content substituted into each layer. Render synchronously for an instant result, or asynchronously with a webhook for bulk work. Creating snaps requires an active subscription or trial.

## Create a snap

```http
POST /v1/snaps
```

Renders a snap from a single template (`template_id`) or every template in a collection (`collection_id`). Provide exactly one of the two.

Synchronous (default): the response carries the finished `media_url` and returns 201.

Asynchronous (`async: true`): the snap is queued, the response returns 202 immediately, and the result is delivered to `webhook_url` on completion.

The API always renders the template's **published** version. Unpublished draft edits are not visible to the API until the template is published.

- **Auth:** Bearer token
- **Token abilities:** `api_requests`
- **Gates:** logApiRequest, hasActiveSubscription
- **Credits:** Synchronous: 1 credit per rendered template. Asynchronous: 0 credits at accept time (HTTP 202); the credit is charged when the queued snap reaches completed. A repeated `idempotency_key` returns the first snap and charges 0 credits.

### Request body

Content-Type: `application/json`

| Field | Type | Required | Validation | Description |
| --- | --- | --- | --- | --- |
| `template_id` | string | No | required_without:collection_id, prohibits:collection_id, exists templates.uuid scoped to company | UUID of a single template to render. |
| `collection_id` | string | No | required_without:template_id, prohibits:template_id, exists template_collections.uuid scoped to company | UUID of a collection; one snap is rendered per template. |
| `type` | string | No | nullable, in:image,pdf | Output type. Defaults to image. |
| `format` | string | No | sometimes, in:png,jpeg,webp | Image output format (image type only). Defaults to png. |
| `transparent` | boolean | No | sometimes, boolean; rejected with png-only/webp-only — 422 when combined with format=jpeg | Render on a transparent background. Valid for png and webp only; jpeg + transparent returns 422. |
| `async` | boolean | No | sometimes, boolean | Queue the render and return 202. |
| `webhook_url` | string | No | url, required_if:async,true, must be a public http or https address | Callback URL invoked when an async snap completes. The address must be public. A host that resolves to a private, loopback, link-local or reserved range is rejected with 422. |
| `variants` | array | No | no server validation | Per-layer content overrides applied to the render. |
| `idempotency_key` | string | No | sometimes, nullable, string, max:191, letters/digits/underscore/hyphen only, prohibits:collection_id | Send the same key when you retry after a timeout. The retry returns the same snap and charges no second credit. Keys are honored for 24 hours and are scoped to your account. Not supported with collection_id. |

### Responses

**201** — Synchronous snap rendered.

```json
{
    "id": "9f1c2d3e",
    "media_url": "https://app.snapsbrew.com/storage/snaps/9f1c2d3e.png",
    "type": "image",
    "status": "completed",
    "is_async": false,
    "webhook_url": null,
    "completed_at": "2026-05-01T12:00:03Z",
    "last_error": null,
    "variants": [],
    "template_id": "141e8454-8aa1-420a-bd0b-18a85ba949a2",
    "template_title": "Launch card",
    "created_at": "2026-05-01T12:00:00Z"
}
```

**202** — Asynchronous snap queued.

```json
{
    "id": "9f1c2d3e",
    "media_url": null,
    "type": "image",
    "status": "pending",
    "is_async": true,
    "webhook_url": "https://example.com/hooks/snap",
    "completed_at": null,
    "last_error": null,
    "variants": [],
    "template_id": "141e8454-8aa1-420a-bd0b-18a85ba949a2",
    "template_title": "Launch card",
    "created_at": "2026-05-01T12:00:00Z"
}
```

**404** — Template or collection not found, or collection empty.

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

**417** — Monthly credit quota exhausted.

```json
{
    "message": "You have reached your snap quota."
}
```

**409** — Another request with the same idempotency_key is still in progress. Nothing was created and nothing was charged. Retry.

```json
{
    "message": "A request with this idempotency_key is already in progress. Retry in a moment. Nothing was created and nothing was charged."
}
```

**422** — Validation failed.

```json
{
    "message": "The template id field is required when collection id is not present."
}
```

> Every response carries an `X-Request-Uuid` header. Quote it in support tickets.

> A collection request returns an array of snap objects, one per template.

> A response to a repeated `idempotency_key` carries an `X-Idempotent-Replay: true` header and charges 0 credits.

> `webhook_url` must be a public address. A host that resolves to a private, loopback, link-local or reserved range is rejected with 422.

> An `idempotency_key` is honored for 24 hours. After that window a retry is a new request and charges a new credit.

### Examples

*Curl*

```bash
curl -X POST https://app.snapsbrew.com/api/v1/snaps \
  -H 'Authorization: Bearer <your-token>' \
  -H 'Content-Type: application/json' \
  -d '{"template_id":"<uuid>","type":"image","variants":[{"layer":"review_title","text":"Hello world"}]}'
```

*Async curl*

```bash
curl -X POST https://app.snapsbrew.com/api/v1/snaps \
  -H 'Authorization: Bearer <your-token>' \
  -H 'Content-Type: application/json' \
  -d '{"template_id":"<uuid>","async":true,"webhook_url":"https://example.com/hooks/snap"}'
```
