Using the API

Response types

This page is the reference for every object the served models return. JSONL models (aug-extract, aug-care-model, aug-cds) return one object per line; each line has an object field that tells you its type. aug-evidence-qa returns text plus a citations array.

Rule for integrators: switch on object, ignore types and fields you do not recognise. Within a version, changes are additive only.

At a glance

`object`	Returned by	One line per	Page
`extraction.entity`	`aug-extract`	entity found in the text	Extraction
`extraction.summary`	`aug-extract`	call (last)	Extraction
`care_model.session`	`aug-care-model`	call (first)	Care models
`care_model.observation`	`aug-care-model`	observation taken from the case	Care models
`care_model.condition`	`aug-care-model`	condition under consideration, ranked	Care models
`care_model.missing_observation`	`aug-care-model`	observation worth collecting next, ranked	Care models
`care_model.action`	`aug-care-model`	next best action, ranked	Care models
`care_model.summary`	`aug-care-model`	call (last)	Care models
`cds.card`	`aug-cds`	decision-support card	Decision cards
`cds.summary`	`aug-cds`	call (last)	Decision cards
`text.delta`	`aug-evidence-qa` over NDJSON	answer fragment	Streaming
`error`	any, NDJSON only	failure after streaming began	Streaming

The summary object is the last line in NDJSON. With SSE and single responses it arrives in augsidius on the final chunk / message rather than in content.

Shared building blocks

Concept

A clinical concept from the Augsidius evidence base.

JSON

{"id": "c_3o53nio3rzmizyb3f2ra", "name": "Nuchal rigidity", "kind": "examination_finding"}

Field	Description
`id`	Opaque concept id, stable for your organisation. Send it back as `concept_id` in observations for an exact match. Ids issued to one organisation do not work for another.
`name`	Preferred clinical name. May differ from the words in your text ("neck stiffness" → "Nuchal rigidity").
`kind`	`condition`, `condition_group`, `complaint`, `examination_finding`, `clinical_measurement_finding`, `historical_finding`, `investigation`, `procedure`, `drug`, `drug_group` and others.

concept is null when the text could not be matched; the item is still returned so you can show it.

Coding

Standard codes for a concept, as a list of FHIR-style codings:

JSON

[{"system": "http://snomed.info/sct", "code": "422400008", "status": "provisional"},
 {"system": "http://id.who.int/icd/release/11/mms", "code": "MD80", "status": "provisional"}]

Field	Description
`system`	`http://snomed.info/sct` (SNOMED CT) or `http://id.who.int/icd/release/11/mms` (ICD-11 MMS).
`code`	The code.
`status`	`provisional` — mapped but not yet verified against the official release; review before use in billing or registries. `verified` — checked against the official release.

An empty list means no code is mapped yet; use the concept id.

Evidence

Every clinical statement is backed by evidence objects.

JSON

{
  "claim": "Metformin is contraindicated in Severe renal impairment (eGFR < 30 mL/min/1.73 m²)",
  "certainty": "moderate",
  "detail": "rationale: …",
  "sources": [
    {"type": "pubmed", "pmid": "32138474", "title": "…", "year": 2020,
     "url": "https://pubmed.ncbi.nlm.nih.gov/32138474/", "quote": "…a sentence from the abstract…"}
  ]
}

Field	Description
`claim`	The statement in plain words.
`certainty`	Certainty of the evidence behind the statement (below).
`detail`	Key qualifiers (probability, severity, management, regimen…) when known; otherwise `null`.
`sources`	Up to three sources.

Source types

`type`	Fields	Meaning
`pubmed`	`pmid`, `title`, `year`, `url`, `quote`	A published study. `quote` is the most relevant sentence of the abstract, verbatim.
`label`	`url`	Official product information (drug label).
`web`	`url`	Another authoritative web source.
`reference_class`	`label`	A class of reference (for example `guideline`) without a specific citation.

Certainty

GRADE-aligned certainty of the evidence for a statement:

Value	Meaning
`high`	Further research is very unlikely to change confidence in the statement.
`moderate`	Further research is likely to have an important impact on confidence.
`low`	Further research is very likely to change the estimate.
`very_low`	Any estimate is very uncertain.
`ungraded`	Not yet graded. Treat as unverified.

Certainty describes the evidence, not whether the statement applies to your patient.

Weight

Ranked items carry rank (1 = first) and weight (0–1). weight is relative within one response: the first item of a list is 1.0 and the rest are scaled to it. It is a ranking aid, not a probability.

Q&A answer and citations

aug-evidence-qa returns the answer as text; each clinical sentence ends with markers like [2] or [1][4]. The citations are in message.augsidius.citations (single response) or augsidius.citations on the final chunk (stream):

JSON

{"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", "…": "…"}]}

A citation is an evidence object plus index, the number used in the markers. Only cited statements are listed, so indexes can have gaps. OpenAI-style annotations (url_citation with start_index/end_index of each marker) are provided as well.

Abstaining

When the evidence does not cover a question, aug-evidence-qa says so in the answer and returns no citations. When a term cannot be matched, its concept is null (extraction, care model) or it is listed in unlinked (care model summary). Neither is an error, and neither should be shown as a negative finding.

Streaming & formats

Errors