Graphite by Augsidius

API reference

Augsidius API

Endpoints, parameters and response objects. For guides and concepts, see the documentation.

Overview

Introduction

The Augsidius API is a REST API with an OpenAI-compatible chat-completions surface. Requests and responses are JSON. All endpoints are served from https://api.augsidius.care/v1.

You can use any OpenAI client library by setting the base URL and using an Augsidius key. Augsidius-specific options travel in the augsidius object of the request. Structured results come back as JSONL in message.content, with the call's summary in message.augsidius.

Base URL

https://api.augsidius.care/v1

Authentication

Authenticate with an API key in the Authorization header. Keys are created in Dashboard → API keys and are scoped to a project and an environment (aug_test_ sandbox, aug_live_ production).

Keep keys secret. Never use them in browsers or mobile apps — call the API from your server.

cURL

curl https://api.augsidius.care/v1/models \
  -H "Authorization: Bearer $AUGSIDIUS_API_KEY"

Errors

Errors return a JSON body with an error object and a standard HTTP status. code is stable and safe to branch on; message is human-readable. Retry 429 and 5xx with exponential backoff and an Idempotency-Key. See Errors for every code.

Response

{
  "error": {
    "type": "permission_error",
    "code": "scope_denied",
    "message": "This key does not have the agents:triage scope."
  }
}

Chat completions

Create chat completion

POST/v1/chat/completions

Runs a model. OpenAI-compatible: any OpenAI SDK works with the Augsidius base URL and key.

aug-evidence-qa returns answer text with [n] citation markers. aug-extract, aug-care-model and aug-cds return JSONL in message.content — one typed object per line, each with an object field. The call's summary is in message.augsidius. See Response types and Streaming & formats.

Request body

modelstringRequired
aug-evidence-qa, aug-extract, aug-care-model or aug-cds.
messagesarrayRequired
Chat messages. Q&A uses the last user message as the question; the other models use all user messages as the clinical text.
streamboolean
true for server-sent chat.completion.chunk events (one JSON line per chunk for JSONL models). Add Accept: application/x-ndjson for raw NDJSON.
stream_optionsobject
{"include_usage": true} adds a final usage chunk.
augsidiusobject
Augsidius options. Also accepted as metadata.augsidius.
Show properties
- session_idstring
  aug-care-model only. Continue a session; omit to start one.
- observationsarray
  aug-care-model, aug-cds. {text | concept_id, present}, up to 50.
- provider_scopearray
  aug-care-model, aug-cds. Action kinds: ask, examine, measure, test.

Returns

A chat.completion object, or a stream of chat.completion.chunk objects, or NDJSON lines.

Example request

curl https://api.augsidius.care/v1/chat/completions \
  -H "Authorization: Bearer $AUGSIDIUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "aug-cds",
    "messages": [{"role": "user", "content": "58M on metformin. Fever 39.2, headache, neck stiffness, no rash. eGFR 25."}]
  }'

Response

{
  "id": "chatcmpl_9f2c…",
  "object": "chat.completion",
  "created": 1794226698,
  "model": "aug-cds",
  "choices": [{
    "index": 0,
    "finish_reason": "stop",
    "message": {
      "role": "assistant",
      "content": "{\"object\":\"cds.card\",\"card\":{\"summary\":\"Rule out bacterial meningitis\",\"indicator\":\"critical\",…}}\n{\"object\":\"cds.card\",…}\n",
      "augsidius": {"object": "cds.summary", "cards": 5, "indicators": {"critical": 3, "warning": 0, "info": 2}, "billable_calls": 1}
    }
  }],
  "usage": {"prompt_tokens": 30, "completion_tokens": 2410, "total_tokens": 2440, "augsidius_units": 20}
}

Served models

aug-evidence-qaPreview

POST/v1/chat/completions

Cited answer to a clinical question. Each clinical sentence ends with [n] markers; message.augsidius.citations lists them with claim, certainty and sources (PubMed with a quoted sentence, or product label). Non-clinical and bulk-listing questions return message.refusal and are not billed. Input up to 2,000 tokens. 8 units per call. Guide

Example request

curl https://api.augsidius.care/v1/chat/completions \
  -H "Authorization: Bearer $AUGSIDIUS_API_KEY" -H "Content-Type: application/json" \
  -d '{"model": "aug-evidence-qa", "stream": true,
       "messages": [{"role": "user", "content": "Can metformin be continued at eGFR 25?"}]}'

Response

// message.content
"Metformin should not be continued at an eGFR of 25 mL/min/1.73 m² [5][9]. …"

// message.augsidius.citations
[
  {"index": 5,
   "claim": "Metformin is contraindicated in Severe renal impairment (eGFR < 30 mL/min/1.73 m²)",
   "certainty": "moderate",
   "detail": null,
   "sources": [{"type": "pubmed", "pmid": "32138474", "title": "…", "year": 2020,
                "url": "https://pubmed.ncbi.nlm.nih.gov/32138474/", "quote": "…"}]}
]

aug-extractPreview

