Skip to content

Changelog

Every change to the /v1 contract, newest first. Additive changes ship without notice; see Versioning for what that covers and what it does not.

2026-11-21 (catalog state filter)

GET /v1/medications and GET /v1/pharmacies accept an optional state, a two-letter state code, in both modes: only the rows whose states include it are returned. A code that is not two capital letters is 400 invalid_request with an issue on state. See Cases.

2026-11-20 (prescriber decides, comparison, shipping address)

A requested line can leave the whole dose to the prescriber. requested_medications[] on POST /v1/cases and on a visit's intake accepts an optional prescriber_decides. true shows the clinician the medication with no strength, and sent with quantity, refills, days_supply or directions it is 400 invalid_request with an issue on that field. false or absent changes nothing. Each requested line a case returns gains prescriber_decides, true when the whole dose is the prescriber's: the clinician sees no strength on the line and it states none of those four fields.

GET /v1/cases/{id}/prescription_comparison, under cases:read in both modes, sets each requested line beside what the clinician prescribed: an outcome of prescribed, substituted, not_prescribed, added, pending or sent_to_retail_pharmacy, and requested, prescribed and changed for each dose field. See Cases.

changed_fields on GET /v1/cases/{id}/prescriptions agrees with the comparison. It no longer lists a field the prescription states no comparable value for: a quantity that is not a bare whole number (published as its leading number, such as 3 for 3 mL vial, or 0), refills the clinician left blank (published as 0), and directions the clinician did not write (published as the dosage). Each of those could appear in changed_fields before.

PATCH /v1/cases/{id}/shipping_address, under patients:write in both modes, changes the address this case's order will ship to until a pharmacy has it, and announces patient.updated.v1. Two new problem codes: shipping_state_change_requires_new_intake (422) and shipping_address_locked (409). See Cases.

2026-11-16 (visits decide their intake)

POST /v1/visits accepts intake, optional and exclusive with case: the fields of POST /v1/cases without patient, hold and files. The visit files it as a case held at received and returns with case set to it; the refusals are case create's, on paths under intake, and sending both case and intake is 400 invalid_request. Booking with intake needs cases:write beside visits:write, else 403 forbidden. At wrap-up the clinician approves or declines that case in place, and case.approved.v1 or case.declined.v1 follows visit.completed.v1. A visit booked without an intake is a consultation only.

POST /v1/cases/{id}/release_hold answers 409 conflict while a scheduled or started visit holds the case.

A case a visit decided is billed as the visit. Its decision raises no case_approved or case_declined charge; video_visit is still charged on visit.completed.v1.

Test mode. POST /v1/test/visits/{id}/complete takes an optional decision, the approve and decline bodies of POST /v1/test/cases/{id}/decision. With none, a visit booked with an intake approves the requested lines as autopilot does; a decision on a visit with no held intake case is 409 conflict. See Visits.

2026-11-16 (state rules)

Test mode now refuses a testosterone or estradiol case filed without a visit. In test mode, POST /v1/cases requesting med_testosterone_cyp or med_estradiol answers 409 visit_required: the sandbox's fixture rules require a live video visit for men's and women's hormone therapy in every state. Book POST /v1/visits with the intake instead. A held case asking for either stays held: release_hold answers the same refusal. Every other sandbox medication files as before (catalog version 2026-11-16.1).

POST /v1/cases checks the patient's state, in both modes. Two new refusals, both 409, whose detail names the treatment category, the state and the next step: visit_required when the treatment needs a live video visit where the patient lives (book POST /v1/visits and send the intake), and not_available_in_state when no clinician could approve the case there (no state on the patient, no clinician licensed in it, or a treatment the state blocks). POST /v1/cases/{id}/release_hold asks the same question. See Cases.

GET /v1/states publishes each state's rule. Items gain visit_required, visit_required_categories and blocked_categories. Live rules are whatever this returns under a live key; test mode's are fixtures (Test mode).

Question sets publish category, the treatment category the set is the intake for, or null. It categorises only the medications the set lists in medication_ids, for a case that names the set, where the catalog does not already categorise them (Question sets).

case.visit_required.v1, a new case event: a change to the patient's state left an open case needing a live visit there. The case is held at received; book POST /v1/visits with case. It is sent once, when the change puts the hold on, and never for a case a booked visit will decide.

2026-11-16 (lab orders)

