Upload one batch item

POST/lang2fhir/batch/{job_id}/items

Stores one multipart item. Set either document with a raw file, or JSON-only create.

Set exactly one JSON object. document requires file; create forbids it. Violations return 400.

Upload validates only the envelope. Endpoint request validation happens during processing: decoding failures are invalid_input; other pipeline failures are processing_failed.

Use request_id for every upload so retries replace the same item. deduplicated is true only for an unchanged payload; a changed payload overwrites the item and returns false.

Uploads return 409 after finalization or at the item limit, and 413 when the item is too large.

RequiresBearerauthentication

Path parameters

job_idstringrequired

Body parameters

documentobjectoptional

The JSON body of POST /lang2fhir/document/multi, without its base64 content field — the uploaded file supplies the content. Accepts that endpoint's fields (version, provider, primary_patient, patient_reference (deprecated), implementation_guide, detection_effort (deprecated), validation_method, config). This is the multi-resource body: it has no single-resource field, and the item's result is a DocumentMultiResponse (a Bundle of resources). Mutually exclusive with create; requires file. Do not combine primary_patient with patient_reference.

createobjectoptional

The JSON body of POST /lang2fhir/create/multi. Accepts that endpoint's fields (text, version, provider, primary_patient, patient_reference (deprecated), implementation_guide, detection_effort (deprecated), validation_method, resource_review). This is the multi-resource body: it has no single-resource field, and the item's result is a CreateMultiResponse (a Bundle of resources). Mutually exclusive with document; must not be accompanied by a file. Do not combine primary_patient with patient_reference.

filestring (binary)optional

The document's file content (PDF, PNG, JPEG, TIFF, RTF, or XML/C-CDA). The document pipeline accepts files up to 20 MiB; an upload that passes the storage cap but exceeds this limit fails during processing. RTF and XML/C-CDA documents whose extracted text exceeds 1 MiB also fail during processing. Generic XML must include an XML declaration; C-CDA documents rooted at ClinicalDocument may omit it. Required with document; forbidden with create.

request_idstringoptional

Optional idempotency token (at most 256 UTF-8 bytes). Re-uploading under the same token overwrites the same item instead of adding a new one. The token is scoped to this job; the same token in another job is independent and creates a separate item.

idstringoptional

Optional caller-supplied correlation label (at most 512 UTF-8 bytes), echoed back on status and result listings so you can match the server's item_id to your own record.

Returns

Item accepted

Response fields

job_idstringoptional

request_idstringoptional

statusstringoptional

finalizedbooleanoptional

total_itemsintegeroptional

errorobjectoptional

kindstringoptional

messagestringoptional

created_atstringoptional

updated_atstringoptional

completed_atstringoptional

expires_atstringoptional

item_idstringoptional

idstringoptional

deduplicatedbooleanoptional

POSTRequest

# Get authentication token
PHENOML_TOKEN=$(curl -X POST "https://experiment.app.pheno.ml/v2/auth/token" \
  -u "$PHENOML_CLIENT_ID:$PHENOML_CLIENT_SECRET" \
  | jq -r '.access_token')

curl -X POST "https://experiment.app.pheno.ml/lang2fhir/batch/{job_id}/items" \
  -H "Authorization: Bearer $PHENOML_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "document": {},
  "create": {},
  "file": "example",
  "request_id": "<access_token>",
  "id": "abc-123-def-456"
}'

202 AcceptedExample Response

{
  "job_id": "l2f_batch_6f1d2c3a-8b4e-4f5a-9c7d-0e1f2a3b4c5d",
  "request_id": "submit-2025-09-02-batch-001",
  "status": "pending",
  "finalized": false,
  "total_items": 12,
  "error": {
    "kind": "processing_failed",
    "message": "the item could not be converted"
  },
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "completed_at": "2024-01-15T09:30:00Z",
  "expires_at": "2024-01-15T09:30:00Z",
  "item_id": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "id": "chart-note-0042",
  "deduplicated": false
}