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. Uploads are rate-limited to 10 per user per minute; exceeding it returns 429 with a Retry-After header.

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

Response:

{
  "id": "b8f0c2d1-9e3a-4f5b-8c7d-1a2b3c4d5e6f",
  "key": "org-uuid/file-uuid",
  "contentType": "application/pdf",
  "size": 384213,
  "url": "https://api.esus.health/files/b8f0c2d1-9e3a-4f5b-8c7d-1a2b3c4d5e6f"
}

The id field is the file’s canonical UUID (file_metadata.id) and the handle used to download or delete it. url already points at GET /files/{id} — use it directly in content.attachment.url, Media.content.url, or presentedForm[].url.

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

GET /files/:fileId takes the UUID id returned by the upload (a single segment — there is no /:orgId/:fileId route).

curl "https://api.esus.health/files/{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.

A fileId that does not exist or belongs to another organization returns 404.

Delete a File

DELETE /files/:fileId soft-deletes the file (it becomes unreadable while the audit trail is preserved).

curl -X DELETE "https://api.esus.health/files/{fileId}" \
  -H "Authorization: Bearer YOUR_TOKEN"

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/{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/{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.