POST/v1/chat/completions

Clinical entities from text, one extraction.entity per line: text, span, category, status (present / absent / possible), temporality, value, unit, concept, codes (SNOMED CT / ICD-11 codings, provisional). Summary extraction.summary with demographics. Input up to 4,000 tokens. 15 units per call per 500 input tokens. Guide

Example request

curl https://api.augsidius.care/v1/chat/completions \
  -H "Authorization: Bearer $AUGSIDIUS_API_KEY" -H "Content-Type: application/json" \
  -d '{"model": "aug-extract",
       "messages": [{"role": "user", "content": "No fever. Vomited twice. BP 150/90. On ramipril 5 mg OD."}]}'

Response

{"object":"extraction.entity","text":"fever","span":[3,8],"category":"symptom","status":"absent","temporality":"current","value":null,"unit":null,"concept":{"id":"c_qbxn…","name":"Fever","kind":"complaint"},"codes":[]}
{"object":"extraction.entity","text":"Vomited","span":[10,17],"category":"symptom","status":"present","temporality":"current","value":"twice","unit":null,"concept":{"id":"c_sypy…","name":"Vomiting","kind":"complaint"},"codes":[{"system":"http://snomed.info/sct","code":"422400008","status":"provisional"}]}
{"object":"extraction.entity","text":"ramipril","span":[39,47],"category":"drug","status":"present","temporality":"current","value":"5 mg OD","unit":null,"concept":{"id":"c_a2xx…","name":"Ramipril","kind":"drug"},"codes":[]}

aug-care-modelPreview

POST/v1/chat/completions

Adaptive care model. Lines in order: care_model.session, care_model.observation (per observation in this call), care_model.condition (ranked, weight, severity, must_not_miss, evidence), care_model.missing_observation (ranked; emergency rule-outs first), care_model.action (ranked next best actions with evidence). Continue with augsidius.session_id. Input up to 3,000 tokens. 20 units per call per 500 input tokens. Guide

Example request

curl -N https://api.augsidius.care/v1/chat/completions \
  -H "Authorization: Bearer $AUGSIDIUS_API_KEY" -H "Content-Type: application/json" \
  -H "Accept: application/x-ndjson" \
  -d '{"model": "aug-care-model", "stream": true,
       "messages": [{"role": "user", "content": "58M, fever 39.2, severe headache, neck stiffness, no rash."}]}'

Response

{"object":"care_model.session","session_id":"cc47ad4e…"}
{"object":"care_model.observation","text":"neck stiffness","status":"present","category":"sign","concept":{"id":"c_3o53…","name":"Nuchal rigidity","kind":"examination_finding"},"codes":[],…}
{"object":"care_model.condition","rank":1,"concept":{"id":"c_8kq1…","name":"Bacterial meningitis"},"weight":1.0,"probability_share":0.41,"severity":0.9,"must_not_miss":true,"time_critical":"hours","explained_by":["Fever","Headache","Nuchal rigidity"],"evidence":[…]}
{"object":"care_model.missing_observation","rank":1,"concept":{"id":"c_q7w2…","name":"Photophobia","kind":"complaint"},"weight":1.0,"rules_out_emergency":true,"for":["Bacterial meningitis"],"evidence":[…]}
{"object":"care_model.action","rank":1,"action":"test","label":"Cerebrospinal fluid analysis","weight":1.0,"rules_out_emergency":true,"resolves":["Bacterial meningitis"],"evidence":[…]}
{"object":"care_model.summary","session_id":"cc47ad4e…","emergencies_open":["Bacterial meningitis"],"unlinked":[],"counts":{…},"usage":{…}}

aug-cdsPreview

POST/v1/chat/completions

Decision-support cards in the HL7 CDS Hooks 2.0 card format, one cds.card per line, most important first. Kinds (source.topic.code): emergency_rule_out (critical), contraindication and interaction (critical / warning, only when they apply to this patient), diagnostic_workup and documentation_gap (info). Up to 8 cards. Input up to 3,000 tokens. 20 units per call per 500 input tokens. Guide

Example request

curl https://api.augsidius.care/v1/chat/completions \
  -H "Authorization: Bearer $AUGSIDIUS_API_KEY" -H "Content-Type: application/json" \
  -d '{"model": "aug-cds",
       "messages": [{"role": "user", "content": "On metformin and ramipril. K 5.9, eGFR 25. Plan: start spironolactone."}]}'

Response

{"object":"cds.card","card":{
  "uuid":"4c1e8a6e-…",
  "summary":"Spironolactone contraindicated: Hyperkalemia",
  "detail":"Spironolactone is contraindicated in Hyperkalemia.\n\nFor this patient: potassium is 5.9 mmol/L.\n\nCertainty: moderate.",
  "indicator":"critical",
  "source":{"label":"Augsidius Clinical Evidence","url":"https://augsidius.care",
            "topic":{"system":"https://api.augsidius.care/cds/card-kind","code":"contraindication","display":"Contraindication"}},
  "suggestions":[{"label":"Review Spironolactone","uuid":"1f0b…","isRecommended":true}],
  "selectionBehavior":"any",
  "overrideReasons":[{"code":"benefit-outweighs-risk","system":"https://api.augsidius.care/cds/override-reason","display":"Benefit outweighs the risk for this patient"}, …],
  "links":[{"label":"PubMed 16624686 (2006)","url":"https://pubmed.ncbi.nlm.nih.gov/16624686/","type":"absolute"}],
  "extension":{"com.augsidius":{"kind":"contraindication","certainty":"moderate","concepts":[…],"evidence":[…]}}
}}

