Calling the audit from an AI agent
An AI agent can call the MachineRead audit by sending a POST request to the /v1/audit endpoint. The request is a JSON body with a URL and optional scope parameters.
`json POST /v1/audit Content-Type: application/json
{ "url": "https://example.com", "preset": "blog" } `
The response is a JSON object containing the overall score, per-check findings, benchmark comparison, and agent readiness data. The agent can parse the response and summarize the results for the user.
Minimal agent workflow
1. Read the URL the user wants audited 2. POST to /v1/audit with the URL and optional preset 3. Parse the JSON response 4. Extract overall_score, benchmark.score, and agent_readiness.score 5. Summarize the checks array findings for the user 6. Note the locked_rows as coverage gaps the free tier does not verify
Discovery surfaces
MachineRead publishes 4 static agent-readable surfaces. These are static files served from the static export. They do not execute code and do not collect data.
llms.txt
Located at /llms.txt. A plain-text file explaining what MachineRead does, how to call the free audit, what the scores mean, and what the audit does not claim. Agents can read this to understand the product before calling the API.
ai-catalog.json
Located at /.well-known/ai-catalog.json. A JSON catalog file following the ARD (Agentic Resource Discovery) convention. It lists the audit API as a discoverable agent resource with metadata about capabilities, endpoints, and authentication requirements (none for the free tier).
api-catalog.json
Located at /.well-known/api-catalog.json. A linkset-style JSON file that points to the OpenAPI schema and API documentation. Agents use this to find the machine-readable API contract.
openapi.json
Located at /openapi.json. The curated OpenAPI schema for the audit API. Contains tags, field-level descriptions, examples, response schemas, and deprecation markers. Agents can use this to generate client code or inspect the contract.
MCP server card
MachineRead publishes an MCP (Model Context Protocol) server card as a static JSON file. The server card describes the audit as an MCP tool that an agent can invoke:
- Tool name:
machineread_audit - Input: URL string and optional preset string
- Output: JSON audit result
- Authentication: none (free tier)
- Transport: HTTP
The MCP server card is a static descriptor. It does not run a live MCP server. Agents that support MCP can read the card to understand how to invoke the audit as a tool within their workflow.
Agent readiness scoring
The audit response includes an agent_readiness object with a separate score that measures explicit agent-native discovery and protocol signals. This score is stricter than general crawlability or SEO:
- Default scope max: 8 probes
- Full scope max: 21 probes
- Probes cover: robots.txt, sitemap, link headers, DNS-AID, markdown negotiation, AI bot rules, content signals, web bot auth, API catalog, OAuth discovery, OAuth protected resource, auth.md, MCP server card, A2A agent card, agent skills, WebMCP, and commerce metadata protocols (x402, MPP, UCP, ACP)
An agent can use this score to assess whether a target site is itself agent-readable, separate from whether it is search-optimized.