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, version0.1.0-next.0. - Python:
pip install --pre cuvo, version0.1.0a1, on PyPI since 2026-09-08. - Command line:
pnpm add -g @cuvo-health-us/cli@next, version0.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/filesnow requirespatient. A request without it is refused with400 invalid_request, and theFileresource carries the field on every read.POST /v1/files/{id}/confirm, which previously took an empty body, now requirespatient,kindandfilename, repeating what the reservation was made with.mimeis now one ofapplication/pdf,image/jpeg,image/pngandimage/heicrather than any string.FileUploadgainedupload_headers. The upload URL is signed for them, so aPUTwithout 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 answers501 live_not_availablein live mode, because the internal clinical contract has no delete.- A live
POST /v1/casesstill refuses a non-emptyfilesarray.
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.