API and agent access

Cuvo publishes a small, read-only set of machine-readable endpoints so AI assistants, crawlers, and automated agents can read the site without scraping HTML. Everything listed here is public, requires no authentication, and mirrors claims already published on the human-readable pages. This page is the endpoint-by-endpoint reference; the developer portal at /developers covers the quickstart, the error model, rate limits, and the versioning policy.

1Discovery and well-known endpoints

• GET /.well-known/api-catalog: an RFC 9727 API catalog (application/linkset+json) pointing at the OpenAPI description, this page, and the status endpoint.
• GET /openapi.json: an OpenAPI 3.1 description of every endpoint on this page.
• GET /auth.md: agent authentication and registration discovery (auth.md convention). Access is anonymous; no credentials are issued.
• GET /.well-known/agent-card.json: the A2A Agent Card (also at /.well-known/agent.json) describing the deterministic Cuvo agent at POST /api/a2a (JSON-RPC message/send) and its AP2 merchant declaration. The agent answers from published facts and books the free discovery call when a data part carries first_name and email.
• GET /.well-known/mcp.json: the MCP server manifest (registry server.json format) for the Model Context Protocol server at /mcp: streamable HTTP, stateless, no auth, with content tools and consent-gated discovery-call booking. The read-only documentation server at /docs/mcp has its manifest at /.well-known/mcp-docs.json, a server card lives at /.well-known/mcp/server-card.json, and connection details are on the developer portal.
• GET /.well-known/ai-catalog.json and /.well-known/agent-skills/index.json: the Agentic Resource Discovery catalog of every agentic resource on this domain, and the flat Agent Skills index (name, description, protocol, endpoint per capability).
• GET /robots.txt and GET /sitemap.xml: crawl policy and the canonical list of indexable pages.

2Content and feed endpoints

• GET /llms.txt: a markdown summary of Cuvo for AI assistants (llmstxt.org format): what the platform runs, published pricing, key facts, and canonical Q&As.
• GET /llms-full.txt: the complete text of every published article and comparison page in one markdown document.
• GET /feed.xml: an RSS 2.0 feed of published blog articles with full content.
• GET /compare/{slug}.md: a plain-markdown mirror of any comparison page. Append .md to the page URL, for example /compare/cuvo-vs-wheel.md. The homepage mirror is /index.md, and /pricing, /developers, /about, /booking, /terms, /privacy, and /security mirror the same way; every mirror opens with YAML frontmatter.
• GET /api/articles and GET /api/comparisons: typed JSON lists with cursor pagination (limit 1-50, follow next_cursor until null), linking each item's HTML page and markdown mirror.
• GET or POST /ask: NLWeb natural-language queries over the published content, answered deterministically as ranked links; JSON by default, SSE streaming on request.

3Agentic commerce (ACP)

Cuvo implements the Agentic Commerce Protocol (agenticcommerce.dev, spec 2026-01-30) with a single free item: booking a 30-minute discovery call. Discovery lives at /.well-known/acp.json; the REST API base is /api/acp. An agent creates a checkout session, completes it with the buyer's first name and email (no payment data: the total is always $0), and the order in the response carries the /booking URL where the buyer picks a time. Sessions are stateless: retrieval returns the canonical cart, updates echo merged state without persisting it, and the complete call is authoritative and carries all data. The endpoints are POST /api/acp/checkout_sessions, GET and POST /api/acp/checkout_sessions/{id}, plus /complete and /cancel.

4Errors, rate limits, and versioning

API errors are RFC 9457 problem details (application/problem+json) carrying a machine-readable code and a hint with the next step; the ACP endpoints use the protocol's own error body and the A2A and MCP endpoints use JSON-RPC error objects. Dynamic endpoints allow 300 requests per 60 seconds per IP, advertised in the RateLimit response headers, with Retry-After on 429. Versioning is date-based via the API-Version header; breaking changes get at least 90 days of Deprecation and Sunset notice. The full conventions live at /developers and in /openapi.json.

5Status and health checks

• GET /api/health: returns application/health+json with status "pass" while the deployment is up. This is a liveness signal for the website, not a status page for clinical or third-party systems.

There is no authenticated partner API on cuvo.co. Prospective partners can review published pricing at /pricing or book a discovery call at /booking.