Build on the chart.

Two ways in

Start in the sandbox — it takes an email and no paperwork. Production is where real charts live, so it carries real obligations.

Quickstart

Send the key as a bearer token. That's the entire authentication story.

Request

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

Response

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

Headers

Limits and errors

Rate limits

Budgets sit far above normal integration traffic — they exist to stop a runaway loop, not to meter you. Two windows apply at once: a per-second burst and a per-minute sustained rate, counted per key and again across the whole practice.

Over budget returns 429 with a Retry-After header. Honor it and back off — hammering a 429 is grounds for revocation. If you need a bulk window for a migration or a nightly extract, tell us in advance rather than discovering the ceiling in production.

Need a higher limit? Email info@chartvoyant.com with the integration, the traffic it sends and the peak rate you need, and we'll raise the limit. There's no fee for a higher limit.

Status codes

Error shape

Every error is the same envelope. Log the correlationId — it's the single fastest way for us to find your request, and it joins your call to the practice's audit trail.

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

API key usage policy

These terms apply to every key we issue. For production keys they're the substance of the API Use Agreement you sign; for sandbox keys the shorter Sandbox Terms below apply.

1. One key per integration. Never shared.

   A key identifies a system, not a company. Two integrations get two keys, so one can be revoked without breaking the other and the activity trail means something. Don't pass your key to a subcontractor, a sister product, or another practice.

2. Server-side only, with one exception.

   Keys live on infrastructure you control. Not in browser JavaScript, not in a mobile or desktop app you ship, not in a CLI you distribute — anywhere an end user could extract it. The one exception is an MCP client run by the person the key was issued to, on a computer your organization manages; item 14 sets the rules.

3. Store it like a database password.

   A secrets manager or an encrypted store. Not in source control, not in a container image, not in a CI log, not in a screenshot, not pasted into a support ticket or a chat window — and not into an AI assistant's transcript, which is a persisted copy of your credential in someone else's system.

4. Request the least access that does the job.

   Read-only unless you write. If your integration writes to two endpoints and reads twenty, say so — we'd rather scope the key correctly than issue a broad one and hope.

5. Minimum necessary.

   Pull the records and fields the integration actually needs. A nightly full-table sweep to support a feature that touches fifty patients is not minimum necessary, and it's the pattern that turns a small breach into a large one.

6. Don't build a shadow chart.

   Cache what you need to do the job, for as long as the job takes. Standing up a permanent parallel copy of a practice's clinical record needs that practice's explicit written agreement — the API is an interface to their chart, not a license to replicate it.

7. No secondary use.

   Data reached with a ChartVoyant key is used to deliver the service the practice asked for. Not to train models, not to build a data product, not for research, not to enrich a marketing profile, and never sold or brokered — unless the practice has authorized that specific use in writing.

8. Commercial products share profits.

   If the API powers something you sell, thirty-five percent of the profits from it go to Geach Technologies, LLC, on the terms set in the API Use Agreement — including that the rate and terms can change on notice. If a profit share shapes whether your product works as a business, read that section before you build on us.

9. Respect the rate limits.

   Honor 429 and Retry-After with real backoff. Schedule bulk work off-hours and tell us before a migration or a large backfill.

10. Rotate on a schedule, and on turnover.

    Ask for a new key before the current one expires, and whenever someone who had access to it leaves. Old key gets revoked; there's no reason to run two.

11. Report exposure immediately.

    A key in a public repo, a leaked log, a compromised host, a laptop gone missing — email info@chartvoyant.com with the key prefix and what happened. We revoke first and sort it out after. Telling us early is not the thing that gets a key pulled permanently; not telling us is.

12. Keep your contact current.

    We need a real technical contact who answers email. Expiry notices, incident notices, and breaking-change notices go there.

13. Access can be revoked at any time.

    ChartVoyant may suspend or revoke a key at any time, for any reason, without notice — a security incident, use outside these terms, or a request from the practice it's bound to are the common ones, but the right isn't limited to them. The practice can likewise revoke its own keys whenever it wants and doesn't owe you an explanation — it's their data. Build with that in mind.

14. AI agents are your risk, not ours.

    An MCP client hands what it reads to its AI model, so with a production key the model provider needs a BAA that covers the exact product and features you use — MCP, connector and tool traffic included, which some providers exclude even on healthcare plans — and no training on the data. Consumer accounts never qualify. One key per person or per agent, a managed computer for any client that holds a key, a person supervising the agent, and no clinical decisions made by it. The agent, its model provider and the data once ChartVoyant returns it are your responsibility, and ChartVoyant takes no liability for them. Production use needs version 1.1 of the API Use Agreement.

How to get a key

Every request is read by a person. There's no self-serve signup, and that's deliberate — we'd rather know who's holding a credential to a medical record.

Sandbox — usually same day

1. Email us

   Send info@chartvoyant.com your company or project, what you're building, a technical contact, and a line accepting the Sandbox Terms below.

2. We issue your key

   Your own key, bound to the shared sandbox office, with read and write on synthetic patients. It arrives by email to the technical contact you named.

3. Start building

   Point at https://demo.chartvoyant.com/api/v1 and go. Ask for a fresh key whenever this one expires.

Production — a few days, mostly paperwork

1. Tell us what you're connecting

   Email info@chartvoyant.com with the practice, the integration, the data it needs, whether it writes, and a technical contact.

2. The practice confirms

   We check with the office that they asked for this. If you're the practice, that step is already done.

3. Sign the API Use Agreement

   Print the agreement, sign it, email the scan back. We file it against the key. Confirm your BAA with the practice is in place at the same time, and if an AI agent will use the key, name it and its model provider on the agreement.

4. We issue the key

   Bound to that one office, at the access level you asked for, with an expiry. Delivered to the named technical contact — never posted in a ticket or a chat.

5. Verify, then go live

   Make a call, confirm it lands in the key's activity trail, and you're connected. We watch the first days of a new integration more closely than the rest.

On the roadmap

Not built yet — listed so you can tell us if one of these is what you actually need. Saying so moves it up.