CURL GUIDE

Test every screenshot workflow from the command line

Use cURL to verify authentication, request fields, and response handling before adding an SDK. Start with a public test URL, keep the key in an environment variable, and inspect both status and JSON.

One command

Fast API test

4 endpoints

Capture and analysis

Server-side

Private credential

Install:export SNAPSHOT_SITE_API_KEY='ss_live_xxx'

Auth:SNAPSHOT_SITE_API_KEY

Get started for free

cURL request workflow

Snapshot Site themed screenshot API cURL illustration

Good fits

Developers validating credentials and endpoints

CI jobs with a controlled shell environment

Support teams reproducing a request safely

SDK authors checking the raw REST contract

A useful cURL test checks more than pixels

Treat the command as a small integration test: protect the secret, make state explicit, save headers, and handle non-success responses.

Private key

Read the credential from a protected environment variable instead of committing it in shell history or scripts.

Explicit JSON

Specify URL, viewport, format, full-page choice, timing, and cleanup required by the use case.

Visible status

Use fail-with-body and response inspection so an error document is not mistaken for a generated asset.

Stored evidence

Save the response and request context when the command is part of a repeatable CI or support procedure.

Implementation workflow

Run a dependable cURL capture

Export the API key in a protected terminal session

Choose an authorized HTTP or HTTPS target

POST JSON with the documented authentication header

Inspect the status and validate the returned fields

cURL screenshot API examples

cURL

Capture a full-page WebP

The fail-with-body option keeps an HTTP error visible while returning a failing process status.

curl --fail-with-body --silent --show-error \
  --request POST \
  --url https://api.prod.ss.snapshot-site.com/api/v1/screenshot \
  --header "x-snapshotsiteapi-key: $SNAPSHOT_SITE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "url": "https://example.com",
    "format": "webp",
    "width": 1440,
    "height": 900,
    "fullSize": true,
    "hideCookie": true,
    "delay": 2
  }'

cURL

Compare two public page states

Use the compare endpoint when the intended result is a before-and-after visual artifact.

curl --fail-with-body --silent --show-error \
  --request POST \
  --url https://api.prod.ss.snapshot-site.com/api/v3/compare \
  --header "x-snapshotsiteapi-key: $SNAPSHOT_SITE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "beforeUrl": "https://example.com/before",
    "afterUrl": "https://example.com/after",
    "width": 1440,
    "height": 900
  }'

Use cURL as a contract probe

cURL is the shortest route between documentation and the live HTTP contract. It is ideal for confirming a credential, isolating an SDK problem, or creating a minimal support reproduction. A successful command should make every important input visible without leaking a secret.

Run experiments against a harmless public fixture before a production URL. Change one field at a time and save the response status as well as the body. This produces a clearer diagnosis than repeatedly modifying an application integration.

Shell safety matters

Environment variables reduce accidental copying, but they are not a complete secret-management system. Avoid verbose output in shared logs, unset temporary values after use, and rely on CI secret injection in automation. Do not include signed preview tokens or private output URLs in tickets.

Quote JSON deliberately. Shell expansion, smart quotes, and copied line continuations can all change a request before it reaches the service.

From experiment to production

A cURL command does not provide job ownership, retry policy, rate control, storage, or access control. When a capture becomes a product feature, move the validated contract into a backend service or SDK and add those operational layers.

Continue with the authentication guide, then use error handling to decide which failures are safe to retry.

Screenshot API with cURL FAQ

Which header authenticates cURL requests?

Send the private key in the x-snapshotsiteapi-key request header. Use the current API documentation as the source of truth for endpoint contracts.

Should I place the key directly in the command?

Avoid it. Inline secrets can enter shell history, CI logs, process listings, and copied support transcripts. Read from a protected environment variable or secret injection.

Why use --fail-with-body?

It returns a failing process status for HTTP errors while retaining the response body for diagnosis, which is useful in scripts and CI.

Can cURL download the returned image automatically?

Inspect the response contract first, then download the returned authorized asset with a separate validated request when appropriate.

How do I debug malformed JSON?

Store the payload in a reviewed file or use a here document locally, validate it with a JSON parser, and keep secrets outside the payload.

Can I use cURL for high-volume batch capture?

It can launch requests, but a queue-aware application or CLI provides better concurrency, retry, idempotency, and observability.

Does the screenshot endpoint accept local file paths?

No. Supply a reachable HTTP or HTTPS URL that the rendering service is authorized to access.

When should I switch to an SDK?

Use an SDK when typed request objects, shared error mapping, download helpers, and application-level tests improve maintainability.

Related resources

Snapshot Site Home Website Screenshot API API Documentation TypeScript SDK Screenshot API Examples Pricing Authentication Guide Error Handling CLI

Verify your first request with cURL

Use an authorized test page and explicit viewport, then preserve the successful payload as a reviewed integration fixture.

Get started for free Read the API docs