Skip to content
ScreenshotDude

Core concepts

Global parameters

Parameters accepted by every billable endpoint — soft_fail, is_async, fields and webhook_url.

These parameters work on /v1/capture, /v1/content, /v1/analyze and /v1/website/crawler.

Parameter Type Default Description
soft_fail boolean false Return HTTP 200 even on errors, with the message in error.
is_async boolean false Queue the request and return a job_id immediately.
fields string — Comma-separated list of response fields to keep.
webhook_url string — With is_async=true, POST the finished job to this URL. Paid plans.

soft_fail

Many no-code tools (Zapier, Make, n8n) halt a workflow on any non-2xx response. With soft_fail=true errors come back as 200:

{ "success": false, "error": "Insufficient credits: 1 required, 0 available" }

Errors are still never billed. Your workflow must check error to branch.

is_async

curl -G "http://localhost:4000/v1/content" \
  --data-urlencode "url=https://example.com" \
  -d include_markdown=true -d is_async=true \
  -H "x-api-key: $SNAPLENS_API_KEY"
{ "success": true, "job_id": "job_4f8k2m9q1x7c3v5b6n0z8l2p", "status": "Queued" }

The 202 response is free; you're billed when the job completes successfully. Poll /v1/jobs/{id} or use webhook_url. See Async jobs.

fields

fields trims JSON responses to what you need. Use commas to list fields and dots for nested fields:

# keep only the title and internal links
-d fields=metadata.title,links.internal

Rules:

  • Dot notation selects nested fields: metadata.ogImage.
  • For responses shaped { success, data: { … } }, paths are resolved inside data and the envelope is kept: fields=metadata.title returns { "success": true, "data": { "metadata": { "title": "…" } } }.
  • If a path starts with a top-level key (for example data.markdown), it's applied to the whole body instead.
  • Arrays: a path applies to every element. fields=redirects.status on the crawler returns each redirect with only its status.
  • Unknown fields are ignored silently.
  • fields has no effect on binary responses (screenshots).

Example on the content API:

curl -G "http://localhost:4000/v1/content" \
  --data-urlencode "url=https://example.com" \
  -d fields=metadata.title,metadata.description,links.social \
  -H "x-api-key: $SNAPLENS_API_KEY"
{
  "success": true,
  "data": {
    "metadata": { "title": "Example Domain", "description": "…" },
    "links": { "social": [] }
  }
}

webhook_url

Requires is_async=true. When the job finishes (successfully or not), we POST the job object to your URL with an x-snaplens-signature header. Available on paid plans. See Webhooks.

x_api_key (deprecated)

The API key can also be passed as the x_api_key query parameter. This is deprecated — query strings are logged by proxies and servers. Use the x-api-key header.