Uploading Files

Add documents with POST /v1/data-engine/batches/{batchId}/documents. Send plain text inline. Upload PDFs, Word files, and anything over 1 MiB separately.

Each request takes up to 100 documents and 10 MiB. It is atomic: if it returns 409 or 422, no document in it was added.

Document Fields

Field	Required	Description
externalReference	Yes	Your ID for the document. Unique within the batch, up to 500 characters
mediaType	Yes	A supported type. Parameters such as ; charset=utf-8 are ignored
content	Inline text only	text/plain or text/markdown, up to 1 MiB
byteSize	Recommended for files	Size in bytes
checksumSha256	Recommended for files	SHA-256 as Base64 or 64 hex characters
filename	No	Original file name, up to 512 characters
patient	No	{ "externalId": "P-100" }
encounter	No	{ "externalId": "V-22", "date": "2026-10-01" }
metadata	No	Up to 20 string pairs, 500 characters each. Returned as sent

{
  "documents": [
    {
      "externalReference": "note-8841",
      "mediaType": "text/plain",
      "content": "Clinical note text",
      "patient": { "externalId": "P-100" },
      "encounter": { "externalId": "V-22", "date": "2026-10-01" },
      "metadata": { "ward": "4B" }
    }
  ]
}

A document with content starts as pending. Without content, it starts as awaiting_upload.

Upload a File

Declare the document without content, including byteSize and checksumSha256. Then upload the bytes:

curl -s -X PUT \
  "https://api.amorphous.health/v1/data-engine/batches/$BATCH_ID/documents/$DOCUMENT_ID/content" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/pdf" \
  --data-binary @scan-12.pdf

Check	On Failure
Body is at most 25 MiB	413
Content-Type matches mediaType	415
Bytes match checksumSha256	409 with checksum_mismatch
Size matches byteSize	422 with pointer /byteSize

Uploading the same bytes again returns 200. Different bytes return 409: content cannot change once stored.

Media Types

Other types return 415.

mediaType	Inline
text/plain	Yes
text/markdown	Yes
application/pdf	No
application/msword	No
application/vnd.openxmlformats-officedocument.wordprocessingml.document	No
application/rtf	No
application/vnd.oasis.opendocument.text	No

Patient and Encounter

Patient and encounter details are sent alongside the file, not inside it. They are optional and independent of each other.

Field	Effect
patient.externalId	Links the document to that patient. Without it, the document is still processed
encounter.externalId, encounter.date	Recorded on the document