Readiness API documentation

Start a scan

POST /api/v1/scans accepts JSON with url, capture_profile, and optional site_type. Use static_v28 for the current capture. Site types are auto, content, api, and commerce. Supply an account bearer token in the Authorization header.

Get an account token

Create an account through Sign in, then use POST /api/json/auth/sign-in with your email and password. Send the JSON:API media type and a data object with type user and attributes email and password. The response contains meta.token. Keep it private and use it as READINESS_API_TOKEN.

Retry and status

Send an Idempotency-Key for actor-scoped retries. The server returns 202 for pending work and 200 for terminal work, with a Location header. Poll GET /api/v1/scans/{id}. Keep the key and request fields unchanged when retrying.

Read without starting work

GET /api/v1/scores/{domain} reads the latest approved report. GET /api/v1/checks returns the versioned check catalog. GET /api/v1/openapi.json publishes this API contract. Public reads need no bearer token.

Limits and errors

A quota response uses HTTP 429 and Retry-After. Back off for that interval. Invalid requests use a JSON problem response. A pending or failed scan has no readiness score. The score summary reports scope, coverage, and scanner limits.

Command-line use

Download readiness.py below. It needs Python 3 and no third-party packages. Set READINESS_API_TOKEN for scans. Read-only score and check commands need no token. Use --json for CI data. A minimum-score gate rejects reports without enough evidence.

Example request

curl -X POST https://agentnsight.com/api/v1/scans \
-H "Authorization: Bearer $READINESS_API_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: example-request-1" \
-d '{"url":"https://example.com/","capture_profile":"static_v28","site_type":"content"}'

OpenAPI contract · Check catalog · Download CLI (Python 3)

python3 readiness.py score example.com --json