HTTP API Reference

This is the public HTTP API for Snap.

Base URL

https://snap.i2dev.com

Authentication

Pass your API key using either header:

http
Authorization: Bearer YOUR_API_KEY

or

http
x-api-key: YOUR_API_KEY

POST /v1/screenshots

Captures a screenshot of a URL (synchronous). Returns an imageUrl plus metadata.

Example request (copy/paste)

bash
curl -sS -X POST https://snap.i2dev.com/v1/screenshots   -H "Authorization: Bearer YOUR_API_KEY"   -H "Content-Type: application/json"   -d '{
    "url": "https://example.com",
    "format": "png",
    "fullPage": false,
    "viewport": { "width": 1280, "height": 720 },
    "waitUntil": "load"
  }'

Example response

json
{
  "jobId": "...",
  "request_id": "...",
  "imageUrl": "https://snap-i2dev-com.s3.amazonaws.com/...?X-Amz-...",
  "contentType": "image/png",
  "bytes": 12345,
  "durationMs": 987,
  "logs": [],
  "page_errors": []
}

Result URLs and retention

Use imageUrl to retrieve the finished screenshot. Authenticated result URLs are signed and expire. Synchronous results default to seven days; async results default to one hour. Both are deployment-configurable. Download or copy an artifact that must outlive its URL. logs and page_errors contain capture diagnostics and may be empty.

Async mode, when enabled

Set "async": true in the POST /v1/screenshots body to queue the render and return immediately. Then poll GET /v1/jobs/:id for status. If async mode is unavailable on the deployment, the API returns a 400 bad_request; synchronous capture remains available.

Async submit example

bash
curl -sS -X POST https://snap.i2dev.com/v1/screenshots   -H "Authorization: Bearer YOUR_API_KEY"   -H "Content-Type: application/json"   -d '{
    "url": "https://example.com",
    "format": "png",
    "async": true
  }'

Async submit response

json
{
  "jobId": "...",
  "request_id": "...",
  "status": "queued",
  "statusUrl": "https://snap.i2dev.com/v1/jobs/..."
}

Poll job status

bash
curl -sS -H "Authorization: Bearer YOUR_API_KEY"   https://snap.i2dev.com/v1/jobs/JOB_ID

Job status response (done)

json
{
  "jobId": "...",
  "status": "succeeded",
  "result": {
    "imageUrl": "https://snap-i2dev-com.s3.amazonaws.com/...?X-Amz-...",
    "contentType": "image/png",
    "bytes": 12345,
    "durationMs": 987
  }
}

Request body

FieldTypeRequiredDescription
urlstringYesThe URL to screenshot (public http/https only; SSRF protections enabled).
format"png" | "jpeg"NoDefault: png. The anonymous GET endpoint defaults to jpeg instead.
fullPagebooleanNoCapture full scrollable page. Default: false
viewport{ width, height }NoDefault: {"width":1280,"height":720}
waitUntil"load" | "domcontentloaded" | "networkidle"NoDefault: load. After this condition fires, the renderer always runs a best-effort settle pass (network quiescence up to 5s, font loading, brief animation delay) before capturing, so SPAs and lazy content typically render fully on the default setting.
waitForSelectorstringNoWait for a CSS selector before capturing.
timeoutMsnumberNoOverall render timeout (bounded by server max).
navTimeoutMsnumberNoNavigation timeout (bounded by server max).
timezoneIdstringNoExample: America/Toronto
localestringNoExample: en-US
extraHTTPHeadersobjectNoExtra request headers (string → string).
cookiesarrayNoCookies to set before navigation.
baselineTagstringNoOptional label included in the result's storage identity. It does not publish a Visual CI baseline.
compareWithTagstringNoOptional label included in the result's storage identity. It does not retrieve or diff a previous capture.
asyncbooleanNoQueue render and return immediately (requires async mode enabled).

Capturing authenticated pages safely

Supply headers and cookies from CI or repository secrets—never commit authorization values. Cookies must include the target domain. Use the least privilege and shortest lifetime possible, and avoid reusing long-lived personal sessions. Snap forwards these credentials while loading the target page. Header and cookie values are not part of the result's storage identity, so do not use one API key with identical URL/render options for multiple user sessions; a later capture can replace the earlier object.

Errors

Errors are returned as JSON and include a request_id. Include that ID when reporting issues.

json
{
  "error": "Invalid or missing API key",
  "code": "unauthorized",
  "request_id": "..."
}

Common HTTP status codes:

  • 400 bad_request / unsafe_url
  • 401 unauthorized
  • 429 rate_limited / too_many_inflight
  • 500 internal_server_error