Agent API
Read crawl history, inspect deploy diffs, and start or cancel scans from scripts and integrations—no browser session required. Uses the same paid API key as CI and GitHub Actions.
On this page
Authentication
Create or copy a paid key from Developers → API keys. Pass it on every request:
x-ci-api-key: sck_…Authorization: Bearer sck_…
The key must belong to your organization with an active paid entitlement.
Shared operator keys are not accepted. Failed auth returns 401 with { "error": "…" }.
Base URL: https://signaldiff.dev/api (production) or
https://staging.signaldiff.dev/api (staging).
Read routes
GET /agent/sites
Site directory with run counts and the latest known run summary per site (from recent history).
GET /agent/runs
Paginated crawl history for your organization.
| Query | Description |
|---|---|
site |
Filter by normalized site key |
limit |
Page size (1–250, default 50) |
cursor |
Continuation token from nextCursor |
Active in-memory jobs appear on the first page only; later pages use the archive cursor.
GET /agent/runs/{runId}
Run summary. Optional includePages=true adds stored page payloads (default false).
GET /agent/runs/{runId}/findings
Flattened findings with filters and offset pagination.
| Query | Description |
|---|---|
severity |
Error, Warning, or Info |
check |
Exact check name (case-insensitive) |
urlPrefix |
URL prefix filter |
limit / cursor |
Page size (1–200, default 50) and numeric offset cursor |
Response: { "items": [...], "nextCursor": "…", "totalCount": N }
GET /agent/runs/{runId}/diff
Returns only the deploy diff for the run. 404 when no baseline diff exists.
Write routes
POST /agent/scans
Start a crawl (API context—not CI metadata). Returns 202 Accepted with
{ "jobId", "statusUrl" }. Concurrent limits match the dashboard; excess returns 429.
| Field | Required | Notes |
|---|---|---|
sitemapUrl |
Yes | Absolute http/https URL |
maxPages |
No | Cap pages fetched |
maxConcurrency, linkCheckMaxConcurrency, timeoutSeconds, maxFetchRetries |
No | Override crawl defaults |
executionMode |
No | Cloud (default) or Agent |
agentPoolId |
No | Required when executionMode is Agent |
GET /agent/scans/{scanId}
Poll scan status (summary only, no pages).
POST /agent/scans/{scanId}/cancel
Cancel a pending or running scan. Returns 204 No Content on success.