Developers · ChartVoyant API

REST API

Live

A JSON API over the same contract layer the ChartVoyant app runs on. Your system authenticates with an API key, and every key is bound to exactly one practice.

At a glance

Status	Live in the sandbox and in production.
Base URL	Sandbox: `https://demo.chartvoyant.com/api/v1` Production: `https://chartvoyant.com/api/v1`
Authentication	`Authorization: Bearer cvk_…`, an API key issued by ChartVoyant. No OAuth flow and no session.
Scope	One practice per key, at one of two access levels: read-only, or read and write.
Format	JSON over HTTPS. Request bodies up to 1 MB.
OpenAPI	An OpenAPI 3.1 document is served at `https://chartvoyant.com/api/openapi.json`. It describes the core routes (context, practitioners, patients, encounters, documents, MCP and status) and does not yet list every route. Ask us for the routes your integration needs.
Terms	Sandbox: the Sandbox Terms. Production: a signed API Use Agreement and the usage policy.

How an API key works

One credential format everywhere. A key is a bearer token you send over TLS.

A synthetic example of the key format. The prefix identifies which key you are; the secret proves you hold it.

One key, one practice. The key is the tenant. There is no cross-office key and no header that reaches a different practice's data.
The prefix is public; the secret is not. Quote the prefix in a support email so we can find your key. Never send the full token to anyone, including us.
Two access levels. read_only permits safe methods only; a POST, PUT, PATCH or DELETE is refused with a 403 that says so. full permits reads and writes. The one place a read-only key may POST is the MCP endpoint, where it can call the read tools only.
Keys expire. Every key is issued with an expiry, 90 days by default. Ask for a longer term if your integration needs one.
Revocation is immediate. A revoked key stops authenticating on the next request.
Every request is logged to the key. Method, route, status, source IP, correlation ID and duration, including refusals. Query strings, request bodies and response payloads stay out of that trail; PHI access is recorded in the practice's own audit log.

Quickstart

Send the key as a bearer token. The example uses the sandbox, which holds synthetic patients only.

Request

# Sandbox: synthetic patients only
curl "https://demo.chartvoyant.com/api/v1/patients?limit=5" \
  -H "Authorization: Bearer $CHARTVOYANT_API_KEY" \
  -H "X-Purpose: operations"

Response (synthetic)

{
  "data": [
    {
      "id": "0f2c…",
      "mrn": "MRN-100482",
      "name": { "family": "Example", "given": ["Sample"] },
      "birthDate": "1974-03-11"
    }
  ],
  "page": { "limit": 5, "offset": 0, "hasMore": true }
}

Headers

Header	Required	What it does
Authorization	Yes	`Bearer cvk_…`, your full key, on every request.
X-Purpose	No	Purpose of use recorded on the practice's audit event for the request. Defaults to `operations`.
Content-Type	On writes	`application/json`.

Common routes

These are the routes the OpenAPI document describes. Paths are relative to the base URL.

Route	What it does
GET /context	The practice and principal the key resolves to.
GET /practitioners	The practice's providers. `GET /practitioners/{id}` reads one.
GET /locations/{id}/providers	Providers who work at one location.
GET /patients	Patient search by `mrn`, `q` or `dob` (an ISO date prefix), paged with `limit` (up to 100) and `offset`.
GET /patients/{id}	One patient.
POST /patients	Create a patient (full-access key).
POST /encounters	Start an encounter (full-access key).
POST /documents	Register document metadata (full-access key).
GET /patients/{id}/ccda	The patient's current CCD as XML (beta). See C-CDA.
POST /mcp	The MCP server.

Server-side only

A ChartVoyant key belongs on a server you control. Never ship one in a browser bundle, a mobile app, a desktop client or anything else a user can open.

Limits and errors

Budgets sit far above normal integration traffic. Two windows apply at once, a per-second burst and a per-minute sustained rate, counted per key and again across the whole practice.

Scope	Burst	Sustained
Per key	150 requests / second	3,600 requests / minute
Per practice (all keys and staff sessions combined)	400 requests / second	12,000 requests / minute

Over budget returns 429 with a Retry-After header. Honor it and back off. Need a higher limit, or a bulk window for a migration? Email info@chartvoyant.com with the traffic and the peak rate. There is no fee for a higher limit.

Status codes

Code	Meaning
400	The request was malformed or failed validation. The message says what.
401	The key is unknown, revoked, expired, or the secret is wrong. We deliberately do not say which.
403	The key is valid but this is not allowed: a read-only key attempting a write, or any key touching a forbidden path.
404	No such record in the practice this key is bound to. A record at another practice is a 404 here, not a 403.
429	Rate limited. Back off for `Retry-After` seconds.
5xx	Our problem. Retry with backoff, and send us the correlation ID if it persists.

Error shape

Every error uses the same envelope. Log the correlationId: it is the fastest way for us to find your request.

{
  "error": {
    "code": "forbidden",
    "message": "This API key is read-only; POST is not permitted",
    "correlationId": "01J8ZC…"
  }
}

What a key can never reach

These refusals are structural. No access level unlocks them.

Sign-in and password routes

Creating or changing staff logins

The role and permission map

The patient portal

Demo session control

Tenant migration tooling

ChartVoyant’s own operations tools

Issuing or revoking API keys

Minting other credentials (portal invites, upload or kiosk tokens, SMART clients)

A refused request is a row in your key's activity trail with the reason attached.

How to get access

Start in the sandbox
Email info@chartvoyant.com with your project, what you are building, a technical contact and a line accepting the Sandbox Terms. Sandbox keys are usually issued the same day.
Go to production with a practice
A production key needs a sponsoring practice that confirms the request, a signed API Use Agreement, and a BAA between you and the practice. The steps are on the developers page.
Contact ChartVoyant support with questions
Email info@chartvoyant.com or use the support form. A person reads every request.

MCP serverThe same key, for AI agents Usage policyThe terms every key carries API Use AgreementSigned for a production key

At a glance

How an API key works

Quickstart

Headers

Common routes

Server-side only

Limits and errors

Status codes

Error shape

What a key can never reach

How to get access

Related