Writing documents & media

Ava's write surface is deliberately narrow: apps contribute documents (DocumentReference) and captures (Media) to the chart, create-only. There is no update, patch, or delete anywhere in the API, and no way to read back what you wrote — the clinic's record is the EMR's to manage.

Both are clinician-context (user/) scopes: writes happen as the signed-in user, onto the chart of a patient that user can access.

Creating a document

curl -X POST "{fhir_base_url}/DocumentReference" \
  -H "Authorization: Bearer $SMART_ACCESS_TOKEN" \
  -H "Content-Type: application/fhir+json" \
  -H "Accept: application/fhir+json" \
  -d '{
    "resourceType": "DocumentReference",
    "status": "current",
    "type": { "coding": [{ "system": "http://loinc.org", "code": "34133-9" }] },
    "subject": { "reference": "Patient/{id}" },
    "content": [{
      "attachment": {
        "contentType": "application/pdf",
        "data": "<base64-encoded bytes>",
        "title": "Visit summary"
      }
    }]
  }'

A successful create returns 201 Created with the stored resource in the body and its address in the Location header. Persist the returned id in your own system if you need to refer to the write later — you cannot search for it afterwards.

Guidelines:

• Send content inline as base64 attachment.data with an accurate contentType; give every attachment a human-meaningful title — that's what clinicians see.
• Use a specific LOINC document type code; it drives where the document files in the chart.
• subject must reference the patient the document belongs to. In a patient launch, that should be the launched patient.

Creating media

Same pattern against /Media, with a single content attachment and a type of image, video, or audio — see the Media reference for a complete example.

Failure modes

• 403 — your granted scopes lack user/DocumentReference.c / user/Media.c, or the user cannot write to that patient's chart.
• 422 with an OperationOutcome — the resource failed validation (missing required elements, unknown codes, malformed base64). The outcome's issue[] pinpoints the element.
• Duplicate submissions create duplicate documents — POST is not idempotent. Guard your own retry logic.