API reference

Health check

Liveness probe for the API.

Auth: None (public)

No required parameters.

Request

curl -X GET 'https://api.sitescreens.com/v1/health'

Response HTTP 200

{
  "ok": true,
  "service": "sitescreens-api"
}

Plan catalog

Public plan definitions, features, and credit allotments.

Auth: None (public)

No required parameters.

Request

curl -X GET 'https://api.sitescreens.com/v1/plans'

Response HTTP 200

{
  "plans": [
    {
      "id": "starter",
      "name": "Starter",
      "creditsPerMonth": 2000,
      "features": {
        "crawl": true,
        "batch": true,
        "video": false
      }
    }
  ]
}

Create screenshot job

Queue a viewport or full-page screenshot. Free plans may watermark results. Poll GET /v1/jobs/:id for status and signed artifact URLs.

Auth: API key or session required

Required parameters

Optional parameters

Request

{
  "url": "https://example.com",
  "device": "mobile",
  "resolution": "mobile_390x844",
  "fullPage": false,
  "format": "png",
  "overlayMode": "cut"
}

Response HTTP 202

{
  "jobId": "job_01HXYZ...",
  "reservedCredits": 1,
  "status": "queued"
}

Create scrape job (PDF / text / markdown)

Queue a PDF export or text/markdown extraction. Relative links in markdown/text are rewritten to absolute URLs. Requires Starter+.

Auth: API key or session required

Required parameters

Optional parameters

Request

{
  "url": "https://example.com",
  "format": "markdown",
  "overlays": {
    "ads": "cut"
  }
}

Response HTTP 202

{
  "jobId": "job_01HXYZ...",
  "reservedCredits": 2,
  "status": "queued"
}

• For text/markdown, set overlays.ads to "cut" to purge in-content ad units before extraction.

Create crawl job

Crawl a site into a multi-page markdown pack plus JSONL for agents and RAG. Requires Starter+. maxPages is capped by your plan.

Auth: API key or session required

Required parameters

Optional parameters

Request

{
  "url": "https://example.com",
  "maxPages": 10,
  "maxDepth": 2,
  "overlayMode": "cut"
}

Response HTTP 202

{
  "jobId": "job_01HXYZ...",
  "reservedCredits": 10,
  "status": "queued"
}

Create scroll video job

Record a short scrolling product-demo video (WebM or MP4). Requires Pro+.

Auth: API key or session required

Required parameters

Optional parameters

Request

{
  "url": "https://example.com",
  "seconds": 8,
  "format": "webm",
  "scroll": true,
  "device": "desktop"
}

Response HTTP 202

{
  "jobId": "job_01HXYZ...",
  "reservedCredits": 10,
  "status": "queued"
}

Create forensic evidence pack

Capture a timestamped evidence pack: screenshot, content hash, and manifest. Optionally mark artifacts immutable so they cannot be deleted. Requires Starter+.

Auth: API key or session required

Required parameters

Optional parameters

Request

{
  "url": "https://example.com",
  "immutable": true,
  "includeMarkdown": true,
  "fullPage": true
}

Response HTTP 202

{
  "jobId": "job_01HXYZ...",
  "reservedCredits": 3,
  "status": "queued"
}

Create structured extract job

Extract structured JSON from a page according to your schema. Relative URL strings in the result are rewritten to absolute URLs. Requires Pro+.

Auth: API key or session required

Required parameters

Optional parameters

Request

{
  "url": "https://example.com",
  "schema": {
    "type": "object",
    "properties": {
      "title": {
        "type": "string"
      },
      "price": {
        "type": "string"
      }
    },
    "required": [
      "title"
    ]
  }
}

Response HTTP 202

{
  "jobId": "job_01HXYZ...",
  "reservedCredits": 7,
  "status": "queued"
}

Create page/site summary job

Scrape a single URL, an explicit URL list, or crawl a site, then produce per-page summaries plus an overall rollup. Requires Pro+ and a configured LLM endpoint on the worker. Credits: 5 per page summarized (+ proxy).

Auth: API key or session required

No required parameters.

Optional parameters

Request

{
  "url": "https://example.com",
  "crawl": true,
  "maxPages": 10,
  "maxDepth": 2,
  "length": "medium"
}

Response HTTP 202

{
  "jobId": "job_01HXYZ...",
  "reservedCredits": 50,
  "status": "queued"
}

• Artifacts: summary.json (structured), summary.md (human-readable), pages.jsonl (per-page rows).
• Settled credits scale with pages actually summarized (minimum 1 page).

List jobs

List jobs for your organization with optional filters and pagination.

Auth: API key or session required

No required parameters.

Optional parameters

Request

curl -X GET 'https://api.sitescreens.com/v1/jobs?status=succeeded&limit=25&offset=0' \
  -H 'Authorization: Bearer ssk_your_api_key'

