Ssnap DocsAPI response formats
Binary bytes, signed urls, queued acknowledgements, and the headers that come with them.
The capture endpoint answers in one of three shapes, chosen by your parameters.
Binary (default)
With no response or callback_url, the body is the rendered file itself.
HTTP/1.1 200 OK
Content-Type: image/jpeg
Content-Disposition: inline; filename="media_9f3c….jpg"
Cache-Control: private, max-age=0, no-store
X-Screenshot-Cached: false
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 299| Header | Meaning |
|---|---|
Content-Type | image/jpeg, image/png, image/webp or application/pdf. |
Content-Disposition | inline, with the generated filename. |
X-Screenshot-Cached | true when served from an earlier identical capture. |
Check the status code before writing the body to disk. Error responses are JSON, so a
blind --output will happily save an error object with an image file extension.
Signed url (response=url)
{
"url": "https://ssnap.cc/screenshots/0193ab…/file?expires=1758283200&signature=8f2c…",
"cached": true
}The link is signed and expires 24 hours after the response. It needs no API key, so it can be handed to a browser or embedded in an email, but treat it as a secret while it lives. Fetch and re-host the file if you need it for longer; stored captures are also subject to retention.
An invalid or expired signature returns 403; a capture whose file has been pruned
returns 404.
Queued (callback_url set)
HTTP/1.1 202 Accepted{
"status": "queued",
"message": "Screenshot queued; the result will be delivered to the callback URL."
}Nothing is rendered yet at this point: quota and subscription checks happen when the job runs, so a queued request can still end in an error, delivered as a webhook, not as an HTTP response. See Async callbacks.
Errors
Every failure is JSON with a human-readable error and a stable code:
{
"error": "Monthly screenshot limit reached",
"code": "quota_exceeded"
}Validation failures use Laravel's standard shape instead, with a message and a
per-field errors map. Both are covered in API error codes.