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).
Rate limits
Limits are applied per API key. Exceeding a limit returns 429 with
{ "error": "Rate limit exceeded." } and a Retry-After header (seconds).
| Surface | Default |
|---|---|
GET /agent/* (sites, runs, findings, diff, summary, scan status) |
120 requests / minute |
POST /agent/scans, cancel, and POST /trigger/ci |
10 requests / hour |
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.
GET /agent/runs/{runId}/summary
Rule-based executive summary for agents and MCP: run metadata, deploy diff headline counts, and capped top regressions/improvements with fix hints from SEO checks reference. No page payloads or full findings lists.
| Query | Description |
|---|---|
limit |
Max regressions and improvements per side (1–20, default 5) |
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.
Audit logging
Each Agent API request with a paid programmatic key records a structured AgentApiAccess log
(key document id, route, method, optional job id, outcome)—never the plaintext key or page content.
Operators query these events in Application Insights or Grafana; see the repository
docs/agent-api.md for Kusto and LogQL examples.