API-Referenz

Health-Check

Liveness-Probe für die 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"
}

Tarifkatalog

Öffentliche Tarifdefinitionen, Funktionen und Credit-Kontingente.

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
      }
    }
  ]
}

Screenshot-Job erstellen

Viewport- oder Full-Page-Screenshot in die Warteschlange stellen. Free-Tarife können Ergebnisse mit Wasserzeichen versehen. Status und signierte Artefakt-URLs über GET /v1/jobs/:id pollen.

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"
}

Scrape-Job erstellen (PDF / Text / Markdown)

PDF-Export oder Text-/Markdown-Extraktion in die Warteschlange stellen. Relative Links in Markdown/Text werden in absolute URLs umgeschrieben. Erfordert 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"
}

• Für Text/Markdown setzen Sie overlays.ads auf "cut", um In-Content-Werbeeinheiten vor der Extraktion zu entfernen.

Crawl-Job erstellen

Eine Website in ein mehrseitiges Markdown-Paket plus JSONL für Agents und RAG crawlen. Erfordert Starter+. maxPages wird durch Ihren Tarif begrenzt.

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"
}

Scroll-Video-Job erstellen

Kurzes scrollendes Produkt-Demo-Video aufzeichnen (WebM oder MP4). Erfordert 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"
}

Forensisches Evidence-Paket erstellen

Zeitgestempeltes Evidence-Paket erfassen: Screenshot, Content-Hash und Manifest. Artefakte optional als unveränderlich markieren, damit sie nicht gelöscht werden können. Erfordert 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"
}

Strukturierten Extract-Job erstellen

Strukturiertes JSON von einer Seite gemäss Ihrem Schema extrahieren. Relative URL-Strings im Ergebnis werden in absolute URLs umgeschrieben. Erfordert 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"
}

Zusammenfassungs-Job erstellen

Eine einzelne URL, eine URL-Liste oder eine Website crawlen und pro Seite sowie als Gesamtüberblick zusammenfassen. Erfordert Pro+ und einen konfigurierten LLM-Endpunkt am Worker. Credits: 5 pro zusammengefasster Seite (+ 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).

Jobs auflisten

Jobs Ihrer Organisation mit optionalen Filtern und Paginierung auflisten.

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
}

Job abrufen

Einen einzelnen Job einschliesslich signierter Artefakt-Download-URLs abrufen (typischerweise ca. 1 Stunde gültig).

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=..."
      }
    ]
  }
}

Artefakt löschen

Ein Artefakt, das Ihnen gehört, soft-löschen. Unveränderliche forensische Artefakte können nicht gelöscht werden.

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
}

• Gibt 403 zurück, wenn das Artefakt als unveränderlich markiert ist.

Artefakt herunterladen (signierte URL)

Binärer Download für ein Artefakt. Erfordert eine gültige exp- und sig-Query-Signatur aus einer Job-Antwort — keinen API-Schlüssel.

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, …)."
}

• Verwenden Sie die vollständige signierte URL aus GET /v1/jobs/:id statt Signaturen selbst zu rekonstruieren.

Batch von URLs einreihen

Viele URLs in einer Anfrage einreihen. Fehler pro URL werden in results zurückgegeben, ohne den gesamten Batch scheitern zu lassen. Erfordert Starter+. Die URL-Anzahl ist durch plan maxBatchSize begrenzt.

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
    }
  ]
}

Monitore auflisten

Change-Monitore Ihrer Organisation auflisten.

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"
    }
  ]
}

Monitor erstellen

Wiederkehrende visuelle/inhaltsbezogene Prüfungen planen. Erfordert Starter+. Anzahl tarifabhängig begrenzt.

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
  }
}

Monitor abrufen

Einen einzelnen Monitor anhand der ID abrufen.

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
  }
}

Monitor aktualisieren

Teilaktualisierung der Monitor-Einstellungen. Body-Felder entsprechen Create (alle 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
  }
}

Monitor löschen

Einen Monitor entfernen.

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-Verlauf

Aktuelle Monitor-Läufe mit Änderungsflags und 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=..."
    }
  ]
}

Monitor-Läufe vergleichen

Seiten-an-Seiten-Vergleich zweier Monitor-Läufe.

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": "…"
    }
  }
}

RAG-Quellen auflisten

Allowlistete RAG-Sync-Quellen auflisten. Erstellen/Sync erfordert Pro+.

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
    }
  ]
}

RAG-Quelle erstellen

Eine allowlistete Website für wiederkehrenden Knowledge-Pack-Sync hinzufügen. Erfordert 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"
    ]
  }
}

RAG-Quelle abrufen

Eine RAG-Quelle abrufen.

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"
  }
}

RAG-Quelle aktualisieren

Teilaktualisierung. Body-Felder entsprechen Create (alle 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
  }
}

RAG-Quelle löschen

Eine RAG-Quelle entfernen.

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
}

RAG-Sync auslösen

Sofortigen rag_sync-Job für die Quelle einreihen. Erfordert 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-Ereignis bei Abschluss: rag.synced.

Knowledge-Packs auflisten

Versionierte Knowledge-Packs aus dem RAG-Sync auflisten.

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"
    }
  ]
}

Knowledge-Pack abrufen

Ein Pack und seine signierten Artefakt-URLs (Markdown/JSONL) abrufen.

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=..."
      }
    ]
  }
}

API-Schlüssel auflisten

Aktive API-Schlüssel und Perioden-Ausgabenübersichten auflisten. Secrets werden hier nie zurückgegeben.

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"
    }
  ]
}

API-Schlüssel erstellen

Einen neuen API-Schlüssel erstellen. Das vollständige Secret wird einmal zurückgegeben — sicher speichern.

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"
  }
}

API-Schlüssel aktualisieren

Schlüssel umbenennen oder tägliche/wöchentliche/monatliche Credit-Limits setzen. null hebt ein Limit auf (unbegrenzt).

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
  }
}

API-Schlüssel widerrufen

Einen API-Schlüssel sofort widerrufen.

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
}

Org-Webhook-Einstellungen abrufen

Organisations-Webhook-URL und ob ein HMAC-Secret konfiguriert ist lesen.

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
}

Org-Webhook-Einstellungen aktualisieren

Organisations-Webhook-URL setzen oder löschen und optional das HMAC-Signatur-Secret rotieren.

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…"
}

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

Credit-Ledger

Aktuelle Credit-Ledger-Einträge Ihrer Organisation (neueste 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"
    }
  ]
}