Reference

API reference

Every endpoint below is generated from the same catalog the API serves, this page can’t drift from what’s actually deployed. Machine-readable versions: /api/openapi and /llms.txt.

Base URL

https://chartely.com/api/v1

Auth

Optional for /chronology and /pricing (anonymous = throttled trial, no API/MCP access on Free). Send `Authorization: Bearer cty_live_…` (or `x-api-key`) for a Pro/Scale key.

Metering

Metered by page (one record page = one billable unit).

Response envelope

Every successful /chronology response includes a request_id for tracing, a disclaimer, every event’s page citation and a confidence score. Free/anonymous responses also carry an attribution field.

{
  "chronology_id": "chr_9f3ac1d0",
  "status": "completed",
  "meta": {
    "patient_ref": "Jordan A. Rivera",
    "record_source": "Northgate Medical Group",
    "provider_count": 4,
    "facility_count": 3,
    "first_event_date": "2026-02-03",
    "last_event_date": "2026-05-19"
  },
  "events": [
    { "date": "2026-02-03", "event_type": "emergency", "provider": "Dr. R. Okafor", "facility": "Northgate Emergency Dept", "title": "ER visit, rear-end collision", "summary": "...", "page_ref": 3, "confidence": "high" },
    { "date": "2026-02-10", "event_type": "imaging", "provider": "Dr. L. Bennett", "facility": "Cascade Imaging Center", "title": "MRI cervical spine", "summary": "...", "page_ref": 11, "confidence": "high" }
  ],
  "gaps": [
    { "from_date": "2026-03-03", "to_date": "2026-05-19", "days": 77, "after_event_index": 3 }
  ],
  "narrative": "Jordan Rivera was seen at Northgate Emergency Dept on Feb 3, 2026 following a rear-end collision...",
  "page_count": 34,
  "event_count": 5,
  "confidence": 0.91,
  "engine": "anthropic-api",
  "warnings": [],
  "request_id": "req_9f3ac1d0",
  "disclaimer": "Chartely organizes the medical records you provide. It is not legal or...",
  "attribution": "Built with Chartely (https://chartely.com) - the medical chronology API. Free tier responses require this attribution."
}

Errors

Structured, never silent

Every non-2xx response is JSON, never a fabricated fallback.

code	status	meaning
invalid_request	400	A required field is missing or malformed, or the uploaded file was empty.
unauthorized	401	The Authorization header is missing a valid, unrevoked API key for an endpoint that requires one.
upgrade_required	402	The Free plan has no API/MCP access, or the requested export format needs Pro or Scale.
not_found	404	No chronology exists for the given id (or it belongs to a different owner).
payload_too_large	413	The file exceeds the size limit.
unsupported_media_type	415	Only PDF records (or raw text) are supported right now.
unprocessable	422	The file couldn't be read as medical records, was too degraded to extract reliably, or extraction couldn't produce a valid result, never a fabricated fallback.
rate_limited	429	You've exceeded your plan's per-minute burst rate or the anonymous daily cap.
not_configured	503	A required backend credential isn't configured on our side.
upstream_unavailable / upstream_timeout	502 / 504	The extraction backend didn't respond correctly in time. Safe to retry with backoff.
internal	500	An unexpected server error. Safe to retry; contact support if it persists.

error response

{
  "error": {
    "code": "unprocessable",
    "message": "This file doesn't look like medical records."
  },
  "request_id": "req_9f3ac1d1"
}

Rate limits

By plan

Tier	Burst	Volume	Batch
Anonymous	4/min	20/day	No API access, trial only
Free	n/a	50/mo (web only)	No API/MCP access
Pro	120/min	1,000/mo incl., then $0.06/page	Up to 25 files/call
Scale	600/min	7,500/mo incl., then $0.04/page	Up to 200 files/call

Full plan details at /pricing or the machine-readable /api/v1/pricing.

Endpoints

Every route

POST

/api/v1/chronology

Auth optional

Build a page-cited chronology from a case medical-record PDF or text - every event dated, cited to its page, with treatment gaps flagged.

Param	In	Required	Description
file	body	no	multipart/form-data field with the PDF (alternative to text/file_base64/file_url).
text	body	no	Already-extracted record text (JSON body).
file_base64	body	no	Base64-encoded PDF bytes (JSON body).
file_name	body	no	Original file name, used with file_base64.
file_url	body	no	https:// URL to fetch the PDF from (fetched server-side, SSRF-guarded).
matterName	body	no	Optional case/matter name to store with the chronology.
matterType	body	no	personal_injury \| medical_malpractice \| workers_comp \| mass_tort \| disability \| other.
format	query	no	csv \| json \| word - return a converted file instead of JSON. Word requires a Pro or Scale key.

curl -X POST https://chartely.com/api/v1/chronology \
  -H "Authorization: Bearer cty_live_..." \
  -F "file=@records.pdf"

POST

/api/v1/chronology/batch

Requires paid key

Build chronologies for several record sets in one call (Pro: up to 25, Scale: up to 200). One bad file fails only that item, never the whole batch.

Param	In	Required	Description
file	body	no	multipart/form-data: repeat this field once per file. A shared matter_name/matter_type field applies to the whole batch.
items	body	no	JSON body: array of { text \| file_base64 (+file_name) \| file_url, matter_name?, matter_type? } - one entry per record set.
matter_name	body	no	Batch-level default, JSON body only (multipart uses the shared form field above).
matter_type	body	no	Batch-level default; personal_injury \| medical_malpractice \| workers_comp \| mass_tort \| disability \| other.

curl -X POST https://chartely.com/api/v1/chronology/batch \
  -H "Authorization: Bearer cty_live_..." \
  -F "file=@case-a.pdf" -F "file=@case-b.pdf"

GET

/api/v1/chronologies

Requires paid key

List the caller's own saved chronologies, newest first.

curl https://chartely.com/api/v1/chronologies -H "Authorization: Bearer cty_live_..."

GET

/api/v1/chronologies/{id}

Requires paid key

Get one saved chronology with its full event list.

Param	In	Required	Description
id	path	yes	Chronology id returned by POST /chronology.

curl https://chartely.com/api/v1/chronologies/CHRONOLOGY_ID -H "Authorization: Bearer cty_live_..."

GET

/api/v1/chronologies/{id}/export

Requires paid key

Download a saved chronology converted to CSV, JSON or Word.

Param	In	Required	Description
id	path	yes	Chronology id.
format	query	yes	csv \| json \| word.

curl -OJ "https://chartely.com/api/v1/chronologies/CHRONOLOGY_ID/export?format=word" -H "Authorization: Bearer cty_live_..."

GET

/api/v1/pricing

Auth optional

Machine-readable pricing - plans, included pages, per-page overage, rate limits and features.

curl https://chartely.com/api/v1/pricing

Chartely organizes the medical records you provide. It is not legal or medical advice, and automated extraction can misread poor-quality scans. Review the chronology before you rely on it. Every event links to its source page, so review takes minutes, not days.