Response HTTP 200

{
  "jobs": [
    {
      "id": "job_01HXYZ...",
      "kind": "screenshot",
      "status": "succeeded",
      "url": "https://example.com",
      "reservedCredits": 1,
      "settledCredits": 1,
      "createdAt": "2026-08-11T10:00:00.000Z",
      "faviconUrl": "https://api.sitescreens.com/v1/files?key=...&sig=..."
    }
  ],
  "total": 1,
  "limit": 25,
  "offset": 0
}

Get job

Fetch a single job including signed artifact download URLs (typically valid ~1 hour).

Auth: API key or session required

Required parameters

Request

curl -X GET 'https://api.sitescreens.com/v1/jobs/job_01HXYZ...' \
  -H 'Authorization: Bearer ssk_your_api_key'

Response HTTP 200

{
  "job": {
    "id": "job_01HXYZ...",
    "kind": "screenshot",
    "status": "succeeded",
    "url": "https://example.com",
    "reservedCredits": 1,
    "settledCredits": 1,
    "error": null,
    "meta": {
      "overlaysDetected": []
    },
    "createdAt": "2026-08-11T10:00:00.000Z",
    "finishedAt": "2026-08-11T10:00:08.000Z",
    "artifacts": [
      {
        "id": "art_01...",
        "contentType": "image/png",
        "byteSize": 184220,
        "contentHash": "sha256:…",
        "watermarked": false,
        "immutable": false,
        "url": "https://api.sitescreens.com/v1/artifacts/art_01...?exp=...&sig=..."
      }
    ]
  }
}

Delete artifact

Soft-delete an artifact you own. Immutable forensic artifacts cannot be deleted.

Auth: API key or session required

Required parameters

Request

curl -X DELETE 'https://api.sitescreens.com/v1/artifacts/art_01...' \
  -H 'Authorization: Bearer ssk_your_api_key'

Response HTTP 200

{
  "ok": true
}

• Returns 403 if the artifact is marked immutable.

Download artifact (signed URL)

Binary download for an artifact. Requires a valid exp and sig query signature from a job response — not an API key.

Auth: None (public)

Required parameters

Request

curl -X GET 'https://api.sitescreens.com/v1/artifacts/art_01...?exp=1723370000&sig=%E2%80%A6'

Response HTTP 200

{
  "note": "Binary response body with Content-Type from the artifact (image/png, application/pdf, text/markdown, …)."
}

• Use the full signed URL from GET /v1/jobs/:id rather than reconstructing signatures.

Queue a batch of URLs

Enqueue many URLs in one request. Per-URL failures are returned in results without failing the whole batch. Requires Starter+. URL count is limited by plan maxBatchSize.

Auth: API key or session required

Required parameters

Optional parameters

Request

{
  "kind": "screenshot",
  "urls": [
    "https://example.com",
    "https://example.org"
  ],
  "options": {
    "device": "desktop",
    "fullPage": false,
    "overlayMode": "cut"
  }
}

Response HTTP 202

{
  "batchSize": 2,
  "queued": 2,
  "failed": 0,
  "results": [
    {
      "url": "https://example.com",
      "jobId": "job_01...",
      "reservedCredits": 1
    },
    {
      "url": "https://example.org",
      "jobId": "job_02...",
      "reservedCredits": 1
    }
  ]
}

List monitors

List change monitors for your organization.

Auth: API key or session required

No required parameters.

Request

curl -X GET 'https://api.sitescreens.com/v1/monitors' \
  -H 'Authorization: Bearer ssk_your_api_key'

Response HTTP 200

{
  "monitors": [
    {
      "id": "mon_01...",
      "name": "example.com",
      "url": "https://example.com",
      "intervalMinutes": 60,
      "thresholdPercent": 2,
      "enabled": true,
      "lastCheckedAt": "2026-08-11T09:00:00.000Z",
      "nextRunAt": "2026-08-11T10:00:00.000Z"
    }
  ]
}

Create monitor

Schedule recurring visual/content checks. Requires Starter+. Count limited by plan.

Auth: API key or session required

Required parameters

Optional parameters

Request

{
  "url": "https://example.com",
  "intervalMinutes": 60,
  "thresholdPercent": 2,
  "overlayMode": "cut"
}

Response HTTP 201

{
  "monitor": {
    "id": "mon_01...",
    "name": "example.com",
    "url": "https://example.com",
    "intervalMinutes": 60,
    "thresholdPercent": 2,
    "enabled": true
  }
}

Get monitor

Fetch a single monitor by id.

Auth: API key or session required

Required parameters

Request

curl -X GET 'https://api.sitescreens.com/v1/monitors/mon_01...' \
  -H 'Authorization: Bearer ssk_your_api_key'