Ordering labs. Under a new scope, labs:write (not in the default grant), an integration orders a panel for its patient the way a clinic does in its console, in both modes: POST /v1/lab_orders, POST /v1/lab_orders/{id}/confirm and POST /v1/lab_orders/{id}/cancel, with the reads they need under labs:read: GET /v1/lab_panels, GET /v1/lab_orders/{id}/collection_options and GET /v1/lab_consents. The patient is charged nothing. A lab order gains confirmed_at. New problem codes: lab_panel_unavailable (404), patient_ineligible (422), lab_order_open (409), collection_unavailable (422), lab_order_not_confirmable (409), lab_order_required (409) and labs_unavailable (503); a missing or stale lab consent, or one accepted before its version took effect, is consent_required. See Labs.

lab_order.created.v1 announces every new lab order, by the clinic, a clinician or an integration, as awaiting_patient, with case when a clinician asked. An order was first announced when it was placed until now. The sandbox emits it too. POST /v1/test/lab_orders is unchanged, and still answers a second open order of a panel with 409 conflict.

2026-11-14 (question sets)

Question sets. GET /v1/question_sets and GET /v1/question_sets/{id} (?version= optional), both catalog:read and both modes, serve the intakes Cuvo publishes for each treatment in one vocabulary: id, question, input, type, required, options, none_option, ask_when and send_as, plus critical_options, the options a clinician must acknowledge. An unknown set or version answers 404 not_found. A test key reads the twelve Cuvo Network standard intakes with their live question and option ids. Two new MCP tools, catalog_question_sets and catalog_question_set, seventy-one in all.

POST /v1/cases accepts question_set: { id, version }, optional. A case that names one is checked before it is written and refused with 400 invalid_request, one issue per failing answer on answers.<i>.answer, or on answers for a required question left unanswered, or on question_set for a set or version that is not published. Any published version is accepted. A critical option never refuses a case. The case returns question_set, null when it named none. See Question sets.

2026-11-14 (requested lines)

A requested line may leave the dose to the prescriber. On POST /v1/cases, a requested_medications line now needs only its medication_id: quantity, refills, days_supply and directions are each optional, with the same limits when sent. A case returns every line with every key, null where the line did not state it (schema RequestedMedicationLine; pharmacy_notes, pharmacy_id and no_substitutions are now always present too). A live case now returns its requested_medications instead of an empty list; a line filed before today returns days_supply, directions, pharmacy_notes and no_substitutions as null.

A prescription shows what was asked beside what was prescribed. It gains requested, the case's requested line for the same medication_id or null, and changed_fields, the subset of quantity, refills, days_supply and directions the request stated and the prescription sets differently. A live prescription's days_supply is now the clinician's own value, null when the line records none.

Orders gain carrier, null until the pharmacy reports one. In test mode, POST /v1/test/cases/{id}/ship takes an optional carrier, and a ship with no tracking_number reports plainly fake tracking rather than null. Autopilot fills a dose a request left to the prescriber with a stated placeholder; see Test mode.

2026-11-14 (patient identity and ship_to)

A patient's email is optional, and is no longer how a patient is matched. email on POST /v1/patients may be left out, and a patient can now come back with email: null. A patient is identified by id and by your external_id. POST /v1/patients no longer returns an existing patient because the email matches: an undocumented behaviour until now, it merged two people who share an address into one chart, so the same request now creates a new patient. A case is filed on the patient you name, whatever their email. When a patient has no email, or shares one with another patient in any clinic on Cuvo, the pharmacy is sent a Cuvo relay address in its place. See Patients and consents.

Test mode returns the patient an external_id already names, as live mode does, rather than answering 400 invalid_request.

Orders gain ship_to, the address the pharmacy was sent, null until the order is submitted. A patient's address change reaches orders not yet submitted and never a submitted one.

2026-11-13 (sandbox labs)

Labs have a sandbox. Under a test key, GET /v1/lab_orders, GET /v1/lab_orders/{id}, GET /v1/lab_orders/{id}/results and GET /v1/lab_results/{id} now answer from the sandbox rather than with an empty list and 404. Seven test controls, all test:manage, play the patient and the lab network: POST /v1/test/lab_orders (patient, panel, optional case) and /v1/test/lab_orders/{id}/place, /collect, /receive, /result (an outcome of normal, abnormal or critical; a second call is a correction, the next version), /cancel and /fail. A patient has one open order per panel, as in live mode, so a second answers 409 conflict. They emit lab_order.placed.v1, lab_order.status_changed.v1 and lab_result.final.v1 exactly as live mode does. Three panels, testosterone-total-free, complete-blood-count and psa-total, report their markers under LOINC codes. A sandbox report has no PDF.

