Media Resource

Media represents audio, video, and images in clinical workflows. It is used to capture patient photos, wound images, radiological images, and more.

API convention: the patient and encounter references are sent as flat ids (subjectId, encounterId). The operator reference (who captured the media) uses the standard FHIR reference shape. All ids are UUIDs. The binary bytes live in /files/upload and are referenced by URL.

Create Media

curl -X POST https://api.esus.health/fhir/Media \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/fhir+json" \
  -d '{
    "status": "completed",
    "type": {
      "coding": [{
        "system": "http://terminology.hl7.org/CodeSystem/media-type",
        "code": "image",
        "display": "Image"
      }]
    },
    "modality": {
      "coding": [{
        "system": "http://dicom.nema.org/resources/ontology/DCM",
        "code": "GR",
        "display": "General Radiography"
      }]
    },
    "subjectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "encounterId": "c1a2e3d4-5b6f-7890-abcd-ef1234567890",
    "operator": {
      "reference": "Practitioner/a7b1c2d3-e4f5-6789-abcd-ef0123456789"
    },
    "view": {
      "coding": [{
        "system": "http://terminology.hl7.org/CodeSystem/media-view",
        "code": "front",
        "display": "Front view"
      }]
    },
    "bodySite": {
      "coding": [{
        "system": "http://snomed.info/sct",
        "code": "89545006",
        "display": "Right arm"
      }]
    },
    "content": {
      "contentType": "image/jpeg",
      "url": "https://api.esus.health/files/{orgId}/{fileId}",
      "creation": "2026-04-21T10:30:00Z"
    }
  }'

Media Status

StatusMeaning
preparationCapture planned / being prepared
in-progressCapture in progress
not-doneCapture was not performed
on-holdCapture paused
stoppedCapture stopped
completedCapture completed
entered-in-errorRecording error
unknownStatus unknown

Common Use Cases

Wound Photography

curl -X POST https://api.esus.health/fhir/Media \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/fhir+json" \
  -d '{
    "status": "completed",
    "type": { "coding": [{ "code": "image" }] },
    "subjectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "bodySite": {
      "coding": [{
        "system": "http://snomed.info/sct",
        "code": "72037002",
        "display": "Left lower leg"
      }]
    },
    "note": [{ "text": "Wound assessment — day 3 post-surgery" }],
    "content": {
      "contentType": "image/jpeg",
      "url": "https://api.esus.health/files/{orgId}/{fileId}"
    }
  }'

Ultrasound

curl -X POST https://api.esus.health/fhir/Media \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/fhir+json" \
  -d '{
    "status": "completed",
    "type": { "coding": [{ "code": "video" }] },
    "modality": {
      "coding": [{
        "system": "http://dicom.nema.org/resources/ontology/DCM",
        "code": "US",
        "display": "Ultrasound"
      }]
    },
    "subjectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "encounterId": "c1a2e3d4-5b6f-7890-abcd-ef1234567890",
    "content": {
      "contentType": "video/mp4",
      "url": "https://api.esus.health/files/{orgId}/{fileId}"
    }
  }'

Search Media

# All media for a patient
curl "https://api.esus.health/fhir/Media?patient=3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Images only
curl "https://api.esus.health/fhir/Media?patient=3fa85f64-5717-4562-b3fc-2c963f66afa6&type=image" \
  -H "Authorization: Bearer YOUR_TOKEN"