How ESUS Stores Document Bytes

ESUS does not expose the FHIR Binary resource as a separate endpoint. Instead, the platform provides a dedicated file-storage service that performs the checks that matter for clinical data: magic-byte content-type validation, antivirus scanning (when configured), and per-tenant isolation.

Once uploaded, a file is addressed by its URL and referenced from the resources that describe it (DocumentReference.content.attachment.url, Media.content.url, DiagnosticReport.presentedForm[].url).

Upload a File

POST /files/upload accepts a multipart/form-data body with a single file part. Maximum size is 50 MB.

curl -X POST https://api.esus.health/files/upload \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@/path/to/document.pdf"

Response:

{
  "key": "org-uuid/file-uuid",
  "size": 384213,
  "contentType": "application/pdf"
}

The server performs the following checks before storing:

1. Magic-byte + extension + MIME consistency — the declared content-type is verified against the actual file bytes. A 415 is returned on mismatch.
2. Antivirus scan — when ClamAV is configured, the file is scanned; infected files are rejected with 422.
3. Tenant binding — the file is stored under the caller’s organization; cross-tenant access is not possible.

Download a File

curl "https://api.esus.health/files/{orgId}/{fileId}" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  --output downloaded.pdf

By default the response uses Content-Disposition: attachment to prevent HTML/SVG/PDF being rendered in-origin (XSS via uploaded content). Image-preview flows can opt in via ?disposition=inline. The returned Content-Type is always the server-detected MIME, not the client-declared one.

Cross-organization reads are refused with 403.

Reference the File from a FHIR Resource

After upload, link the file from the relevant FHIR resource. For a clinical note:

{
  "resourceType": "DocumentReference",
  "status": "current",
  "subjectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "content": [{
    "attachment": {
      "contentType": "application/pdf",
      "url": "https://api.esus.health/files/{orgId}/{fileId}",
      "title": "Progress note"
    }
  }]
}

For an image:

{
  "resourceType": "Media",
  "status": "completed",
  "subjectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "content": {
    "contentType": "image/jpeg",
    "url": "https://api.esus.health/files/{orgId}/{fileId}"
  }
}

Limits and Guidance

• Max upload size: 50 MB per request. For larger files, split and upload each part as a separate DocumentReference.content attachment, or contact us about enterprise options.
• Allowed MIME types: the validator enforces a whitelist of clinical content types. Request additions through support if you have a legitimate use case.
• Confidentiality: file bytes are stored encrypted at rest and served only over TLS.