Docs API
Snap batches
Render up to 100 snaps from one template in the background, read the progress and cancel a batch.
A batch renders up to 100 snaps from one template. Each item has its own variants. The batch always runs on the queue. See Batches for the web screens.
| Method | Path | What it does |
|---|---|---|
POST |
/v1/snaps/batches |
Starts a batch. |
GET |
/v1/snaps/batches/{batchUuid} |
Returns the progress and each item. |
POST |
/v1/snaps/batches/{batchUuid}/cancel |
Stops a batch that runs. |
For each endpoint:
- Auth: bearer token
- Ability:
api_requests - Rate limit:
api(60 a minute) - Usage log: yes
Each response carries an X-Request-Uuid header. The bodies have no data key.
The queue worker must run. See Queues and Horizon.
Batch status
A batch has one of five statuses:
| Status | Meaning |
|---|---|
pending |
The batch runs. |
processing |
The batch runs. |
completed |
The batch ran to the end, and one or more items rendered. Read the failed count too. |
failed |
No item rendered. |
canceled |
A person or a client canceled the batch. |
completed, failed and canceled are terminal. A batch never leaves a terminal status. At a terminal status, completed + failed + canceled is equal to total_rows.
Create a batch of snaps
POST /v1/snaps/batches
The response is always 202. The items render in the background. The API renders the published version of the template.
| Field | Type | Required | Rules | Description |
|---|---|---|---|---|
template_id |
string | Yes | A template UUID of your company | The template of each item. |
items |
array | Yes | 1 to 100 items | One entry for each snap. |
items[].variants |
array | No | The variant rules | The content for the layers of this item. |
items[].identifier |
string | No | Maximum 191 characters | Your name for this item. The default is item_1, item_2 and on. |
title |
string | No | Maximum 255 characters | The name of the batch in the web app. The default is API batch. |
webhook_url |
string | No | A public http or https URL, maximum 2048 characters |
The address of the one webhook at the end. |
type |
string | No | image or pdf |
The output type of each item. The default is image. |
format |
string | No | png, jpeg or webp |
The image format of each item. The default is png. |
transparent |
boolean | No | Not with jpeg |
A transparent background for each item. |
idempotency_key |
string | No | Maximum 191 characters. Letters, digits, _ and -. |
A key for a safe retry. |
type, format and transparent apply to each item. If an item needs a different format, put it in a different batch.
More than 100 items returns 422 and creates nothing. The instance never cuts the list.
{
"uuid": "7c1f2a9e-0b44-4a1e-9f2b-5d3c8e1a7b60",
"title": "October launch",
"status": "processing",
"total_rows": 3,
"processed_rows": 0,
"completed": 0,
"pending": 3,
"failed": 0,
"canceled": 0,
"status_url": "https://snapsbrew.example/api/v1/snaps/batches/7c1f2a9e-0b44-4a1e-9f2b-5d3c8e1a7b60"
}
| Status | Cause | Body |
|---|---|---|
202 |
The batch is on the queue. A replay of the same idempotency_key also returns 202 with X-Idempotent-Replay: true. |
The batch object. |
409 |
The key is in progress on another request, or a single snap already used the key. | {"message": "This idempotency_key already belongs to a single snap. Use a new key for a batch."} |
422 |
A field failed a rule. | {"message": "A batch accepts at most 100 items. Split the request into smaller batches.", "errors": {...}} |
Read a batch
GET /v1/snaps/batches/{batchUuid}
Returns the counts and each item. Read the batch every 5 seconds or so. Stop when status is completed, failed or canceled.
{
"uuid": "7c1f2a9e-0b44-4a1e-9f2b-5d3c8e1a7b60",
"title": "October launch",
"status": "completed",
"total_rows": 2,
"processed_rows": 2,
"completed": 1,
"pending": 0,
"failed": 1,
"canceled": 0,
"status_url": "https://snapsbrew.example/api/v1/snaps/batches/7c1f2a9e-0b44-4a1e-9f2b-5d3c8e1a7b60",
"items": [
{"id": "9f1c2d3e", "identifier": "row-1", "status": "completed", "media_url": "https://snapsbrew.example/storage/snaps/9f1c2d3e.png", "last_error": null},
{"id": "4b8a7c6d", "identifier": "row-2", "status": "failed", "media_url": null, "last_error": "Render failed."}
]
}
media_urlhas a value only on an item with statuscompleted.last_erroris the error text from the renderer. Show it to a person. Do not branch on it.- A batch of another company returns
404, the same as a batch that does not exist.
404 returns {"message": "No batch with that id exists in your account."}.
Cancel a batch
POST /v1/snaps/batches/{batchUuid}/cancel
Stops a batch that runs:
- An item that rendered keeps its image.
- An item that did not start gets the status
canceledand never renders. - An item that renders at that moment can still complete.
You cannot undo a cancel or continue a canceled batch. Start a new batch for the items that you still want.
200 returns the batch with its items, in the same shape as the read. A batch that is already terminal comes back with no change, so a second cancel is safe.
Webhook
If you send webhook_url, the instance posts one webhook when the batch reaches a terminal status. No item posts its own webhook.
The event is snap-import.completed, snap-import.failed or snap-import.canceled. The body has the counts in import and the template in template. See Webhooks.
Examples
curl -X POST https://snapsbrew.example/api/v1/snaps/batches \
-H 'Authorization: Bearer <your-token>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{"template_id":"<uuid>","title":"October launch","items":[{"identifier":"row-1","variants":[{"layer":"headline","text":"Hello"}]},{"identifier":"row-2","variants":[{"layer":"headline","text":"World"}]}]}'
curl https://snapsbrew.example/api/v1/snaps/batches/<batch-uuid> \
-H 'Authorization: Bearer <your-token>' \
-H 'Accept: application/json'
curl -X POST https://snapsbrew.example/api/v1/snaps/batches/<batch-uuid>/cancel \
-H 'Authorization: Bearer <your-token>' \
-H 'Accept: application/json'
Start a batch and read it until it ends, in PHP:
use Illuminate\Support\Facades\Http;
$api = Http::withToken(config('services.snapsbrew.token'))
->acceptJson()
->baseUrl('https://snapsbrew.example/api');
$items = collect($products)->map(fn ($product) => [
'identifier' => 'product-'.$product->id,
'variants' => [
['layer' => 'headline', 'text' => $product->name],
['layer' => 'photo', 'image_url' => $product->image_url],
],
])->all();
$batch = $api->post('/v1/snaps/batches', [
'template_id' => $templateUuid,
'title' => 'Product cards',
'items' => $items,
'idempotency_key' => 'product-cards-2026-10',
])->throw()->json();
do {
sleep(5);
$batch = $api->get("/v1/snaps/batches/{$batch['uuid']}")->throw()->json();
} while (! in_array($batch['status'], ['completed', 'failed', 'canceled'], true));
foreach ($batch['items'] as $item) {
if ($item['status'] === 'completed') {
// Store $item['media_url'] for $item['identifier'].
}
}