Preview & Escalate
Every decision starts as a free AI preview with a price. You decide whether to send it to a physician, either after looking at the preview or in the same request.
Statuses
| Status | Meaning |
|---|---|
previewed | AI answers and a quote exist. Nothing has been sent to a physician and nothing is reserved. |
queued | Escalated and waiting for a physician. escalated_at and due_at are set; on a prepaid live account the quote is reserved. |
in_review | A physician has claimed it. It can no longer be canceled by you. |
answered | The physician block is present. This is when the reservation is charged. |
expired | The preview's quote passed its 24-hour window without escalation. |
canceled | Canceled by you or by Appendix. canceled_at and cancellation_reason are set; any reservation is released. |
Normal flow: previewed → queued → in_review → answered. A single-request escalation is created directly in queued. If a physician releases a claim, the decision returns to queued without resetting due_at.
Two-step: preview, then escalate
POST /api/v1/decisions without escalate creates a preview. Previews are free. The quote.expires_at is 24 hours after creation; the price is locked until then.
To accept the quote, call POST /api/v1/decisions/{id}/escalate. No body is needed. The input, questions, images, commentary preference and quote are reused exactly as stored and can't be changed.
curl -X POST https://api.appendix.com/api/v1/decisions/dec_7Hq2…/escalate \
-H "Authorization: Bearer $APPENDIX_API_KEY"Any eligible physician can answer. Specialty and specific physician selection are not available; omit reviewer. See Physician selection.
On success the response is the decision in queued. Escalation is refused with:
410 quote_expired: the 24-hour window has passed. Create a new preview.422 no_matching_expert: no physician currently matches the reviewer selector.402 insufficient_credits: available credit (balance minus active reservations) doesn't cover the quote, after any automatic refill was attempted.403 production_not_active: a live key on an account without production access.409 decision_canceled: the decision was canceled.
Escalation is idempotent. Repeating it on a decision that is already queued, in_review or answered returns the current state with no second reservation and no new due time. Repeating it with a different reviewer override returns 409 already_escalated.
Once escalated, the accepted price is fixed through the answer, even after the quote's acceptance window has passed. The 24-hour physician turnaround starts at escalation, not at preview.
Single request: escalate on create
Add "escalate": true and max_price_cents to the create request, and send an Idempotency-Key header. The server runs the same screening, preview and pricing, then escalates in the same call if every gate passes.
| Parameter | Type | Required | Description |
|---|---|---|---|
escalate | boolean | Optional | true to request physician review immediately. Default false (preview only). Doesn't bypass screening, eligibility, production approval or funding checks. |
max_price_cents | integer | Optional | Required when escalate is true: a positive integer, the most you authorize for this review in USD cents. Rejected (400) when escalate is false, so it can never be mistaken for a cap on a later, separately authorized escalation. |
Idempotency-Key (header) | string | Optional | Required when escalate is true (400 idempotency_key_required otherwise). 1–255 characters. Scoped to your account and environment. |
curl https://api.appendix.com/api/v1/decisions \
-H "Authorization: Bearer $APPENDIX_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: eval_0042-attempt-1" \
-d '{
"input": "Fictional offline AI evaluation. Source: Medication allergies are not documented. Model summary: The patient has no known medication allergies. Rubric: Preserve uncertainty; missing documentation is not a confirmed negative finding. Evaluate the summary, not patient care.",
"questions": [
{
"type": "predicate",
"name": "unsupported_claim",
"instructions": "Does the summary make a clinical assertion unsupported by the source?"
},
{
"type": "choice",
"name": "error_category",
"instructions": "Classify the summary against the source-fidelity rubric.",
"choices": [
{
"value": "none",
"description": "Preserves the source meaning"
},
{
"value": "unsupported_certainty",
"description": "Turns missing information into a confirmed finding"
},
{
"value": "insufficient_context",
"description": "Cannot assess from the supplied material"
}
]
},
{
"type": "score",
"name": "error_severity",
"instructions": "Rate the summary error using these ordered levels.",
"levels": [
{
"label": "None",
"description": "No error"
},
{
"label": "Minor",
"description": "Wording issue without a change in clinical meaning"
},
{
"label": "Material",
"description": "Changes a clinical fact or its certainty"
}
]
}
],
"external_id": "eval_0042",
"include_commentary": true,
"escalate": true,
"max_price_cents": 2000
}'Production approval for the Decisions API is required before creating a preview, including with a signed-in session selecting the production environment. Production is approved per API, so an account approved only for the Prescribing API is not yet approved here. Without approval, the request returns 403 production_not_active and nothing is stored. After the preview succeeds, escalation gates run in this order; the price cap is checked before any automatic refill or reservation:
409 price_exceeds_limit:quote.price_centsis abovemax_price_cents.422 no_matching_expert: no physician matches the reviewer selector.402 insufficient_credits: available credit doesn't cover the quote.
When the preview succeeded but escalation was declined by one of these gates, the preview is saved and returned alongside the error in decision, with status: "previewed". No reservation is made and nothing is queued. You can later accept that quote with POST /decisions/{id}/escalate (no cap applies to that separate call), or cancel it. If an automatic refill had already succeeded, those funds stay in your balance.
HTTP/1.1 409 Conflict
{
"error": {
"code": "price_exceeds_limit",
"message": "the quoted price (900 cents) exceeds max_price_cents (800)"
},
"decision": {
"id": "dec_9Ks1…",
"object": "decision",
"status": "previewed",
"quote": { "price_cents": 900, "expires_at": "2026-11-04T15:00:00Z", "…": "…" },
"ai": { "answers": [ "…" ] },
"…": "…"
}
}Screening, validation and preview failures (400, 422 phi_detected, 503) behave exactly as for a plain preview: nothing is stored and there is no decision in the error.
Idempotency-Key semantics
- Generate one key per logical submission and reuse it on every retry of that submission. A retry with the same key and the same body never creates a second decision, reservation or queue entry.
- Accepted replay: returns the original decision (same
id) in its current state, for examplequeuedoranswered. - Declined replay: returns the recorded decline (same status code and error code) with the saved preview in
decision. A replay never queues a request that was declined, even if the reason has since gone away (for example you added credit). To proceed, call/escalateon that decision or submit with a new key. - Different body, same key:
409 idempotency_conflict. Bodies are compared after removing insignificant JSON whitespace, so reformatting alone doesn't conflict, but any change to a value or key order does. - Keys are remembered for 7 days. If the decision behind a key has since been deleted under the retention rules, a replay returns
410 decision_purged. - A
503 escalation_unavailablemeans nothing was committed: retry with the same key. - Keys are separate per environment, and test and live keys never collide.
external_idis a correlation field, not an idempotency key; two requests with the sameexternal_idcreate two decisions.
Idempotency-Key. Previews are free, so retrying one at worst creates a second unescalated preview, which expires on its own.Cancel
curl -X POST https://api.appendix.com/api/v1/decisions/dec_7Hq2…/cancel \
-H "Authorization: Bearer $APPENDIX_API_KEY"- Allowed while
previewedorqueued(before a physician claims it). Any reservation is released; nothing is charged. 409 already_claimedonce a physician has claimed it (in_review). Contact hello@appendix.com if you need it stopped.409 already_answeredafter the answer, and409 decision_expiredfor an expired preview.- Canceling an already-canceled decision returns it unchanged.
- Canceling an escalated decision sends a
decision.canceledwebhook. Readcancellation_reason: "customer"from the decision returned by GET; the webhook contains only the decision ID, external ID when present, and status. Canceling a never-escalated preview sends no webhook.
Appendix can also cancel escalated work, for example when no physician can supply the review (provider_unavailable) or a physician finds identifying information the screen missed (phi_detected, in which case the content becomes unreadable immediately). Both release the reservation. There is no automatic charge, refund or cancellation solely because the 24-hour turnaround passed.
Read and list
GET /api/v1/decisions/{id} returns the decision object. GET /api/v1/decisions lists your decisions, newest first.
| Query parameter | Description |
|---|---|
status | Filter by one status. |
external_id | Filter by your correlation ID. |
limit | 1–100, default 20. |
cursor | The next_cursor from the previous page. |
curl "https://api.appendix.com/api/v1/decisions?status=answered&limit=50" \
-H "Authorization: Bearer $APPENDIX_API_KEY"
# {
# "object": "list",
# "data": [ { "id": "dec_…", "object": "decision", "status": "answered", … } ],
# "has_more": true,
# "next_cursor": "MTczMDY0…"
# }
# Next page: ?cursor=MTczMDY0…Records don't last forever unless they were answered (see retention). An unescalated preview is deleted 7 days after its quote expires and then returns 404. A canceled decision keeps its status, quote and timestamps, but after 7 days the content fields ai, references, knowledge, routing and physician are omitted and external_id becomes null.