Healthcare API for AI: a provenance-labelled patient context within a token budget

A FHIR search returns everything that matches. A language model needs something else: the facts that matter, first, each one saying who recorded it, in a size that fits the prompt. Building that from raw resources is a project in itself, and getting it wrong means a model that treats a patient's guess like a lab result. The Anpheros context API does that work on the platform, under the person's consent, so the model you choose starts from a defensible summary.

The request

curl -X POST "$BASE/v1/context" \
     -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
     -d '{"patient": "'$PID'", "budget_tokens": 2000, "task": "pre-visit summary", "format": "text"}'

budget_tokens is the size you can afford in the prompt. task and an optional question steer which items come first; needs names the kinds of data you want; window_days limits how far back to look; format chooses structured sections or a rendered text block. Every call is in the person's access log as a context read.

What comes back

Provenance-labelled sections (or, with format: "text", a rendered block ready to paste into a prompt), plus tokens_used, an omitted list naming what did not fit, warnings and a provenance_note. Items are ordered by clinical relevance and cut at the budget: active problems and allergies first, then current medications, recent measurements and results, recent symptoms, then older history. Each item carries:

• author_type: patient, practitioner, device, import or derived;
• source: the application or organisation that wrote it;
• the date, the code (LOINC, ICD-10, ATC) and the value with its unit;
• for derived items, what they were derived from.

The provenance note in the response says the same thing in words, so a model that reads the text block also learns to weigh the items. A practitioner-recorded diagnosis and a patient-typed "I think I have…" are both present, and they are labelled differently.

What it is for

• A pre-visit summary for a clinician, generated by the model you trust, from facts with sources.
• A patient-facing assistant that answers "what did my last results say" with the actual numbers and dates.
• Triage or routing inside your product, where the model needs the record but must not see more than the person allowed.
• Pattern questions ("what changed since spring"), for which the platform's pattern engine and the compare_periods and get_series tools give evidence rather than conclusions.

What it refuses to be

The context API is not clinical decision support and the platform does not call a model for you. It returns labelled facts; what the model says is the responsibility of whoever deploys it. The API also does not include items the person's consent excludes: if the grant covers observations and medications but not documents, the context has no documents.

Under consent, always

The token in the request is the person's, obtained through OAuth 2.1 with the scopes and duration they chose. A project key sees only the patients the project created. An application registered as an AI agent can read under consent and can only propose writes, which the person approves or rejects.

The same context is available to MCP assistants as the get_patient_context tool at platform.anpheros.com/mcp, so Claude, ChatGPT or your own agent reads it without any code on your side. See EMR integration with AI medical assistants.

Frequently asked questions

Which model does the platform use?

None. The platform builds the context; you send it to the model you choose, hosted or private. The record never leaves the EU on the platform's side.

How is the budget enforced?

Items are ranked by clinical relevance and included until the budget is reached; the omitted list in the response names what was left out, so the model knows the context is partial.

Can I ask for only part of the record?

Yes, in three ways: the scopes of the person's consent limit what can be read at all, needs and window_days narrow the request, and the budget cuts the rest. For raw control use search_fhir or the /v1 endpoints instead.

Is the output deterministic?

For the same record, consent and budget, yes. New entries change it, which is the point: the context reflects the record as it is now.

Where do I try it?

The sandbox is free and its 30 synthetic patients have six months of coded history. Get a key and call the context endpoint on any of them: developers.anpheros.com/guides/first-hour.