Skip to main content

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).

POST /api/v1/decisions
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.

200 OK (illustrative)
{
  "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.

POST /api/v1/decisions/{id}/escalate
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:

GET /api/v1/decisions/{id}
curl https://api.appendix.com/api/v1/decisions/dec_7Hq2… \
  -H "Authorization: Bearer $APPENDIX_API_KEY"
200 OK (answered, excerpt)
{
  "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
done

Or: 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.

Submit and escalate
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