--- title: "Cuvo Health developer portal" description: "The Cuvo Health developer portal: free REST API with OpenAPI spec, MCP server for AI agents, problem+json errors, rate limits, and versioning. No API keys." canonical: "https://cuvo.co/developers" last-updated: "August 23, 2026" --- # Cuvo Health developer portal Last updated August 23, 2026. Canonical page: https://cuvo.co/developers Cuvo Health is the white label telehealth platform: brands bring their name and customers, and Cuvo operates the licensed clinic behind them. This portal documents everything cuvo.co serves to developers and AI agents: a small, free, read-only REST API over the site's published content, an MCP server with live discovery-call booking, and the conventions (errors, rate limits, versioning) those endpoints follow. There is nothing to sign up for and nothing to pay: every endpoint below is anonymous. ## 1. Quickstart for agents and developers - **Read the site summary:** curl https://cuvo.co/llms.txt returns what Cuvo runs, published pricing, the canonical FAQ, and when-to-use guidance for agents. - **Fetch the API contract:** curl https://cuvo.co/openapi.json returns the OpenAPI 3.1 description of every operation, with typed responses and the error model. - **Check liveness:** curl https://cuvo.co/api/health returns application/health+json with status "pass" while the deployment is serving. - **Connect over MCP:** point any MCP client at https://cuvo.co/mcp (streamable HTTP, no auth). In Claude Code: claude mcp add --transport http cuvo https://cuvo.co/mcp - **Script it with the official CLI:** npx cuvo-health --help (npm package cuvo-health; npm install -g cuvo-health installs the cuvo command). It wraps every read endpoint (overview, pricing, compare, articles, openapi, health) plus availability, book, and callback, with --json for structured output. - **Read any content page as markdown:** the homepage is at /index.md; append .md to /pricing, /developers, /about, /booking, /terms, /privacy, /security, any /blog/, or any /compare/ URL; or send Accept: text/markdown to the page URL itself. Every mirror opens with YAML frontmatter (title, description, canonical, last-updated). ## 2. Authentication and API keys There are none, by design. Every endpoint on cuvo.co is anonymous and free; no credentials are issued and no OAuth server exists. The machine-readable statement of this policy lives at /auth.md (auth.md convention). The only "registration" Cuvo offers is commercial, not technical: a founder who wants to launch on the platform books a discovery call at /booking, and agents can book that call programmatically through the MCP, ACP, or A2A endpoints below. ## 3. REST API reference and OpenAPI - **GET /openapi.json:** the OpenAPI 3.1 contract (version 2026-08-23). Every operation has a unique operationId, a description, typed response schemas, and documented error responses, so the spec loads directly into LLM function-calling and codegen tooling. - **GET /.well-known/api-catalog:** RFC 9727 API catalog (application/linkset+json) linking the spec, the docs, and the health endpoint. - **Content endpoints:** GET /llms.txt (site summary), GET /llms-full.txt (every published article and comparison in one markdown document), GET /compare/{slug}.md (comparison mirrors). Scoped context: /developers/llms.txt, /blog/llms.txt, /compare/llms.txt, /pricing/llms.txt, /api/llms.txt, /docs/llms.txt. - **JSON lists with pagination:** GET /api/articles and GET /api/comparisons return typed items with cursor pagination: pass limit (1-50, default 20) and follow next_cursor until it is null. - **Natural-language search (NLWeb):** GET /ask?query=... (or POST {"query": "..."}) returns ranked links into the published pages, answered deterministically from published content. SSE streaming with ?streaming=true or prefer.streaming. - **Booking endpoints:** the Agentic Commerce Protocol checkout under /api/acp (discovery at /.well-known/acp.json) and the A2A JSON-RPC agent at /api/a2a (Agent Card at /.well-known/agent-card.json). Both book the free discovery call; the total is always $0 and no payment data is ever requested. - **Endpoint reference:** the endpoint-by-endpoint walkthrough lives at /api-docs. ## 4. MCP server for AI agents Cuvo runs two stateless Model Context Protocol servers over streamable HTTP with plain JSON responses: no sessions, no SSE, no auth. The product server at https://cuvo.co/mcp exposes nine tools: get_overview, get_pricing, list_comparisons, get_comparison, list_articles, and get_article read the site's published content; get_availability, book_discovery_call, and request_callback check the team's real calendar and book the free 30-minute discovery call. The documentation server at https://cuvo.co/docs/mcp exposes the six read-only content tools and cannot act, for agents that answer questions only. Every tool carries behavioral annotations (readOnlyHint, destructiveHint) and a closed input schema. Booking tools require the user's explicit consent plus their real name and email; the calendar invite goes to that email. - **Manifests and preview:** registry server.json manifests at /.well-known/mcp.json (product) and /.well-known/mcp-docs.json (docs); a server card with the full tool list at /.well-known/mcp/server-card.json; the Agent Skills index at /.well-known/agent-skills/index.json; and the ARD catalog of everything at /.well-known/ai-catalog.json. - **Claude Code:** claude mcp add --transport http cuvo https://cuvo.co/mcp - **Any MCP client:** POST JSON-RPC 2.0 to https://cuvo.co/mcp, e.g. {"jsonrpc":"2.0","id":1,"method":"tools/list"} after initialize. - **Stdio-only clients:** run the official CLI as a local proxy: command "npx", args ["-y", "cuvo-health", "mcp"]. It forwards stdio JSON-RPC lines to https://cuvo.co/mcp, so clients without HTTP transport get the same nine tools. ## 5. Error model and status codes API errors are RFC 9457 problem details (application/problem+json). Every problem carries type, title, status, and detail, plus two documented extension members: code, a stable machine-readable snake_case identifier (not_found, method_not_allowed, rate_limited, and so on), and hint, a plain statement of what to do next. Two protocol-mandated exceptions: the ACP endpoints return the Agentic Commerce Protocol error body (a messages array with type "error" and a code), and the A2A and MCP endpoints return JSON-RPC 2.0 error objects. Undefined /api/* paths return a problem+json 404 that lists where the real endpoints are described; nonexistent site paths return a markdown 404 with recovery links to any client that does not ask for HTML. ## 6. Rate limits and self-throttling Dynamic endpoints (ACP, A2A, MCP) allow 300 requests per 60 seconds per IP and advertise live quota state on every response using the IETF RateLimit headers: RateLimit-Policy describes the policy, RateLimit carries remaining requests and seconds to reset, and the draft-07 trio (RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset) is sent alongside for older clients. Exceeding the quota returns 429 with Retry-After; wait that many seconds and retry. Statically cached endpoints (content and discovery documents) advertise RateLimit-Policy only and are effectively unmetered reads from the CDN. ## 7. API versioning and deprecation Versioning is date-based. The current version is 2026-08-23; every API response echoes the version that served it in the API-Version header, and requests may pin a version by sending the same header. The policy agents can rely on: breaking changes ship as a new version date, the prior version keeps working for at least 90 days, and during that window responses on the deprecated version carry Deprecation and Sunset headers announcing the removal date. Additive changes (new endpoints, new optional fields) do not bump the version. ## 8. Webhooks, sandbox, and testing There are no public webhooks: the inbound receivers under /api are private integration endpoints for specific third parties and are deliberately not part of this API. The sandbox is built into the production endpoints rather than hosted separately. Read endpoints are a free sandbox by nature: every GET is side-effect free, so test against them directly. For the write path, the ACP checkout has a documented test mode: complete a session with a buyer email on an RFC 2606 reserved domain (for example agent@example.com) and the flow behaves exactly like production but no notification is sent and nothing is recorded. Retries are safe everywhere: send an Idempotency-Key on mutating calls (it is echoed back), and a retried complete never duplicates the sales notification. The calendar booking tools (MCP book_discovery_call and request_callback, A2A booking) have no test mode because they write to a real calendar; call those only with a real user's consent, never with synthetic data. Questions, or want Cuvo to run the clinic behind your brand? Published pricing is at /pricing and a 30-minute discovery call is at /booking. For everything machine-readable, start at /llms.txt or /.well-known/api-catalog.