> ## Documentation Index
> Fetch the complete documentation index at: https://docs.medlistiq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Output formats

> Pick the response shape that fits how you'll consume the data: inferred_list, fhir_bundle, or fhir_array.

Every inference request picks both a **verbosity** (how much detail per
medication) and a **format** (the overall shape of the response). These are
orthogonal — pick whichever combination fits your use case.

## Format at a glance

| `format`                  | What you get                                                               | Best for                                                      |
| ------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------- |
| `inferred_list` (default) | Our proprietary JSON: `{ medications, provenance?, meta }`                 | Portal / dashboard UIs, CDS engines, human-readable debugging |
| `fhir_bundle`             | FHIR R4 `Bundle` of `MedicationRequest` (+ `Provenance` at full verbosity) | EHR ingest (Epic, Cerner, Athena), FHIR-native stores         |
| `fhir_array`              | Flat array of FHIR resources                                               | Pipelines, data warehouses, streaming transforms              |

## Which to pick

<CardGroup cols={2}>
  <Card title="Dashboard / portal UI" icon="table">
    Use `inferred_list`. Our shape is pre-shaped for rendering status badges,
    confidence scores, and dosage sigs. FHIR is too verbose for UI.
  </Card>

  <Card title="EHR integration" icon="hospital">
    Use `fhir_bundle`. Standard R4 Bundle you can route straight into your
    FHIR store with no translation layer. Get `Provenance` resources for
    free at `verbosity=full`.
  </Card>

  <Card title="CDS engine / rule engine" icon="code-branch">
    Use `inferred_list` with `verbosity=full`. You get the richest provenance
    trail (evidence tags, enrichments) in the most ergonomic shape.
  </Card>

  <Card title="Pipeline / warehouse" icon="database">
    Use `fhir_array`. Flat list of FHIR resources ingests cleanly into
    BigQuery / DuckDB / Snowflake. Each row is `resourceType` + payload.
  </Card>
</CardGroup>

## Example: the same request in all three formats

**Request** (body is the same; only `format` changes):

```json theme={null}
{
  "format": "<format>",
  "verbosity": "standard",
  "resources": [
    {
      "resourceType": "MedicationRequest",
      "id": "mr-1",
      "status": "active",
      "intent": "order",
      "authoredOn": "2026-03-05",
      "medicationCodeableConcept": {
        "coding": [{ "system": "http://www.nlm.nih.gov/research/umls/rxnorm", "code": "617312" }]
      }
    }
  ]
}
```

### `format: "inferred_list"` — our shape

```json theme={null}
{
  "medications": [
    {
      "id": "med_abc123",
      "display_name": "Atorvastatin 40 MG Oral Tablet",
      "rxnorm_code": "617312",
      "status": "active",
      "confidence": 0.95,
      "sig": "Take 1 tablet by mouth daily",
      "dosage": { "...": "..." },
      "indication": { "...": "..." },
      "last_activity_date": "2026-03-05T00:00:00Z"
    }
  ],
  "meta": {
    "request_id": "...",
    "ruleset_version": "2026-04-15.v5",
    "as_of": "...",
    "processing_time_ms": 187,
    "input_resource_count": 1,
    "output_medication_count": 1
  }
}
```

### `format: "fhir_bundle"` — FHIR R4 Bundle

```json theme={null}
{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 1,
  "entry": [
    {
      "fullUrl": "urn:uuid:med_abc123",
      "resource": {
        "resourceType": "MedicationRequest",
        "id": "med_abc123",
        "status": "active",
        "intent": "order",
        "medicationCodeableConcept": {
          "text": "Atorvastatin 40 MG Oral Tablet",
          "coding": [{ "system": "http://www.nlm.nih.gov/research/umls/rxnorm", "code": "617312", "display": "Atorvastatin 40 MG Oral Tablet" }]
        },
        "authoredOn": "2026-03-05T00:00:00Z",
        "dosageInstruction": [{ "text": "Take 1 tablet by mouth daily", "...": "..." }],
        "extension": [
          { "url": "https://medlistiq.com/fhir/extensions/inference-confidence", "valueDecimal": 0.95 }
        ]
      }
    }
  ]
}
```

### `format: "fhir_array"` — flat list

```json theme={null}
[
  {
    "resourceType": "MedicationRequest",
    "id": "med_abc123",
    "...": "..."
  }
]
```

At `verbosity: "full"`, `fhir_array` becomes a union: `MedicationRequest`
resources followed by `Provenance` resources. Filter by `resourceType` to
separate them.

## Where does the `meta` block go?

`inferred_list` keeps `meta` (request\_id, ruleset\_version, timing, counts)
inside the response body for backwards compatibility.

For FHIR formats, the response body is a pure FHIR payload — no wrapping
allowed. We move the same information to **response headers**:

| Header                      | What                                             |
| --------------------------- | ------------------------------------------------ |
| `x-request-id`              | Request ID, for trace correlation                |
| `x-ruleset-version`         | The ruleset version that ran (`YYYY-MM-DD.vN`)   |
| `x-as-of`                   | Timestamp used as "now" for time-sensitive rules |
| `x-processing-time-ms`      | How long the inference took                      |
| `x-input-resource-count`    | How many resources were in your request          |
| `x-output-medication-count` | How many medications came out                    |

These headers are set on **every** response (including `inferred_list`), so
you can use them uniformly regardless of format.

## Combinations worth knowing

The two axes are fully orthogonal — every (`verbosity`, `format`) pair works:

|                 | `minimal`                                | `standard`                               | `full`                                       |
| --------------- | ---------------------------------------- | ---------------------------------------- | -------------------------------------------- |
| `inferred_list` | body `meta`; compact meds                | body `meta`; codes + dosage              | body `meta` + `provenance` dict              |
| `fhir_bundle`   | meta in headers; thin MedicationRequests | meta in headers; full MedicationRequests | meta in headers; adds `Provenance` resources |
| `fhir_array`    | thin MedicationRequests, flat            | full MedicationRequests, flat            | flat mixed MedicationRequest + Provenance    |

## FHIR extensions we emit

Confidence and inference evidence are not standard FHIR fields, so we attach
them as custom extensions (safe for FHIR-conformant parsers — they can ignore
unknown extensions without error):

| Extension URL                                                | Where                                    | What                                         |
| ------------------------------------------------------------ | ---------------------------------------- | -------------------------------------------- |
| `https://medlistiq.com/fhir/extensions/inference-confidence` | On `MedicationRequest` (standard / full) | `valueDecimal` 0–1                           |
| `https://medlistiq.com/fhir/extensions/inference-evidence`   | On `Provenance` (full only)              | `valueString` evidence tag                   |
| `https://medlistiq.com/fhir/extensions/inference-enrichment` | On `Provenance` (full only)              | Nested extension: `field`, `reason`, `value` |

These live under our root namespace so future IG publication can reference
them as-is.