Skip to main content

Decisions API

For evaluating medical AI, not for direct patient care. Physician judgments from the Decisions API are for testing and improving your AI, not for deciding an individual patient’s diagnosis, treatment, or triage. Need a physician to care for or prescribe to your patients? Use the Prescribing API.

Building with an AI agent? Copy for LLM (above) puts the entire Decisions API contract (request format, answer shapes, escalation, webhooks, pricing, errors) on your clipboard as one prompt you can hand to your agent.

Appendix supplies structured physician judgments for evaluating medical AI, in the structured-decision style of OpenAI’s Decisions API and TypeSafe’s Jev. Send a model output, its source context, and rubric questions for release comparisons, retrospective quality review, or labeled datasets. Try a free AI preview with an upfront quote, then request a physician judgment within 24 hours. The API returns typed answers your evaluation pipeline can use.

How it works

  1. Preview (free). POST /api/v1/decisions with your evaluation item (input) and typed questions (three included). You get AI answers, references, and a quote that is valid for 24 hours.
  2. Escalate. POST /api/v1/decisions/{id}/escalate sends the same question to a physician without re-sending any data. On a prepaid account the quoted amount is reserved; nothing is charged yet.
  3. Get the answer. A physician answers within 24 hours. You receive a decision.answered webhook, then read the physician block with GET /api/v1/decisions/{id}. The reservation is charged only when the physician answers.

Established integrations can also submit and escalate in a single request with escalate: true, a max_price_cents spending cap and an Idempotency-Key header. See Preview & Escalate.

A first request

Create a preview
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
}'

Continue with the Quickstart.

What you get back

FieldWhat it is
ai.answersOne typed AI answer per question, in order, with model probabilities. An AI answer can be a refusal.
referencesThe knowledge-base excerpts supplied to the AI as context, with source metadata. Context, not verified citations for every answer.
knowledge.statusused, no_matches, not_applicable or unavailable.
quoteThe price to send this question to a physician, the exact token count it was computed from, and when the quote expires.
routingEmpty suggested reviewer lists and has_eligible_experts for your reviewer selector.
physicianAfter escalation and answer: the physician's selected answers, physician-reported confidence, and a comment on each answer when the physician wrote one or you requested commentary.
disclaimerA fixed statement on every decision object: the answer is provided for informational and educational purposes only, based on the material you submit. It is not medical advice, creates no physician–patient relationship, and you remain responsible for decisions made with it. Keep it with the answer wherever you store, show or forward it.

What a decision is, and isn't

The Decisions API is for evaluating AI outputs, not approving an individual's diagnosis, treatment, or triage. Each answer is one physician's judgment, not a certification that your system is safe or a guarantee of ground truth. You remain responsible for how you use the results. Don't send protected health information or anything that identifies a person: every field and image is screened and identifying requests are rejected. See the PHI policy and the Developer Terms.

If you need a physician to treat or prescribe for your own users, see the Prescribing API instead.

Keys and environments

Create keys in the developer dashboard. The Decisions API uses the same developer keys, webhook endpoints and credit balance as the rest of the developer platform. Send the key as Authorization: Bearer ak_test_… or ak_live_….

  • Test keys are instant. Previews are real; escalation gets a simulated physician answer within seconds, and nothing is charged. See Sandbox.
  • Live keys reach real physicians. They require the same production activation as the rest of the platform (card on file, identity verification, accepted terms, and approval).
  • A key only sees decisions created in its own environment. A test key asking for a live decision gets a 404.

Endpoints

MethodPathPurpose
POST/api/v1/decisionsCreate a preview and quote (optionally escalate in the same request).
GET/api/v1/decisions/{id}Read a decision, including the physician answer once delivered.
GET/api/v1/decisionsList, filterable by status and external_id, cursor-paginated.
POST/api/v1/decisions/{id}/escalateSend a previewed decision to a physician.
POST/api/v1/decisions/{id}/cancelCancel before a physician claims it.
GET/api/v1/decisions/specialtiesReserved vocabulary endpoint; currently an empty list (public, no key).
GET/api/v1/expertsThe expert directory (key required).
GET/api/v1/experts/{id}One expert's public profile (key required).

The base URL is https://api.appendix.com. All bodies are JSON. Errors use one shape; see Errors & Limits.

Guides