Scans

Start a scan

Queues an asynchronous scan and returns a 202 with the scan id. Poll GET /api/v1/scans/{id} until status is 'completed' or 'failed'.

Supply an optional Idempotency-Key header to make retries safe: the first request runs the scan and any retry carrying the same key replays the original 202 (with Idempotency-Replayed: true) instead of starting a duplicate. Reusing a key with a different request body returns 422; a retry that arrives while the first is still in flight returns 409. Keys are retained for 24 hours.

post/api/v1/scans

Request

  • Base URL: https://agent-ready.dev
  • URL: https://agent-ready.dev/api/v1/scans
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

Optional client-generated key (1-255 chars, [A-Za-z0-9_-]) that makes this POST safe to retry. The same key replays the original response.

Example:scan-2026-06-01-abc123

Request body

urlstring uri required
pageLimitinteger

Example request

{
  "url": "https://example.com"
}

Response

Scan queued. The Location response header carries the polling URL (per RFC 7231 §6.3.3); the same URL is also returned as pollUrl in the body.

idstring required
status'running' | 'completed' | 'failed' required

Lifecycle state of a scan. Poll until status is 'completed' or 'failed'.

urlstring uri required
pollUrlstring required

Changes

No recorded changes to this operation across all 1 revision of this API.