Response HTTP 200

{
  "monitor": {
    "id": "mon_01...",
    "name": "example.com",
    "url": "https://example.com",
    "intervalMinutes": 60,
    "enabled": true
  }
}

Update monitor

Partial update of monitor settings. Body fields match create (all optional).

Auth: API key or session required

Required parameters

Optional parameters

Request

{
  "enabled": false,
  "intervalMinutes": 120
}

Response HTTP 200

{
  "monitor": {
    "id": "mon_01...",
    "enabled": false,
    "intervalMinutes": 120
  }
}

Delete monitor

Remove a monitor.

Auth: API key or session required

Required parameters

Request

curl -X DELETE 'https://api.sitescreens.com/v1/monitors/mon_01...' \
  -H 'Authorization: Bearer ssk_your_api_key'

Response HTTP 200

{
  "ok": true
}

Monitor history

Recent monitor runs with change flags and screenshot URLs.

Auth: API key or session required

Required parameters

Optional parameters

Request

curl -X GET 'https://api.sitescreens.com/v1/monitors/mon_01.../history?limit=20' \
  -H 'Authorization: Bearer ssk_your_api_key'

Response HTTP 200

{
  "monitor": {
    "id": "mon_01...",
    "url": "https://example.com"
  },
  "runs": [
    {
      "id": "run_01...",
      "jobId": "job_01...",
      "changed": true,
      "contentChanged": true,
      "visualChanged": true,
      "diffPercent": 4.2,
      "createdAt": "2026-08-11T09:00:00.000Z",
      "screenshotUrl": "https://api.sitescreens.com/v1/artifacts/...?exp=...&sig=..."
    }
  ]
}

Compare monitor runs

Side-by-side comparison of two monitor runs.

Auth: API key or session required

Required parameters

Request

curl -X GET 'https://api.sitescreens.com/v1/monitors/mon_01.../compare?left=run_01...&right=run_02...' \
  -H 'Authorization: Bearer ssk_your_api_key'

Response HTTP 200

{
  "monitor": {
    "id": "mon_01..."
  },
  "left": {
    "id": "run_01...",
    "screenshot": {
      "url": "…"
    }
  },
  "right": {
    "id": "run_02...",
    "screenshot": {
      "url": "…"
    }
  }
}

List RAG sources

List allowlisted RAG sync sources. Requires Pro+ to create/sync.

Auth: API key or session required

No required parameters.

Request

curl -X GET 'https://api.sitescreens.com/v1/rag/sources' \
  -H 'Authorization: Bearer ssk_your_api_key'

Response HTTP 200

{
  "sources": [
    {
      "id": "rag_01...",
      "name": "example.com",
      "startUrl": "https://example.com",
      "allowlistHosts": [
        "example.com"
      ],
      "maxPages": 25,
      "enabled": true
    }
  ]
}

Create RAG source

Add an allowlisted site for recurring knowledge-pack sync. Requires Pro+.

Auth: API key or session required

Required parameters

Optional parameters

Request

{
  "startUrl": "https://example.com/docs",
  "allowlistHosts": [
    "example.com"
  ],
  "maxPages": 25,
  "intervalMinutes": 1440
}

Response HTTP 201

{
  "source": {
    "id": "rag_01...",
    "startUrl": "https://example.com/docs",
    "allowlistHosts": [
      "example.com"
    ]
  }
}

Get RAG source

Fetch one RAG source.

Auth: API key or session required

Required parameters

Request

curl -X GET 'https://api.sitescreens.com/v1/rag/sources/rag_01...' \
  -H 'Authorization: Bearer ssk_your_api_key'

Response HTTP 200

{
  "source": {
    "id": "rag_01...",
    "startUrl": "https://example.com"
  }
}

Update RAG source

Partial update. Body fields match create (all optional).

Auth: API key or session required

Required parameters

Optional parameters

Request

{
  "enabled": true,
  "maxPages": 40
}

Response HTTP 200

{
  "source": {
    "id": "rag_01...",
    "maxPages": 40,
    "enabled": true
  }
}

Delete RAG source

Remove a RAG source.

Auth: API key or session required

Required parameters

Request

curl -X DELETE 'https://api.sitescreens.com/v1/rag/sources/rag_01...' \
  -H 'Authorization: Bearer ssk_your_api_key'

Response HTTP 200

{
  "ok": true
}

Trigger RAG sync

Enqueue an immediate rag_sync job for the source. Requires Pro+.

Auth: API key or session required

Required parameters

Request

curl -X POST 'https://api.sitescreens.com/v1/rag/sources/rag_01.../sync' \
  -H 'Authorization: Bearer ssk_your_api_key'

Response HTTP 202

{
  "jobId": "job_01HXYZ...",
  "reservedCredits": 1,
  "status": "queued"
}

