Quickstart
Preview, escalate and read a physician's answer in about a minute. Use a test key and the answer comes from a simulated physician, with no charge.
1. Get a test key
Open the developer dashboard (sign up or sign in) and create a test key. It looks like ak_test_…. Export it:
export APPENDIX_API_KEY=ak_test_...2. Create a preview
Send a model output, source context, and rubric as input with one or more typed questions. Don't include names, dates of birth or other identifiers; requests that contain them are rejected (see PHI policy).
curl https://api.appendix.com/api/v1/decisions \
-H "Authorization: Bearer $APPENDIX_API_KEY" \
-H "Content-Type: application/json" \
-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
}'The response has status: "previewed", the AI's typed answers, the references it was given, and a quote valid for 24 hours. Previews are free.
The response below is illustrative; token counts and answers vary by request.
{
"id": "dec_7Hq2…",
"object": "decision",
"status": "previewed",
"sandbox": true,
"created_at": "2026-11-03T15:00:00Z",
"external_id": "eval_0042",
"include_commentary": true,
"reviewer": {
"expert_ids": [],
"specialties": [],
"turnaround": "24h"
},
"quote": {
"price_cents": 500,
"currency": "usd",
"input_tokens": 200,
"image_count": 0,
"billable_tokens": 200,
"question_count": 3,
"turnaround": "24h",
"expires_at": "2026-11-04T15:00:00Z"
},
"escalated_at": null,
"due_at": null,
"disclaimer": "This answer is provided for informational and educational purposes only, based on the material you submit. It is not medical advice, does not create a physician-patient relationship, and you remain responsible for any decision made using it.",
"ai": {
"answers": [
{
"type": "predicate",
"name": "unsupported_claim",
"probability": 0.95
},
{
"type": "choice",
"name": "error_category",
"choice": "unsupported_certainty",
"confidence": 0.9,
"probabilities": [
{
"value": "none",
"probability": 0.03
},
{
"value": "unsupported_certainty",
"probability": 0.94
},
{
"value": "insufficient_context",
"probability": 0.03
}
]
},
{
"type": "score",
"name": "error_severity",
"score": 1.9,
"confidence": 0.9,
"probabilities": [
{
"value": 0,
"label": "None",
"probability": 0.02
},
{
"value": 1,
"label": "Minor",
"probability": 0.06
},
{
"value": 2,
"label": "Material",
"probability": 0.92
}
]
}
]
},
"references": [],
"knowledge": {
"status": "no_matches"
},
"routing": {
"suggested": {
"specialties": [],
"expert_ids": []
},
"has_eligible_experts": true
}
}The same call from Python or TypeScript:
import os, requests
resp = requests.post(
"https://api.appendix.com/api/v1/decisions",
headers={"Authorization": f"Bearer {os.environ['APPENDIX_API_KEY']}"},
json={
"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?"},
],
"external_id": "eval_0042",
},
timeout=120,
)
resp.raise_for_status()
decision = resp.json()
print(decision["id"], decision["ai"]["answers"], decision["quote"]["price_cents"])3. Escalate to a physician
Accept the quote by escalating. No body is needed; the stored question, images and quote are reused.
curl -X POST https://api.appendix.com/api/v1/decisions/dec_7Hq2…/escalate \
-H "Authorization: Bearer $APPENDIX_API_KEY"The decision moves to queued with escalated_at and due_at (24 hours later). On a live prepaid account, the quoted amount is reserved now and charged only when the physician answers.
4. Read the answer
With a test key, the simulated physician answers about one second after escalation. Fetch the decision:
curl https://api.appendix.com/api/v1/decisions/dec_7Hq2… \
-H "Authorization: Bearer $APPENDIX_API_KEY"{
"id": "dec_7Hq2…",
"object": "decision",
"status": "answered",
"escalated_at": "2026-11-03T15:01:10Z",
"due_at": "2026-11-04T15:01:10Z",
"disclaimer": "This answer is provided for informational and educational purposes only, based on the material you submit. It is not medical advice, does not create a physician-patient relationship, and you remain responsible for any decision made using it.",
"…": "…",
"physician": {
"expert": {
"id": "exp_example",
"name": "Example Reviewer, MD",
"specialties": [
"internal_medicine"
]
},
"answers": [
{
"type": "predicate",
"name": "unsupported_claim",
"value": true,
"confidence": 0.9,
"comment": "Not documented means unknown, not \"no known allergies.\""
},
{
"type": "choice",
"name": "error_category",
"choice": "unsupported_certainty",
"confidence": 0.9,
"comment": "Missing documentation became a confirmed negative."
},
{
"type": "score",
"name": "error_severity",
"level": 2,
"label": "Material",
"confidence": 0.8,
"comment": "A false \"no allergies\" can lead to a harmful prescription."
}
],
"answered_at": "2026-11-04T09:12:00Z"
}
}In production, register a webhook endpoint and wait for decision.answered instead of polling tightly. A simple poll loop for testing:
# Poll until the physician answers (or use webhooks; see Webhooks & Polling)
while true; do
STATUS=$(curl -s https://api.appendix.com/api/v1/decisions/dec_7Hq2… \
-H "Authorization: Bearer $APPENDIX_API_KEY" | jq -r .status)
echo "$STATUS"
case "$STATUS" in answered|canceled) break ;; esac
sleep 5
doneOr: one request
When you already know you want a physician, submit and escalate together. Add escalate: true, a max_price_cents cap, and an Idempotency-Key header that you reuse on retries.
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
}'On success the response is the decision with status: "queued". If the preview succeeds but escalation is declined (for example the price is above your cap), you get an error and the saved preview in decision. Details in Preview & Escalate.
Next
- Question types: predicate, choice and score, plus JSON and image input.
- Choosing a reviewer: planned specialty and physician selection (not yet available).
- Pricing: how the quote is computed.