API reference

Serge Scanner API

The API exposes Serge's deterministic scanner for programmatic scans and report retrieval. It covers scanning only; the full Agent Journey Test product lives in the main app. Scanning requires authentication — pass a secret key for 60 scans/hr per workspace. Reading cached reports stays public.

OpenAPI spec llms.txt Full docs (llms-full.txt)MCP quick start Methodology

Also available

Looking for the local Claude Desktop package instead of the hosted scanner API? The Serge MCP package is back in the docs, including the offline quick start.

→ Open Serge MCP quick start

Base URL

Authentication

Scan initiation requires authentication — anonymous requests return 401. Pass a secret key via the Authorization header:

Create secret keys in your account settings. Keys use the sk_serge_ prefix. Treat them like passwords.

Rate limits

All API responses include rate limit headers:

Header	Description
`X-RateLimit-Limit`	Max requests per window
`X-RateLimit-Remaining`	Requests remaining
`X-RateLimit-Reset`	Unix timestamp when window resets
`Retry-After`	Seconds until reset (429 responses only)

Tier	Rate limit	Auth
Anonymous	Not available — returns 401	None
Authenticated	60 scans/hr per workspace	`Authorization: Bearer sk_serge_...`

Domain rate limit: 5 scans per hour per target domain (shared across tiers).

Endpoints

POST/api/scan

Initiate a domain scan. Returns a Server-Sent Events stream with real-time progress as the scan crawls the site and emits findings.

Request body

SSE events

statusScan phase update — includes current phase description

crawlCrawl progress — includes URL being crawled and status

layerLayer scan completed — includes layer number, score, and check results

completeScan finished — includes scan ID, overall score, and per-layer breakdown

errorScan failed — includes error message

Example (anonymous)

Example (authenticated — 60 scans/hr)

GET/api/scan/{id}

Retrieve the full results for a completed scan. Responses are cached for 1 hour.

Path parameters

idUUID of the scan (returned by the complete SSE event)

Response

Error responses

400Invalid scan ID format

404Scan not found

Example

Webhook events

Serge can notify you when a monitored domain's score changes. Subscribe to score change notifications via the email gate on any scan result page.

score.changed

Machine-readable resources

/openapi.jsonOpenAPI 3.1 specification

/llms.txtProduct description for LLMs

/llms-full.txtExtended documentation for LLMs

/.well-known/agent.jsonA2A agent card with capabilities

/.well-known/agent-visit-registry.jsonOptional agent visit registry (data, endpoint, scope)

/methodologyScoring methodology (currently being rebuilt)

/sitemap.xmlXML sitemap

/robots.txtCrawler permissions