Medical Record Summary API for AI Legal Agents
A medical record summary API for legal-AI agents: cited events, structured output, confidence signals, typed errors and MCP access.

A medical record summary API gives an AI agent a trustworthy read of underlying records before it drafts a demand letter, prepares a deposition outline or triages a new intake file. Guessing at what a scanned PDF says is not an option in a legal context, so the chronology engine is built to be called as a tool, not just used through a browser.
Why an agent can't just read the PDF itself
A general-purpose language model can technically attempt to read a medical record PDF directly, but it has no way to guarantee page-level citation, no consistent event schema across different providers' note formats, and no built-in gap detection. Every one of those is exactly what a legal work product needs to be usable: an agent-drafted demand letter that can't point to the specific page supporting a claim isn't something an attorney can safely rely on or file.
Chartely's engine solves that by doing the extraction once, consistently, with a fixed output schema (ExtractedEvent, ChronologyMeta, TreatmentGap) that an agent can parse deterministically, rather than re-deriving structure from unstructured model output every time.
Calling the chronology API directly
The REST API takes a PDF (multipart upload) or raw extracted text (JSON body) and returns a full chronology result synchronously: a single POST to /api/v1/chronology with a bearer key, a PDF attached, and the response comes back before the next step in the agent's task needs it. Any anonymous caller can try it at a throttled rate before setting up an account.
The response is a single JSON object matching the ChronologyResult shape: meta (patient reference, provider and facility counts, first and last event date), the full events array with a pageRef on every entry, treatment gaps, a drafted narrative, and an overall confidence score. An agent can walk the events array directly to build a timeline view, or hand the narrative straight into a drafting step.
Calling it as an MCP tool
For agents built on the Model Context Protocol, the same engine is exposed as a hosted MCP server with three tools: build_chronology (a full record set to a full result), extract_medical_events (a lighter-weight call when only the event list is needed), and get_chronology (retrieve a previously built chronology by id). Adding the server to an agent's config is a single URL and an optional bearer-token header, no local process to install or run.
From there, an agent working a case can call build_chronology mid-task the same way it would call any other tool, no custom parsing logic, no prompt engineering around "please extract the dates from this document."
Why page citations matter even more for agent output
A human reviewing a chronology can sanity-check it against their own read of the file. An agent drafting a document from a chronology has no independent check, unless every claim it makes traces back to a page number it can cite. That's the entire reason the pageRef field exists on every single event, not as a nice-to-have, as the mechanism that makes agent-generated legal work verifiable.
When an agent drafts a demand letter section from a chronology event, it can (and should) carry the page citation forward: "per the emergency department note dated [date], page 14 of the records..." That's what turns an agent's output from something that needs to be entirely re-verified by hand into something a paralegal can spot-check against the specific pages cited.
What agents typically do with the result
- Populate a case timeline view directly from the events array, no separate parsing step.
- Flag treatment gaps automatically for a paralegal to review and explain before a demand letter goes out.
- Feed the narrative field into a drafting step for a demand letter or case summary, with citations preserved.
- Compare a new supplemental record set's events against an existing chronology to spot what's new.
None of this requires custom extraction logic per agent. The schema is fixed, the citations are built in, and the anonymous tier means an agent can be tested against it before any account or billing setup is needed.
Handling errors and low-confidence results
An agent calling the tool needs a plan for the response that isn't a clean success, and the engine is built to make that plan simple: a failed extraction returns a typed error with a specific code (an unreadable file, an unsupported type, a file that doesn't look like medical records at all) rather than a vague failure or a hallucinated partial result. A successful extraction still carries a warnings array and a confidence score, so an agent can set its own threshold, escalate to a human for review below a certain confidence, and proceed automatically above it.
That combination, typed errors instead of silent failure, and a graded confidence signal instead of a binary pass or fail, is what makes it reasonable to wire this into an unattended agent workflow rather than something that always needs a human standing by the console.
A safe hand-off pattern for legal AI agents
The useful boundary is simple: let the agent organise and surface the record, but do not let it turn an uncertain extraction into an asserted legal fact. A chronology result gives the next workflow step structured evidence and a direct route back to the source. It should not be treated as a substitute for the professional judgment that decides what the evidence means.
| Result signal | Agent action |
|---|---|
| Complete result with cited events | Use the structured event list and preserve citations in the next draft. |
| Low-confidence event or warning | Flag it for a paralegal or attorney to compare with the source page. |
| Unreadable or unsupported file | Return the typed error and request a usable source document. |
| Treatment gap | Ask for missing records or a factual explanation; do not invent one. |
A chronology tool makes the review path explicit instead of hiding uncertainty in generated prose.
Security and deployment choices still belong to the firm
An API contract is only one part of a safe agent workflow. The firm still decides which records may enter the system, who can invoke the tool, how source files are retained and how a reviewer signs off on the output. Those decisions should be made before a live file reaches an automated workflow, not improvised after a useful-looking draft appears. The NIST AI Risk Management Framework is a useful general reference for treating risk management as an ongoing practice rather than a one-time vendor questionnaire.
For the tool connection itself, Model Context Protocol uses an explicit client-server architecture with declared capabilities. Read the official MCP architecture guidance alongside the product documentation, then give the agent only the capability and data access it needs for the job. Keep audit logs long enough to investigate an output, test the rejected-file and low-confidence paths as carefully as the happy path, document who owns the final review, and rehearse the escalation path before a deadline arrives. In a legal setting, narrow permissions and a visible review queue are much less exciting than an autonomous demo, but they are what make the workflow manageable when a file is messy or the stakes rise.
See the full API reference, MCP tool list and OpenAPI spec.
Read the developer docsFrequently asked questions
Can an AI agent use a medical chronology API?
Yes. An agent can send a record set to a chronology API, then use the returned events, citations, gaps and confidence signals as structured input for a later task.
Why does an AI legal agent need page citations?
A page citation lets a reviewer check the source of a claim quickly. Without it, a generated draft still requires a broad re-read of the records before anyone can safely rely on it.
What should happen when a chronology result is low confidence?
The workflow should route the cited event or file to human review. Low confidence is a review signal, not permission for the agent to guess or silently omit the issue.
This guide is general reference, not legal or medical advice. To try it on a real record set, use the medical chronology builder, or see how the same engine works from your own code or an AI agent.
More guides
Build a chronology, then build on it
Build a chronology free, then get an API key for your software or your AI agent, no card to start.