Idempotency

An Idempotency-Key header makes a POST request safe to retry. If the first attempt went through, a retry with the same key returns its response instead of analyzing the note again, so you're never charged twice.

When to use it

Send a key with every POST /v1/analyses and POST /v1/batches request that you might retry, such as after a timeout, a dropped connection, or a crash in your own code. Other endpoints don't take a key: reads and deletes are safe to repeat as they are.

Choose a key

Use 1 to 255 printable ASCII characters. A UUID works well.
Create one key for each note or batch you mean to send, and use the same key for every attempt to send it.
Store the key with your own record of the request, so that a retry after a restart can reuse it.

An invalid key returns 400 invalid_request.

curl -s https://api.medchartscan.io/v1/analyses \
  --max-time 300 \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 2c9e4b1d-5f7a-4e08-b3c6-8a1f0d2e7b45" \
  -d '{
    "document_text": "Established patient seen for follow-up of type 2 diabetes and hypertension. Reports good adherence to metformin; no hypoglycemia. BP 138/86. A1c 7.4% reviewed. Assessment: diabetes, improving; hypertension, not at goal. Plan: increase lisinopril to 20 mg daily, recheck BMP in 2 weeks, follow up in 3 months.",
    "client_reference": "enc-2026-10-25-0001"
  }'

What happens on a retry

Keys belong to your organization and last 24 hours: any of the organization's API keys that sends the same Idempotency-Key gets the same outcome. The API compares the endpoint and the request body. Bodies match when they have the same values, even if the fields are in a different order or a field with its default value is left out.

When you retry with the same key	The response
The first request finished, and the body matches	The first response again: the same status and body, except for batches, which replay their current state (see Which responses are kept). The header `Idempotent-Replayed: true` is added. Nothing runs or is charged again.
The first request is still running	`409` `idempotency_in_progress`, with `Retry-After: 2`. Retry after that many seconds.
The body is different, or the key was used on the other endpoint	`409` `idempotency_conflict`. Nothing runs.
The result was deleted after the first request	`404` `not_found`. The note isn't analyzed again.
More than 24 hours have passed	The request runs as a new request.

A replayed body can list its JSON fields in a different order than the first response did. The values are the same.

Which responses are kept

First response	Kept for replay?
`200` (succeeded or out of scope)	Yes.
`202` (batch created)	Yes. A replay returns `202` with the batch as it is now, with current statuses, not the original body.
`502` `analysis_failed`	Yes. To try the note again, use a new key.
`402`, `403`, `422`, `429`	No. Nothing ran, so the key is released: fix the cause and retry with the same key.
`500` before the note is admitted	No. Nothing ran, so the key is released: retry with the same key.
`400`, `401`, `413`	No. The request was rejected before the key was used.

If the first request stopped

If your client times out or loses the connection, retry with the same key. While the first request is still running, you get 409 idempotency_in_progress; once it finishes, you get its response.

If the first request stopped on the server, for example during a restart, the key stays in progress for up to 10 minutes. After that, a retry returns the outcome of the analysis or batch that the first request started, and runs the request only if the first one never started. A key never leads to a second charge for the same request.

Note:

A replayed analysis response can contain the report, which includes text quoted from the note. Replays are available only to your organization's API keys, for 24 hours, and deleting the result also deletes the stored response.