Docs API
Snaps
Render a template or a collection into an image or a PDF, in sync or async mode, with variants and idempotency keys.
A snap is a rendered image or PDF. The instance renders a template with your content in its layers. See Snaps for the web screens.
| Method | Path | What it does |
|---|---|---|
POST |
/v1/snaps |
Renders one snap from a template, or one snap for each template of a collection. |
To render up to 100 snaps from one template, use Snap batches. To see a result before you render it, use Preview.
Create a snap
POST /v1/snaps
- Auth: bearer token
- Ability:
api_requests - Rate limit:
api(60 a minute) - Usage log: yes
Send template_id or collection_id. Do not send both.
The API renders the published version of each template. A draft edit has no effect until you publish the template. A template that has no published version renders its draft. See Publish a template.
Sync and async mode
- Sync (the default). The instance renders during the request. The response is
201with the finishedmedia_url. - Async (
"async": true). The instance puts the render on the queue. The response is202at once, withstatus: pending. When the render completes, the instance posts a webhook towebhook_url.
The queue worker must run for async mode. See Queues and Horizon.
Request body
| Field | Type | Required | Rules | Description |
|---|---|---|---|---|
template_id |
string | Without collection_id |
A template UUID of your company | The template to render. |
collection_id |
string | Without template_id |
A collection UUID of your company | The collection to render. The instance renders one snap for each template. |
type |
string | No | image or pdf |
The output type. The default is image. |
format |
string | No | png, jpeg or webp |
The image format. The default is png. |
transparent |
boolean | No | Not with jpeg |
Renders on a transparent background. Only png and webp accept it. |
async |
boolean | No | A boolean | Puts the render on the queue and returns 202. |
webhook_url |
string | With async: true |
A public http or https URL |
The address that receives the webhook. |
variants |
array | No | See below | The content for the layers. |
idempotency_key |
string | No | Maximum 191 characters. Letters, digits, _ and -. Not with collection_id. |
A key for a safe retry. See Idempotency keys. |
Variants
variants is a list of objects. Each object names a layer by its key and sets one property.
[
{"layer": "headline", "text": "Summer sale"},
{"layer": "logo", "image_url": "https://example.com/logo.png"},
{"layer": "backdrop", "background_color": "#ff5a36"},
{"layer": "ticket", "qr_content": "https://example.com/rsvp"},
{"layer": "sku", "barcode_content": "012345678905"},
{"layer": "ribbon", "hidden": true}
]
| Property | Rule |
|---|---|
layer |
A string. Use a layer key from GET /v1/templates/{templateUuid}. |
text |
A string. |
image_url |
A public http or https URL. The host of APP_URL is also accepted. |
background_color |
A valid CSS color. |
qr_content |
A string. |
barcode_content |
A string of 1000 characters or fewer. |
hidden |
A boolean. |
For the full catalog, call GET /v1/guides/variant-properties. See also Layers and variants.
Response
201 for a sync snap. The body is the snap object, with no data key.
{
"id": "9f1c2d3e",
"media_url": "https://snapsbrew.example/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 for an async snap. media_url is null and status is pending.
A request with collection_id returns a list of snap objects, one for each template.
The snap object
| Field | Type | Description |
|---|---|---|
id |
string | The UUID of the snap. |
media_url |
string or null | The URL of the file. It is null until the render completes. |
type |
string | image or pdf. |
status |
string | pending, processing, completed, failed or canceled. |
is_async |
boolean | true when the render ran on the queue. |
webhook_url |
string or null | The webhook address. |
completed_at |
datetime or null | The time when the render finished. |
last_error |
string or null | The cause of a failure. |
variants |
array or null | The variants that the render used. |
template_id |
string or null | The UUID of the template. It is null for a snap from an inline MCP design. |
template_title |
string or null | The title of the template. |
created_at |
datetime | The creation time. |
Response headers
| Header | When |
|---|---|
X-Request-Uuid |
On each response. The ID of the usage log row. |
X-Idempotent-Replay: true |
When the response repeats an earlier request with the same idempotency_key. Nothing renders again. |
Errors
| Status | Cause | Body |
|---|---|---|
404 |
The collection has no templates. | {"message": "The collection doesn't have any templates."} |
409 |
Another request with the same idempotency_key is in progress. Nothing was created. |
{"message": "A request with this idempotency_key is already in progress. ..."} |
422 |
A field failed a rule. A template or a collection that is not in your company also returns 422. |
{"message": "...", "errors": {...}} |
500 |
The render failed. | {"message": "..."} |
format: jpeg with transparent: true returns 422 with the message Transparency is not supported for the JPEG format.
Webhook
When an async snap completes, the instance posts {"event": "snap.completed", "snap": {...}} to webhook_url. A failed snap posts no webhook. See Webhooks.
Examples
A sync render:
curl -X POST https://snapsbrew.example/api/v1/snaps \
-H 'Authorization: Bearer <your-token>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{"template_id":"<uuid>","type":"image","variants":[{"layer":"review_title","text":"Hello world"}]}'
An async render with a webhook and an idempotency key:
curl -X POST https://snapsbrew.example/api/v1/snaps \
-H 'Authorization: Bearer <your-token>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{"template_id":"<uuid>","async":true,"webhook_url":"https://example.com/hooks/snap","idempotency_key":"order-1042-card"}'
The sync render in PHP, with a safe retry:
use Illuminate\Support\Facades\Http;
$response = Http::withToken(config('services.snapsbrew.token'))
->acceptJson()
->timeout(90)
->retry(2, 1000, throw: false)
->post('https://snapsbrew.example/api/v1/snaps', [
'template_id' => $templateUuid,
'format' => 'webp',
'variants' => [
['layer' => 'review_title', 'text' => 'Hello world'],
],
// The same key on each attempt. A retry returns the first snap.
'idempotency_key' => 'review-'.$review->id,
]);
$response->throw();
$url = $response->json('media_url');
$replayed = $response->header('X-Idempotent-Replay') === 'true';
A webhook receiver in Laravel:
use Illuminate\Http\Request;
Route::post('/hooks/snap', function (Request $request) {
if ($request->input('event') === 'snap.completed') {
$snapId = $request->input('snap.id');
$url = $request->input('snap.media_url');
// Store the URL.
}
return response()->noContent();
});
The webhook carries no signature. Put a secret value in the path or the query of webhook_url, and make sure that the receiver compares it.