An order on a case holds it, as a clinician's lab request does live: the case reads waiting_on_patient with no question and no event, POST /v1/test/cases/{id}/decision refuses an approval or a question with 409 conflict until every order on it is resulted or waived (cancelled by a person, never by the lab network), and the case returns to in_review when the last one settles. A decline, or cancelling the case, cancels the case's orders that were never placed. An order the lab network failed or cancelled is re-ordered with /place, and ordering its panel again on the case waives it. See Labs.

Autopilot gains lab_result_after_s, 0 to 3600 or null, on PATCH /v1/test/autopilot and in its response: an open sandbox lab order is placed, then reported normal, waiting that many seconds before each step, and the approval timer then takes a case back from its settled labs. Seven new MCP tools, test_create_lab_order through test_fail_lab_order, sixty-nine in all.

The sandbox catalog. The sandbox formulary gains med_estradiol and med_nad_inj (catalog version 2026-11-13.1), and the sandbox store gains a fifth product, prod_test_testosterone.

2026-11-05 (commerce and affiliates)

Five new scopes for a tenant's storefront commerce and partner program: products:read, purchases:read, affiliates:read, affiliates:write and audit:read. None is granted by default; an organization's administrator approves each. A workspace's own integration, from its developer settings, now holds all five, and Update API scopes there adds any scope added later. A key keeps the scopes it was minted with, so mint a new key to use them. Fourteen new event types ride the existing feed and your existing endpoints, each delivered only to a grant holding the resource's read scope: purchase.paid.v1, purchase.refunded.v1, purchase.disputed.v1, affiliate_referral.created.v1, affiliate_referral.updated.v1, affiliate.created.v1, affiliate.updated.v1, membership.activated.v1, membership.renewed.v1, membership.payment_failed.v1, membership.cancelled.v1, membership.lapsed.v1, affiliate_commission.created.v1 and affiliate_commission.updated.v1. The resources they point at are described in their own entries as they ship.

Affiliates. GET /v1/affiliates and /{id} read the organization's affiliates and the sponsor tree, with their links and coupon codes and your own external_id and metadata; GET /v1/affiliate_referrals and /{id} read each referral with the upline it was credited under and the acquisition that decided it; GET /v1/affiliates/{id}/customers is the affiliate-facing projection of the customers one affiliate referred, named only as the program's new customer_disclosure setting allows (by default, not at all); and GET /v1/affiliate_program reads the program's settings, including whether commissions run on Cuvo or on an external engine. All need affiliates:read. Test mode serves a fixed program and a three-level tree, and POST /v1/test/affiliates adds your own. See Affiliates.

Purchases, customers and products. GET /v1/purchases and GET /v1/purchases/{id} serve every paid storefront charge with its refunds, any chargeback, its discount and the affiliate it is credited to; GET /v1/customers and GET /v1/customers/{id} serve each storefront account's ids and totals, never its identity. Both need purchases:read, and both filter by updated_after so a copy can be kept in step beside the purchase.* events. GET /v1/products and GET /v1/products/{id} serve the storefront catalogue under products:read, never its costs. A case gains source (integration, storefront or staff) and purchase. Test mode sells four fixed prod_test_ products and records checkouts at POST /v1/test/purchases, with /refund and /dispute controls. Billing now prices a decision or a withdrawal only on a case an integration opened; a storefront or staff case it can read costs it nothing. See Purchases and customers and Products.

A purchase's dispute is its amount_cents and opened_at. Only the Stripe rail records chargebacks today, and how one ended arrives later as one added field, status. In test mode a coupon_code must be one a sandbox affiliate holds: its discount comes off the charge, and sent without affiliate it credits its holder. A membership plan bought there is a treatment purchase until the sandbox models memberships.

Sixteen new MCP tools, sixty-two in all. The twelve reads above join the runtime group with read-only hints, and test_create_purchase, test_refund_purchase, test_dispute_purchase and test_create_affiliate join the build group, the refund and the dispute marked destructive. See MCP server.

