Versioning and changelog

The version is part of every path. Changes inside /v1 don't break working integrations; breaking changes go to a new version, announced at least 90 days ahead.

Versions

The current version is v1, and every path starts with /v1. The OpenAPI document describes it.

Changes within v1

These changes can happen within /v1 at any time, so write your integration to accept them:

New endpoints.
New optional request fields and query parameters. A field that a version doesn't take is refused with 400 invalid_request (unknown field), so send only the fields that are documented.
New fields in responses, including in the report. Ignore fields that you don't recognize.
Changes to error messages. Error codes stay the same; branch on code, not message.

Breaking changes

A breaking change ships as a new version, such as /v2. Breaking changes include removing or renaming a field or an endpoint, making an optional field required, changing a field's type, and changing an error code's meaning.

When a new version ships, it's announced in this changelog at least 90 days before /v1 changes or is retired. During that time, both versions work.

OpenAPI document

The OpenAPI 3.1 document for /v1 is served without authentication at /v1/openapi.json. Open the OpenAPI document.

curl

curl -s https://api.medchartscan.io/v1/openapi.json

Changelog

2026-10-26: stricter requests and new headers

Changed, without a version change:

Request bodies refuse unknown fields with 400 invalid_request (unknown field), at every level, including cpts, patient_demographics, active_problems, and batch items. Before, they were ignored, so a misspelled field (such as analysis_id on a batch retry) silently changed what the request did.
jurisdiction, and your organization's default state, must be one of the 50 states, DC, AS, GU, MP, PR, or VI. Any other code gets 400.
Clearer validation messages for a body that isn't a JSON object, isn't valid JSON, or isn't UTF-8 (all 400 invalid_request). See Validation messages.
RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers on reads, POST /v1/analyses, and POST /v1/batches. See RateLimit headers.
Every GET endpoint also answers HEAD, with the same status and headers and no body. A HEAD counts as a read.
409 idempotency_in_progress has Retry-After: 2; a 405 has an Allow header.
The OpenAPI document lists https://api.medchartscan.io as its server, marks the response fields that are always present as required, and documents 500 internal_error on every operation.

2026-10-25: limits

Changed, without a version change:

429 too_many_uncharged_runs: at most 25 notes per organization in 24 hours that end out of scope or fail.
The per-minute limit is 10 calls until an organization first buys credits, then 60.
429 rate_limited on reads (GET requests and POST /v1/analyses/search) past 600 per API key per minute.
429 too_many_uncharged_runs on a batch or batch retry when the notes in progress plus the batch's notes would pass the uncharged limit (125 in 24 hours, 75 until an organization first buys credits).
409 analysis_running on DELETE /v1/analyses/{id} for a note that's still running.
413 request_too_large for request bodies over 1 MB (12 MB for POST /v1/batches).
active_problems takes up to 50 entries of up to 500 characters; patient_demographics strings are limited to 100 characters.
Times before 2000-01-01 or after 2100-01-01 in created_after, created_before, and cursors get 400.
Failed token authentications are limited to 30 per IP address per minute. Past that, only failing requests get 429; the right client ID and secret still get a token. Malformed requests don't count.

2026-10-25: review fields and channel

Added, without a version change (new fields only):

channel, submitted_code, coding_change, missed_revenue_count, and denial_risk_count on every analysis response and list item, and the four review fields on every batch item.
The channel, coding_change, has_missed_revenue, and has_denial_risk filters on POST /v1/analyses/search.

2026-10-25: v1

The first version of the API:

POST /v1/oauth/token: access tokens with the OAuth 2.0 client credentials flow.
POST /v1/analyses, GET /v1/analyses, POST /v1/analyses/search, GET /v1/analyses/{id}, and DELETE /v1/analyses/{id}: analyze one note and manage results.
POST /v1/batches, GET /v1/batches, GET /v1/batches/{id}, and POST /v1/batches/{id}/retry: up to 100 notes per batch, analyzed in the background.
GET /v1/credits: the credit balance.
Idempotency-Key on both POST endpoints that analyze notes, and test mode with "test_data": true.