Care models

Create sessionPreview

POST/v1/care-models/sessions

Starts a care-model session (the same sessions aug-care-model uses via augsidius.session_id). Sessions belong to the key's project and expire after 6 hours without activity.

Returns

A care_model.session object.

Example request

curl -X POST https://api.augsidius.care/v1/care-models/sessions \
  -H "Authorization: Bearer $AUGSIDIUS_API_KEY"

Response

{
  "id": "3f9a1c…",
  "object": "care_model.session"
}

Add observationsPreview

POST/v1/care-models/sessions/{session_id}/observations

Adds observations — present or ruled out — and re-evaluates the whole session. Missing observations are ranked first by their power to rule out emergencies and severe outcomes; actions are ranked by how much clarity they bring.

Request body

observationsarrayRequired
Up to 200 items.
Show properties
- textstring
  Free text for one finding, e.g. photophobia.
- concept_idstring
  A c_… concept id returned to your organisation. Matches exactly.
- presentboolean
  true (default) or false for ruled out.
provider_scopearray
Keep only actions of these kinds: ask, examine, measure, test.

Returns

A care_model.state object.

Example request

curl https://api.augsidius.care/v1/care-models/sessions/$SID/observations \
  -H "Authorization: Bearer $AUGSIDIUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"observations": [{"text": "photophobia"}, {"text": "rash", "present": false}]}'

Response

{
  "id": "3f9a1c…",
  "object": "care_model.state",
  "observations": {"present": ["Fever", "Neck stiffness", "Photophobia"], "absent": ["Rash"]},
  "hypotheses": [
    {"condition": "c_8kq1…", "name": "Bacterial meningitis", "p": 0.34, "severity": 0.9, "severe_because": "Death"}
  ],
  "emergencies_open": ["Bacterial meningitis"],
  "missing": [
    {"observation": "c_x2k9…", "name": "Altered mental status", "type": "examination_finding", "score": 1.81, "for": ["Bacterial meningitis"]}
  ],
  "next_best_actions": [
    {"kind": "examine", "target": "c_x2k9…", "label": "Examine for Altered mental status", "gain": 1.81, "resolves": ["Altered mental status"]}
  ],
  "memory": [{"after": 3, "nba": ["Examine for Altered mental status"]}],
  "unresolved": [],
  "graph_version": "20261108-765151"
}

Models

List models

GET/v1/models

Lists the models your key can use, with their status (preview, live or coming_soon), family and required scope.

Returns

A list of model objects.

Example request

curl https://api.augsidius.care/v1/models \
  -H "Authorization: Bearer $AUGSIDIUS_API_KEY"

Response

{
  "object": "list",
  "data": [{
    "id": "aug-care-model",
    "object": "model",
    "owned_by": "augsidius",
    "augsidius": {
      "status": "preview",
      "family": "Decision support",
      "scope": "agents:care_model",
      "description": "Adaptive care model: …"
    }
  }]
}

Feedback

Send feedback

POST/v1/feedback

Records what a clinician did with a suggestion. Requires feedback:write. Never include patient identifiers.

Request body

request_idstringRequired
From the x-request-id response header.
outcomestringRequired
accepted, overridden or ignored.
card_idstring
The card uuid (or the item) the feedback is about.
override_reasonstring
A code from the card's overrideReasons, or short free text.

Example request

curl https://api.augsidius.care/v1/feedback \
  -H "Authorization: Bearer $AUGSIDIUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"request_id": "req_18c…", "card_id": "c1", "outcome": "overridden", "override_reason": "benefit-outweighs"}'

Response

{ "ok": true }

Usage

Get usage

GET/v1/usage

Daily requests and units for the key's project. Requires usage:read.

Request body

fromdate
Start date, YYYY-MM-DD. Defaults to the first of this month.
todate
End date. Defaults to now.

Example request

curl "https://api.augsidius.care/v1/usage?from=2026-11-01" \
  -H "Authorization: Bearer $AUGSIDIUS_API_KEY"

Response

{
  "object": "list",
  "data": [
    {"day": "2026-11-08", "model": "aug-care-model", "env": "live", "requests": 1240, "units": 1240}
  ]
}

Schemas

Retrieve schema

GET/v1/schemas/{name}

Returns the JSON Schema for a typed payload, e.g. care_model. Use it to generate types or validate responses.

Example request

curl https://api.augsidius.care/v1/schemas/care_model

Response

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "care_model/0.1",
  "type": "object",
  "properties": { … }
}