Using the API

Streaming & formats

Every model can return its result in three ways. Pick the one that suits your client; the content is the same.

Mode	How to ask	Content type	Best for
Single response	`"stream": false` (default)	`application/json`	Batch jobs, simple integrations
Server-sent events	`"stream": true`	`text/event-stream`	OpenAI SDKs, chat UIs, anything that already reads OpenAI streams
NDJSON	`"stream": true` and header `Accept: application/x-ndjson`	`application/x-ndjson`	EMRs and back-end services that want one JSON object per line without SSE framing

What streams

Model	Unit of streaming
`aug-evidence-qa`	Text fragments of the answer as they are written; citations arrive at the end.
`aug-extract`	One entity per line.
`aug-care-model`	One line per item: session, then observations, then conditions, missing observations and actions.
`aug-cds`	One card per line, most important first.

For the three JSONL models, each line is complete — you can parse and display it as soon as it arrives. Lines never split across chunks.

Server-sent events

Standard OpenAI chat.completion.chunk events. For JSONL models each chunk's delta.content is exactly one JSON line ending in \n.

Text

data: {"id":"chatcmpl_1d…","object":"chat.completion.chunk","model":"aug-cds","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}

data: {"id":"chatcmpl_1d…","object":"chat.completion.chunk","model":"aug-cds","choices":[{"index":0,"delta":{"content":"{\"object\":\"cds.card\",\"card\":{\"summary\":\"Rule out bacterial meningitis\",\"indicator\":\"critical\",…}}\n"},"finish_reason":null}]}

data: {"id":"chatcmpl_1d…","object":"chat.completion.chunk","model":"aug-cds","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"augsidius":{"object":"cds.summary","cards":6,"billable_calls":1,…}}

data: {"id":"chatcmpl_1d…","object":"chat.completion.chunk","model":"aug-cds","choices":[],"usage":{"prompt_tokens":64,"completion_tokens":9269,"total_tokens":9333,"augsidius_units":20}}

data: [DONE]

The first chunk opens the assistant message.
Content chunks follow.
The chunk with finish_reason: "stop" carries the call's summary in augsidius (and, for Q&A, annotations).
If you set stream_options.include_usage, a final chunk with empty choices carries usage.
data: [DONE] ends the stream.

Python

import json
from openai import OpenAI

client = OpenAI(base_url="https://api.augsidius.care/v1", api_key="aug_live_…")
stream = client.chat.completions.create(
    model="aug-care-model", stream=True,
    messages=[{"role": "user", "content": "34F, 6 weeks low mood, anhedonia, early waking, 3 kg weight loss."}],
)
for chunk in stream:
    if not chunk.choices:
        continue
    text = chunk.choices[0].delta.content
    if text and text.strip():
        item = json.loads(text)
        print(item["object"], item.get("concept", {}).get("name") if item.get("concept") else "")

NDJSON

The body is plain lines of JSON. The last line is the summary, with usage included.

cURL

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-cds", "stream": true, "messages": [{"role": "user", "content": "…case summary…"}]}'

Text

{"object":"cds.card","card":{"uuid":"b92b…","summary":"Rule out bacterial meningitis","indicator":"critical",…}}
{"object":"cds.card","card":{"uuid":"4c1e…","summary":"Metformin contraindicated: Severe renal impairment","indicator":"critical",…}}
{"object":"cds.summary","cards":2,"indicators":{"critical":2,"warning":0,"info":0},"usage":{…,"augsidius_units":20}}

For aug-evidence-qa over NDJSON, answer fragments arrive as {"object": "text.delta", "content": "…"} lines and the last line carries citations.

Errors during a stream

Problems found before the response starts (bad key, scope, limits, input too long) return a normal HTTP error. If something fails after streaming has begun, the stream ends with an error event instead of the summary, and the call is not billed:

Text

data: {"error":{"type":"api_error","code":"upstream_unavailable","message":"A clinical service is temporarily unavailable; retry shortly."}}

data: [DONE]

Over NDJSON the same error is a line: {"object": "error", "code": "upstream_unavailable", "message": "…"}.

Timing

Typical calls (a case summary of a few hundred words) complete in 7–15 seconds; the first lines usually arrive within a few seconds. Inputs near the size limit can take up to two minutes. Set client read timeouts to at least 180 seconds, and if you proxy the stream, turn off response buffering.

Chat completions

Response types