Create a batch job

POST/lang2fhir/batch

Opens an empty job; upload items, then finalize it to start processing.

request_id makes creation idempotent: a retry returns the original job. A token is released when its job is canceled or fails before finalization; otherwise it continues to resolve to that job.

RequiresBearerauthentication

Body parameters

request_idstringoptional

Optional client idempotency token (at most 256 UTF-8 bytes). A retried create with the same token returns the original job instead of opening a second one.

Returns

Batch job created (or an idempotent replay of an existing job)

Response fields

job_idstringrequired

Server-assigned job identifier.

request_idstringoptional

The idempotency token supplied at create, if any.

statusstringrequired

Job status. completed means every item has finished — some may have failed, so check counts for the split. failed is a whole-job failure (the job could not run at all), distinct from individual item failures, which never fail the job. canceled is a caller-requested cancellation via POST /lang2fhir/batch/{job_id}/cancel; like the other terminal states it keeps any results already produced readable for the retention window.

pendingprocessingcompletedfailedcanceled

finalizedbooleanrequired

Whether the job's item set has been sealed.

total_itemsintegerrequired

The sealed item count. It is 0 until the job is finalized, so an upload response always reports 0; poll the job after finalize for the real count.

errorobjectoptional

A whole-job failure. Present only on a failed job.

created_atstring (date-time)required

updated_atstring (date-time)required

completed_atstring (date-time)optional

When the job finished. Absent until then.

expires_atstring (date-time)required

When the job and its stored inputs and results are deleted. Set 7 days out, with the clock restarting when the job reaches completed, failed, or canceled. At expiry the job's request_id is freed for reuse.

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" \
  -H "Authorization: Bearer $PHENOML_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "request_id": "submit-2025-09-02-batch-001"
}'

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"
}