Additive throughout: an existing caller is unaffected. Both SDKs and the CLI carry the new resources and events; their typed events read a purchase, a referral or an affiliate back by id.

2026-09-11 (wave 6b-3)

Video visits. A patient can now be booked into a live video consult with a licensed clinician. GET /v1/visits/slots returns bookable slot starts for a patient's state over a window of at most fourteen days, POST /v1/visits claims one, GET /v1/visits/{id} reads it back, and POST /v1/visits/{id}/cancel and /reschedule move it while it is still scheduled; a reschedule keeps the visit's id. GET /v1/visits/{id}/join mints the link the patient joins through: it is patient-bound, lives fifteen minutes, opens an hour before the visit, and is meant to be fetched at join time rather than stored. Two new scopes, visits:read and visits:write.

Six new event types ride the existing feed and your existing endpoints: visit.booked.v1, visit.rescheduled.v1, visit.cancelled.v1, visit.started.v1, visit.completed.v1 and visit.no_show.v1. A new charge kind, video_visit, is raised on visit.completed.v1 and on nothing else; a no-show is unpriced for now. Test mode plays the clinician at POST /v1/test/visits/{id}/start, /complete and /no_show, against sandbox availability generated from a fixed weekday template.

Additive throughout: an existing caller is unaffected. The MCP server gains nine tools for the same operations, and both SDKs and the CLI carry the resource. See Visits, Events and realtime and Billing.

2026-09-11 (wave 6a-2)

A person can sign in from a machine with no browser. The authorization server now offers the RFC 8628 device grant: POST /api/auth/device/code with a client_id, the scopes and a resource, then a poll of /oauth2/token with grant_type=urn:ietf:params:oauth:grant-type:device_code at the interval the server states. The person confirms the code at developers.cuvo.co/device as a signed-in member with a second factor, and approves the request whole or denies it: the device grant does not narrow. The CLI uses it as cuvo login --device. A device token is a member's token, so it is test mode; live data still needs a live client or a live key. Nothing about the /v1 contract changed. See Authentication and CLI.

2026-09-11 (wave 6a-1)

The CLI listens locally, completes itself and scaffolds a starter. cuvo webhooks listen --forward-to http://localhost:3000/hooks subscribes to your integration's realtime channel and POSTs every event to the local URL, signed with a session secret it prints once, so the handler verifies with the SDK exactly as it will in production. It is a mirror of the event stream, not a delivery: nothing is retried and no delivery row is written. cuvo completion zsh|bash|fish prints a completion script from the command tree, and cuvo init [dir] writes a TypeScript or Python starter with a sandbox smoke script and a verifying webhook handler. The TypeScript SDK gains signWebhook, the sender's half of the signature scheme. Nothing about the /v1 contract changed. See CLI.

2026-09-11 (wave 6a-3)

The MCP server publishes resources and every tool carries annotations. resources/list now returns every guide on this site as cuvo://docs/<slug> (text/markdown) and the contract as cuvo://openapi/v1.yaml (application/yaml); resources/read serves them, and a read leaves an audit row exactly as a tool call does. Every tool declares the four MCP hints (readOnlyHint, destructiveHint, idempotentHint, openWorldHint), derived from its operation's method and verb, so a client that asks before a destructive call can ask correctly. docs_search stays. Nothing about the /v1 contract changed. See MCP.

2026-09-09

The clients are published. Both are prerelease and both install with one command.

  • TypeScript: pnpm add @cuvo-health-us/api@next, version 0.1.0-next.0.
  • Python: pip install --pre cuvo, version 0.1.0a1, on PyPI since 2026-09-08.
  • Command line: pnpm add -g @cuvo-health-us/cli@next, version 0.1.0-next.0.

The npm scope is @cuvo-health-us, not @cuvo. The @cuvo scope on npm belongs to someone else, so the packages take the scope Cuvo owns. If your Cuvo contact handed you a tarball named @cuvo/api or @cuvo/cli before today, uninstall it and install the published package: the code is the same, the name is not. The cuvo command the CLI installs is unchanged, and so is the Python package name.

Nothing about the /v1 contract changed with this release. See SDKs and CLI.

2026-09-08 (wave 5b)

The patient export opened in live mode. POST /v1/patients/{id}/exports and GET /v1/patients/{id}/exports/{job} now answer in live mode, and the job comes back already completed: a chart is bounded, so there is nothing to wait for. Its url is the new download below, good for 24 hours, which is the life of the document links inside the bundle. Nothing about the job shape changed, so a caller who wrote the polling loop keeps it.

