---
title: "Cuvo Health developer portal"
description: "Cuvo Health developer portal: the Integrations API (OpenAPI 3.1, signed webhooks, sandbox, SDKs, MCP) plus a free read-only site API for agents."
canonical: "https://cuvo.co/developers"
last-updated: "October 1, 2026"
---
# Cuvo Health developer portal

Last updated October 1, 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. Cuvo publishes two APIs. The Cuvo Integrations API (section 1) is the clinical API a brand or software team builds on: patients, consents, cases, prescriptions, orders, visits and webhooks, documented in full at developers.cuvo.co. The rest of 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. Cuvo Integrations API: build on the clinic

The Cuvo Integrations API is Cuvo's clinical integration API at https://api.cuvo.co, documented publicly at developers.cuvo.co: an OpenAPI 3.1 contract with 65 operations across patients, consents, cases, messages, prescriptions, orders, visits, files, billing and events; HMAC-signed webhooks with 32 versioned event types, secret rotation and redelivery; required idempotency keys on every write; API keys and OAuth 2.0 with fine-grained scopes; a test-mode sandbox with 12 simulator operations that play the clinician and the pharmacy; TypeScript and Python SDKs and a CLI (prerelease); an MCP server with 46 tools; a public changelog, status page and a 12-month deprecation policy.

- **Documentation:** https://developers.cuvo.co/docs (start with https://developers.cuvo.co/docs/getting-started).
- **Contract:** OpenAPI 3.1 at https://developers.cuvo.co/docs/openapi.yaml (65 operations, 33 schemas) and a Postman collection at https://developers.cuvo.co/docs/postman.json.
- **Base URL:** https://api.cuvo.co/v1. Errors are application/problem+json with a stable code and a request_id.
- **Webhooks:** HMAC-SHA256 signed, timestamped deliveries of 32 versioned event types, with secret rotation, a delivery log and redelivery: https://developers.cuvo.co/docs/webhooks
- **Sandbox:** test mode with 12 simulator operations that approve, ship, deliver, block or fail a case and run visits: https://developers.cuvo.co/docs/test-mode
- **SDKs and CLI (prerelease):** TypeScript @cuvo-health-us/api on npm, Python cuvo on PyPI, and the @cuvo-health-us/cli CLI: https://developers.cuvo.co/docs/sdks
- **MCP server:** https://mcp.cuvo.co/mcp with 46 tools over the same scopes and audit as the REST API, OAuth 2.1 with dynamic client registration: https://developers.cuvo.co/docs/mcp
- **Reliability:** idempotency keys on every write, a 12-month deprecation floor inside /v1, a public changelog (https://developers.cuvo.co/docs/changelog) and status page (https://developers.cuvo.co/docs/status).
- **Plans:** API, webhooks and MCP access are included on Grow and Enterprise; Cuvo Prescribe connects Cuvo's providers and pharmacy to a stack a company already runs. Overview for buyers: /telehealth-api.

## 2. Site API 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/<slug>, or any /compare/<slug> URL; or send Accept: text/markdown to the page URL itself. Every mirror opens with YAML frontmatter (title, description, canonical, last-updated).

## 3. Authentication: Integrations API vs site API

The Cuvo Integrations API at https://api.cuvo.co authenticates with test and live API keys or OAuth 2.0 client credentials from the authorization server at https://developers.cuvo.co, with fine-grained scopes per resource (see section 1 and https://developers.cuvo.co/docs/authentication). The cuvo.co site API needs no credentials, by design. Every endpoint on cuvo.co is anonymous and free; no credentials are issued for it, and the site API needs no OAuth server (the Integrations API's authorization server is at developers.cuvo.co). 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.

## 4. Site API: REST 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.

## 5. Site 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.

## 6. Site API 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.

## 7. Site API rate limits and self-throttling

Dynamic endpoints (ACP, A2A, MCP, /ask, the JSON list endpoints, and /api/health) 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.

## 8. Site 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.

## 9. Webhooks, sandbox, and testing on each API

The Cuvo Integrations API publishes HMAC-signed webhooks with 32 versioned event types, secret rotation, a delivery log and redelivery (https://developers.cuvo.co/docs/webhooks), plus a test-mode sandbox whose 12 simulator operations play the clinician and the pharmacy (https://developers.cuvo.co/docs/test-mode). On the cuvo.co site API 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.