Docs API
API overview
The base URL, authentication, response shapes, rate limits, errors, idempotency and webhooks of the Snapsbrew REST API.
The Snapsbrew REST API renders snaps from templates, and it manages templates, media, screenshots, batches and tags. Each instance serves its own API.
Base URL
The API is under /api on the URL of the instance. The version is part of each path.
https://snapsbrew.example/api/v1
APP_URL sets the host. The examples in these pages use https://snapsbrew.example.
Authentication
Most endpoints need an API token. An API token is a Sanctum personal access token with the api_requests ability.
Send the token as a bearer token in the Authorization header. Also send Accept: application/json, so that errors come back as JSON.
Authorization: Bearer <your-token>
Accept: application/json
Create an API token
- Sign in to the instance.
- Open Account, then open the Developers tab.
- Under API access tokens, type a name for the token.
- Click New token.
- Copy the token. The page shows it one time only.
The token does not expire. To stop a token, click Revoke next to it on the same tab.
If the owner deactivates a user, the API tokens of that user stop working. Requests with these tokens get 401.
Keep the token on your server. Do not put it in browser code or in a mobile app.
Token abilities
A token carries one or more abilities. The app uses two abilities.
| Ability | Given to | What it allows |
|---|---|---|
api_requests |
Each token that you make under API access tokens | The REST API and the MCP server. |
signed_url |
The token behind each signed-URL key | Signed image URLs only. See Signed URLs. |
A token without api_requests gets 403 with the message Invalid ability provided.
Endpoint groups
| Group | Page |
|---|---|
| The current token | Authentication |
| Static reference catalogs | Guides |
| Templates and publishing | Templates |
| The v2 draft of a template | Editor documents |
| Your image library | Media |
| Web page captures | Screenshots |
| One render | Snaps |
| Up to 100 renders | Snap batches |
| Watermarked HTML previews | Preview |
| Template labels | Tags |
| Form submissions without a token | Embedded forms |
| Public tools for a marketing site | Free tools |
The instance also serves an OpenAPI file and a Postman collection. See OpenAPI and Postman.
Response shapes
Most success bodies use one envelope:
- A read returns
{"data": ...}. - A list returns
{"data": [...], "meta": {...}}. - A write returns
{"data": ..., "message": "..."}. - A delete returns
{"message": "..."}only.
Some endpoints do not use this envelope. The page of each endpoint shows the exact body. These are the known differences:
POST /v1/snapsreturns the snap object with nodatakey.- The batch endpoints return the batch object with no
datakey. GET /v1/mediareturns the standard Laravel paginator.- The editor document endpoints return
documentandrevisionat the top level. POST /v1/templates/{templateUuid}/tagsreturnsmessageandtags.
Pagination
Two list styles exist.
Cursor pagination. GET /v1/templates and GET /v1/screenshots return meta.next_cursor and meta.previous_cursor. To read the next page, send the value of meta.next_cursor as the cursor query parameter. When meta.next_cursor is null, you have the last page.
Page pagination. GET /v1/media takes a page query parameter. The response has links and meta with current_page, per_page and total.
Rate limits
The instance counts requests for each user. If a request has no user, the instance counts it for the IP address.
| Limiter | Limit | Routes |
|---|---|---|
api |
60 requests a minute | Every route under /api/v1, except the embedded form route. |
preview |
10 requests a minute | GET /v1/templates/{templateUuid}/preview and GET /v1/snaps/preview. |
editor-document |
30 requests a minute for one user, and 180 a minute for one company | The four editor document routes. |
mcp |
30 requests a minute | The MCP server at /mcp. |
The preview and editor document routes also count against the api limiter.
POST /v1/embedded-forms/{formUuid} has no rate limit.
Each limited response carries these headers:
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 40
When you go over a limit, the response is 429. It also carries Retry-After (seconds) and X-RateLimit-Reset (a Unix timestamp). If you get 429, wait for the time in Retry-After. Then send the request again.
Errors
| Status | When | Body |
|---|---|---|
401 |
The token is missing, wrong, revoked or belongs to a deactivated user. | {"message": "Unauthenticated."} |
403 |
The token has no api_requests ability, or a policy refuses the action. |
{"message": "..."} |
404 |
The resource does not exist in your company. | {"message": "..."} |
409 |
A conflict: an idempotency key in progress, an editor document revision that moved, or a legacy edit of a v2 template. | {"message": "..."} or {"code": "..."} |
422 |
A field failed validation. | {"message": "...", "errors": {"field": ["..."]}} |
429 |
A rate limit is full. | {"message": "Too Many Attempts."} |
500 |
The render or the server failed. | {"message": "..."} |
A resource from another company returns 404, the same as a resource that does not exist.
Do not branch on the text of message. The text can change. Where an endpoint returns a code, branch on the code.
Request IDs
POST /v1/snaps, the batch endpoints and the embedded form route return an X-Request-Uuid header. The value is the ID of the row in the usage log. Keep it when you report a problem to the person who runs the instance.
Usage log
The usage log keeps a row for each logged request and the number of renders of that request. Routes that the logApiRequest middleware wraps go into the usage log:
GET /v1/authGET /v1/templates,GET /v1/templates/sizesandGET /v1/templates/{templateUuid}- The screenshot routes
- The tag routes
POST /v1/snapsand the batch routes
The guide routes, the preview routes, the media routes, the template writes and the editor document routes do not go into the usage log. Signed URLs and embedded forms write their own rows. Rendering has no limit. The usage log is a history only.
Idempotency keys
POST /v1/snaps and POST /v1/snaps/batches accept an idempotency_key. If a request times out, send the same request again with the same key. The instance then returns the first result and does not render again.
- A key has a maximum of 191 characters.
- A key accepts letters, digits, underscores and hyphens only.
- The instance keeps a key for 24 hours. After that, the same key starts a new render.
- A key belongs to your company.
- A replayed response carries the header
X-Idempotent-Replay: true. - If another request with the same key is still in progress, the response is
409. Nothing is created. Send the request again after a short wait. - A key that a single snap used returns
409on the batch endpoint. POST /v1/snapswithcollection_iddoes not accept a key.
The scheduler removes old keys every hour with php artisan snaps:prune-idempotency-keys. See Scheduler.
Webhooks
An async snap and a batch can post a webhook when they finish.
The webhook_url must be a public http or https address. If the host resolves to a private, loopback, link-local or reserved address, the request gets 422.
The instance posts JSON with Http::post(). It tries three times, with a short wait between the attempts. If all three attempts fail, the instance writes a warning to its log. The webhook request carries no signature.
Snap webhook. The instance posts it after an async snap completes. A failed snap posts no webhook.
{
"event": "snap.completed",
"snap": {
"id": "9f1c2d3e",
"media_url": "https://snapsbrew.example/storage/snaps/9f1c2d3e.png",
"type": "image",
"status": "completed",
"is_async": true,
"webhook_url": "https://example.com/hooks/snap",
"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"
}
}
Batch webhook. The instance posts one webhook when a batch reaches a terminal status. The event is snap-import.completed, snap-import.failed or snap-import.canceled.
{
"event": "snap-import.completed",
"import": {
"uuid": "7c1f2a9e-0b44-4a1e-9f2b-5d3c8e1a7b60",
"title": "October launch",
"status": "completed",
"total_rows": 2,
"processed_rows": 2,
"completed": 2,
"pending": 0,
"failed": 0,
"canceled": 0
},
"template": {
"uuid": "141e8454-8aa1-420a-bd0b-18a85ba949a2",
"title": "Launch card"
}
}
Public addresses for images
An image_url in variants must also be a public http or https address. The host of APP_URL is always accepted. The same rule applies to the url of a screenshot.
Code examples
The examples use curl and PHP. The PHP examples use the Laravel Http client. Each PHP example reads the token from your own configuration:
use Illuminate\Support\Facades\Http;
$token = config('services.snapsbrew.token');
$base = 'https://snapsbrew.example/api';
services.snapsbrew.token is a key in your own app, not in Snapsbrew. Put the token in your secret store.