API Reference

Endpoint

` POST /v1/audit `

The audit endpoint accepts a URL and optional scope parameters, fetches the target site server-side, runs 13 check groups, and returns a JSON response with scores, findings, benchmarks, and agent readiness data.

A deprecated unversioned alias POST /audit is available at runtime for backward compatibility. It is excluded from the public OpenAPI schema.

Request schema

`json { "url": "https://example.com", "preset": "blog", "include_protocols": false, "include_account_auth": false, "include_ecommerce": false } `

Fields:

• url (string, required): The public URL to audit. Must resolve to a public IP (SSRF protection blocks private ranges).
• preset (string, optional): Website category preset. See presets below.
• include_protocols (boolean, optional, deprecated): Enable API and protocol expectations.
• include_account_auth (boolean, optional, deprecated): Enable account and auth expectations.
• include_ecommerce (boolean, optional, deprecated): Enable commerce protocol and catalog expectations.

The three boolean scope toggles are marked deprecated: true in the OpenAPI schema. They remain in the contract because existing integrations depend on them, but generated client SDKs now flag them as deprecated.

Presets

• blog - Blog and content sites
• corporate - Corporate and brand sites
• services - Services and local business sites
• news - News and publisher sites
• saas - SaaS, product, and API sites
• ecommerce - Ecommerce and catalog sites
• custom - Power user mode with manual family selection

Presets select check families before the scan runs. Custom mode allows manual add/remove of supported free check families. Preset selection is user-controlled and deterministic.

Response schema (200 OK)

The response includes:

• overall_score: Full rubric score (0-100, includes locked rows as 0)
• benchmark.score: Essentials evidence score (0-56, checked rows only)
• agent_readiness.score: Strict agent readiness score (0-8 default, 0-21 full scope)
• checks: Array of 13 check group results with per-check scores, statuses, and findings
• locked_rows: Array of 9 locked advanced rows, all scored 0
• scope: The active scope metadata (preset, enabled families, denominator, caveats)
• benchmarks: Peer-relative comparison data

Error responses

• 400: Invalid URL or missing required field. Example: {"detail": "URL is required"}
• 422: Validation error (unknown preset, preset-override conflict). Example: {"detail": "Unknown preset: foo"}
• 429: Rate limit exceeded. Example: {"detail": "Rate limit exceeded"}

Rate limits

The audit endpoint is rate-limited using SlowAPI.

• Default: 3 requests per minute per IP
• Production override: MACHINEREAD_AUDIT_RATE_LIMIT environment variable at startup
• Rate limit headers are included in 429 responses

CORS

Local development allows known localhost frontend origins. Production uses only MACHINEREAD_CORS_ORIGINS. If unset in production, CORS fails closed with no cross-origin access.

OpenAPI schema

The curated OpenAPI schema is available at /openapi.json and includes:

• Tags grouping operations into Audit and System
• Field-level descriptions and examples on every public model
• Working 200, 400, 422, and 429 response examples
• deprecated: true on the three legacy boolean scope toggles
• externalDocs.url pointing to https://machineread.ai/docs