• Webhook event on completion: rag.synced.

List knowledge packs

List versioned knowledge packs produced by RAG sync.

Auth: API key or session required

No required parameters.

Optional parameters

Request

curl -X GET 'https://api.sitescreens.com/v1/rag/packs?ragSourceId=rag_01...' \
  -H 'Authorization: Bearer ssk_your_api_key'

Response HTTP 200

{
  "packs": [
    {
      "id": "pack_01...",
      "ragSourceId": "rag_01...",
      "version": 3,
      "createdAt": "2026-08-11T08:00:00.000Z"
    }
  ]
}

Get knowledge pack

Fetch a pack and its signed artifact URLs (markdown/JSONL).

Auth: API key or session required

Required parameters

Request

curl -X GET 'https://api.sitescreens.com/v1/rag/packs/pack_01...' \
  -H 'Authorization: Bearer ssk_your_api_key'

Response HTTP 200

{
  "pack": {
    "id": "pack_01...",
    "version": 3,
    "artifacts": [
      {
        "id": "art_01...",
        "contentType": "text/markdown",
        "url": "https://api.sitescreens.com/v1/artifacts/art_01...?exp=...&sig=..."
      }
    ]
  }
}

List API keys

List active API keys and period spend summaries. Secrets are never returned here.

Auth: API key or session required

No required parameters.

Request

curl -X GET 'https://api.sitescreens.com/v1/keys' \
  -H 'Authorization: Bearer ssk_your_api_key'

Response HTTP 200

{
  "keys": [
    {
      "id": "key_01...",
      "name": "Production",
      "keyPrefix": "ssk_live_ab12",
      "dailyCreditLimit": 1000,
      "weeklyCreditLimit": null,
      "monthlyCreditLimit": null,
      "spentToday": 42,
      "spentThisWeek": 210,
      "spentThisMonth": 880,
      "createdAt": "2026-07-01T00:00:00.000Z"
    }
  ]
}

Create API key

Create a new API key. The full secret is returned once — store it securely.

Auth: API key or session required

No required parameters.

Optional parameters

Request

{
  "name": "CI"
}

Response HTTP 200

{
  "key": {
    "id": "key_01...",
    "name": "CI",
    "keyPrefix": "ssk_live_zz99",
    "dailyCreditLimit": null,
    "weeklyCreditLimit": null,
    "monthlyCreditLimit": null,
    "secret": "ssk_live_zz99…full_secret_once"
  }
}

Update API key

Rename a key or set daily/weekly/monthly credit limits. null clears a limit (unlimited).

Auth: API key or session required

Required parameters

Optional parameters

Request

{
  "dailyCreditLimit": 500,
  "weeklyCreditLimit": 2000
}

Response HTTP 200

{
  "key": {
    "id": "key_01...",
    "name": "CI",
    "dailyCreditLimit": 500,
    "weeklyCreditLimit": 2000,
    "monthlyCreditLimit": null,
    "spentToday": 42
  }
}

Revoke API key

Immediately revoke an API key.

Auth: API key or session required

Required parameters

Request

curl -X DELETE 'https://api.sitescreens.com/v1/keys/key_01...' \
  -H 'Authorization: Bearer ssk_your_api_key'

Response HTTP 200

{
  "ok": true
}

Get org webhook settings

Read the organization webhook URL and whether an HMAC secret is configured.

Auth: API key or session required

No required parameters.

Request

curl -X GET 'https://api.sitescreens.com/v1/settings/webhook' \
  -H 'Authorization: Bearer ssk_your_api_key'

Response HTTP 200

{
  "webhookUrl": "https://hooks.example.com/sitescreens",
  "hasSecret": true
}

Update org webhook settings

Set or clear the organization webhook URL and optionally rotate the HMAC signing secret.

Auth: API key or session required

No required parameters.

Optional parameters

Request

{
  "webhookUrl": "https://hooks.example.com/sitescreens",
  "rotateSecret": true
}

Response HTTP 200

{
  "ok": true,
  "webhookSecret": "a1b2c3…"
}

• Events: job.succeeded, job.failed, monitor.changed, monitor.unchanged, rag.synced.
• Signature header: X-Sitescreens-Signature: sha256=<hmac>.

Credit ledger

Recent credit ledger entries for your organization (latest 50).

Auth: API key or session required

No required parameters.

Request

curl -X GET 'https://api.sitescreens.com/v1/usage' \
  -H 'Authorization: Bearer ssk_your_api_key'

Response HTTP 200

{
  "ledger": [
    {
      "id": "led_01...",
      "jobId": "job_01...",
      "delta": -1,
      "balanceAfter": 999,
      "reason": "reserve",
      "createdAt": "2026-08-11T10:00:00.000Z"
    }
  ]
}