Using the API

Chat completions

POST /v1/chat/completions is the single entry point for every model. It follows the OpenAI Chat Completions format, so any OpenAI-compatible SDK works by changing the base URL and key. Augsidius-specific options go in one extra object, augsidius.

Models served today

Model	What you send	What you get back	`message.content`	Sessions
`aug-evidence-qa`	A clinical question	A cited answer	Text with `[n]` citation markers	No
`aug-extract`	Clinical text	Coded clinical entities	JSONL, one entity per line	No
`aug-care-model`	A case summary and/or observations	Observations, conditions, missing observations, next best actions	JSONL, one item per line	Yes
`aug-cds`	A case summary	Decision-support cards	JSONL, one card per line	No

Other models in the catalog return 501 not_available until they launch.

Request

JSON

{
  "model": "aug-care-model",
  "messages": [
    {"role": "user", "content": "58M, T2DM on metformin. 2 days fever 39.2, severe headache, neck stiffness, no rash. eGFR 25."}
  ],
  "stream": true,
  "stream_options": {"include_usage": true},
  "augsidius": {
    "session_id": "cc47ad4e8fb44713a00d9bf5b6b341ec",
    "observations": [{"text": "photophobia", "present": true}, {"concept_id": "c_3o53nio3rzmizyb3f2ra", "present": false}],
    "provider_scope": ["ask", "examine", "test"]
  }
}

Field	Required	Description
`model`	yes	One of the model ids above.
`messages`	yes	Standard chat messages. String content and `[{"type": "text", "text": …}]` content parts are both accepted. See How each model reads messages below.
`stream`	no	`true` streams the response. See Streaming & formats. Default `false`.
`stream_options.include_usage`	no	With `stream: true`, sends a final chunk carrying `usage`.
`augsidius`	no	Augsidius options (below). Also accepted as `metadata.augsidius` for SDKs that only pass `metadata`.
`temperature`, `max_tokens`, `max_completion_tokens`, `user`	no	Accepted for compatibility and ignored. Output size is fixed per model so results stay consistent.

How each model reads messages

Model	Input
`aug-evidence-qa`	The last user message is the question. Up to four earlier `user`/`assistant` turns are used only to resolve follow-ups ("and in pregnancy?").
`aug-extract`, `aug-care-model`, `aug-cds`	All `user` messages, joined, are the clinical text. `system` and `assistant` messages are ignored.

The `augsidius` object

Field	Models	Description
`session_id`	`aug-care-model`	Continue an existing care-model session. Omit it to start a new one; the new id comes back in the response.
`observations`	`aug-care-model`, `aug-cds`	Structured observations in addition to, or instead of, text: `{"text": "photophobia", "present": true}` or `{"concept_id": "c_…", "present": false}`. Concept ids must be ones returned to your organisation. Up to 50 per call.
`provider_scope`	`aug-care-model`, `aug-cds`	Kinds of action your care team can perform: `ask`, `examine`, `measure`, `test`. Next best actions outside it are left out.

Response (`stream: false`)

JSON

{
  "id": "chatcmpl_9f2c…",
  "object": "chat.completion",
  "created": 1794226698,
  "model": "aug-care-model",
  "choices": [{
    "index": 0,
    "finish_reason": "stop",
    "message": {
      "role": "assistant",
      "content": "{\"object\":\"care_model.session\",…}\n{\"object\":\"care_model.observation\",…}\n…",
      "augsidius": {"session_id": "cc47ad4e…", "object": "care_model.summary", "billable_calls": 1, "…": "…"}
    }
  }],
  "usage": {"prompt_tokens": 41, "completion_tokens": 2810, "total_tokens": 2851, "augsidius_units": 20}
}

Field	Description
`message.content`	The result. For `aug-evidence-qa`, the answer text. For the other three, JSONL: one JSON object per line, each with an `object` field naming its type. Split on `\n` and parse each line.
`message.refusal`	`aug-evidence-qa` only: set (and `content` is `null`) when the question is declined. See Evidence Q&A.
`message.annotations`	`aug-evidence-qa` only: OpenAI-style `url_citation` annotations, one per `[n]` marker.
`message.augsidius`	The summary object for the call (`care_model.summary`, `cds.summary`, `extraction.summary`, or the Q&A `citations`), plus `session_id` and `billable_calls`.
`usage.prompt_tokens`, `usage.completion_tokens`	Size of your input and of the returned content (characters ÷ 4). Informational only.
`usage.augsidius_units`	What this call costs. See Plans & billing.

Every response also carries x-request-id and x-ratelimit-* headers.

With the OpenAI SDK

from openai import OpenAI
import json

client = OpenAI(base_url="https://api.augsidius.care/v1", api_key="aug_live_…")

r = client.chat.completions.create(
    model="aug-cds",
    messages=[{"role": "user", "content": "58M on metformin and ibuprofen. Fever, headache, neck stiffness. eGFR 25."}],
)
for line in r.choices[0].message.content.splitlines():
    item = json.loads(line)
    if item["object"] == "cds.card":
        print(item["card"]["indicator"], item["card"]["summary"])

The augsidius field on the request is not in the OpenAI SDK's types: pass it with extra_body={"augsidius": {...}} (Python) or as an extra property (Node.js).

Authentication & keys

Streaming & formats