GET /v1/exports/{id} and GET /v1/exports/{id}/download. Added. The first is the same job, read by the id you kept rather than through the patient; the second streams the bundle as a file, with the same credential and the same patients:read scope. The bundle holds the patient, their cases, consents, files, prescriptions and orders in the shapes this API already publishes, plus a download link per document.

410 gone. Added to the problem codes. A download past expires_at answers with it: the export existed, and its bundle and the links inside it were deleted together. Start another one. No other operation can answer 410. See Errors.

2026-09-08

OAuth clients. Added. A platform can now exchange a client id and secret for a one hour access token at https://developers.cuvo.co/api/auth/oauth2/token and present it wherever an API key goes. Dynamic client registration is open with PKCE required, and a portal member can consent an agent to one integration in test mode. API keys are unchanged. See Authentication.

MCP server. Added at https://mcp.cuvo.co/mcp. Thirty-seven tools over the same credential, the same scopes and the same audit as the REST API. See MCP server.

GET /v1/invoices/{id}. Added. Returns the invoice the list already returned, plus charges: one line per billable event, with its kind, the resource it was raised for, its amount and the charge it reverses. GET /v1/invoices is unchanged.

Files require a patient. Changes a test-only shape: a breaking change for sandbox callers, and the only one in this release. Until today the file resource answered in test mode alone, so nothing in production spoke this shape and it could be corrected rather than versioned.

  • POST /v1/files now requires patient. A request without it is refused with 400 invalid_request, and the File resource carries the field on every read.
  • POST /v1/files/{id}/confirm, which previously took an empty body, now requires patient, kind and filename, repeating what the reservation was made with.
  • mime is now one of application/pdf, image/jpeg, image/png and image/heic rather than any string.
  • FileUpload gained upload_headers. The upload URL is signed for them, so a PUT without them is refused by storage.

Files opened in live mode. POST /v1/files, its confirmation and GET /v1/files/{id} now answer in live mode, which is what naming the patient bought. Three rules come with it:

  • In live mode the file id changes at confirmation. What the reservation answered with identifies the reservation; what the confirmation answers with identifies the filed document, and on the chart those are two different things. Use the id from the response you last received. A reservation is not readable through GET /v1/files/{id} once it has been confirmed. In the sandbox the two ids happen to be the same, so code written against this rule works in both.
  • DELETE /v1/files/{id} stays test only, and answers 501 live_not_available in live mode, because the internal clinical contract has no delete.
  • A live POST /v1/cases still refuses a non-empty files array.

See Files.

Developer documentation. Added: these guides, the reference, a Postman collection, /llms.txt, /llms-full.txt, and the agent skill at /skills/cuvo-api/SKILL.md.

Requesting access to an organization. Added to the developer portal. Send a clinic's org_… id, the scopes you need and a note, and the request appears as a pending grant.

SDKs built; publication pending. The Python client, cuvo, is written and generated from the same document as the TypeScript client, and both are built and gated in CI. Neither is published: @cuvo-health-us/api@next and cuvo==0.1.0a1 are the names they will take, and until Cuvo releases them a partner installs the build their Cuvo contact hands them. See SDKs.

2026-09-07

Billing reads. Added. GET /v1/usage aggregates the charge ledger over a window by kind, and GET /v1/invoices mirrors the invoices raised against the integration. Both need billing:read and both answer in either mode; a test credential gets an empty answer rather than a refusal. The charge.created.v1 event, published with the v1 catalog, is emitted from this date. See Billing.

2026-09-07 (earlier)

Live mode. Added for patients, consents, cases, messages, prescriptions, orders and the catalog. A cuvo_sk_live_ credential reaches the clinical plane instead of the sandbox, once the integration has accepted the business associate agreement in force. Nothing about the request or response shape differs between the two modes. What is not yet open answers 501 live_not_available: the patient export, and at that date the whole file resource.

2026-09-06

/v1 published. The first public contract: organizations, catalog, patients, consents, files, cases, messages, prescriptions, orders, webhook endpoints, events and realtime tokens, all in test mode against the sandbox, with the simulated clinician and pharmacy under /v1/test. Cursor pagination, RFC 9457 problem bodies, required idempotency keys on writes, and signed at-least-once webhook delivery date from here.