SessionShot

Developers

Documentation

Everything you need to capture authenticated pages: authentication, allowed domains, the capture lifecycle, and error handling. Signed-in users get the same guide with live workspace state in the dashboard.

API referenceDashboard quickstart

Guides

Jump to a topic.

QuickstartFrom API key to first capture in four steps.AuthenticationBearer keys, the one-time reveal, and key rotation.Allowed domainsThe hostname allowlist every capture is checked against.Statuses and resultsqueued, processing, completed, failed — and signed URLs.ErrorsWhat each error code means and how to fix it.Security best practicesKey handling, URL hygiene, and allowlist discipline.

Quickstart

Four steps from a fresh workspace to a stored capture.

  1. Create an API key in the dashboard. The full secret is shown once — store it server-side.
  2. Add an allowed domain for the host you want to capture (for example app.example.com or *.example.com).
  3. Send a capture request:
terminal — create a capture
curl -X POST "https://sessionshot.com/api/captures" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "output": { "format": "png", "fullPage": true }
  }'
  1. Poll the status endpoint until the capture completes, then open the signed result URL.

Authentication

Every API request sends a workspace API key as a bearer token.

Keys look like ssk_live_… and are sent as Authorization: Bearer YOUR_API_KEY. SessionShot stores only a hash — the full secret exists exactly once, in the reveal panel at creation time. The short prefix shown in the dashboard key list is a label, not a credential.

Revoke a key at any time from the dashboard; revoked keys stop authenticating immediately. If a key may have leaked, revoke it and create a new one.

Allowed domains

A per-workspace hostname allowlist checked on every capture request.

A capture is only accepted when the target URL's hostname matches an active Project domain. Exact hostnames match one host; wildcards like *.example.com match every subdomain (but not the bare domain). Disabling a domain blocks future captures without deleting existing results.

Statuses and results

Captures are asynchronous. Poll the status endpoint with the same key.

terminal — check status
curl "https://sessionshot.com/api/captures/CAPTURE_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
  • queued — accepted and waiting for a worker.
  • processing — a worker is rendering the page.
  • completed — the response includes a short-lived signed result URL, format, size, and dimensions.
  • failed — the response includes a safe error code and message.

Result URLs expire by design

Signed URLs are short-lived (around ten minutes). Fetch the status endpoint again — or use the capture's dashboard detail page — to mint a fresh link. The stored result itself is unaffected.

Errors

Every error is returned as JSON with a stable code and a safe message.

  • 401 UNAUTHENTICATED — "Authentication is required"

    The Authorization header is missing or malformed. Send "Authorization: Bearer YOUR_API_KEY".

  • 401 UNAUTHENTICATED — "Invalid API key"

    Usually the short key prefix was sent instead of the full one-time secret. Also returned for revoked keys or keys from a different deployment.

  • 403 DOMAIN_NOT_ALLOWED

    The target hostname is not covered by an active allowed domain in your workspace.

  • 400 VALIDATION_ERROR

    Invalid body or URL. Target URLs must use HTTPS.

  • 413 PAYLOAD_TOO_LARGE

    The request body exceeds the maximum size.

  • 500 INTERNAL

    A server-side problem. Retry later; persistent failures indicate a configuration issue.

Captures stuck in queued usually mean the capture worker is not running — see status.

Security best practices

The habits that keep captures safe.

  • Store API keys server-side only — never in browser code.
  • Avoid long-lived secrets in URLs; prefer short-lived, scoped capture URLs generated by your backend.
  • Allow only the domains you actually capture, and disable ones you stop using.
  • Use selector-based redaction for sensitive on-page content.
  • Treat signed result URLs as sensitive while they are live.

More detail on the overall model is on the security page.

Dashboard guide

In-dashboard quickstartThe same guide with your live setup progress (sign-in required).Full API referenceComplete request and response schemas for both endpoints.