Upload DICOM

Create a study, upload DICOM files to presigned URLs, and start AI processing.

Uploading is a three-call flow: create the study, PUT the files to presigned URLs, then start processing. Files go directly to encrypted object storage and never pass through the API servers, so large studies upload fast.

1. Create a study

curl -s -X POST "https://api.vitalview.ai/v1/studies" \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{
    "scan_type": "ct_brain",
    "files": [{"filename": "study.zip", "size_mb": 84.2}],
    "patient": {"name": "DOE^JANE", "dob": "1980-01-01", "sex": "F"},
    "clinical_indication": "Fall with loss of consciousness",
    "vendor_ref": "ACC-2231"
  }'

Response (201):

{
  "study_id": "a1b2c3d4",
  "scan_type": "ct_brain",
  "vendor_ref": "ACC-2231",
  "upload": {
    "s3_prefix": "uploads/<org>/a1b2c3d4",
    "expires_in": 3600,
    "urls": [
      { "filename": "study.zip", "key": "uploads/<org>/a1b2c3d4/study.zip", "url": "https://..." }
    ]
  },
  "created_at": "2026-07-05T09:12:44Z"
}

Request fields:

Field	Required	Notes
`scan_type`	yes	`ct_brain`, `ct_chest`, `ct_abdomen`, `ct_whole_body`, and other CT body regions
`files`	yes	One entry per file you will upload; `.zip` and `.dcm` only
`patient`	no	`name`, `dob` (YYYY-MM-DD), `sex` (M/F/O); appears on the report draft
`clinical_indication`	no	Free text shown to the AI planner and on the report
`vendor_ref`	no	Your accession or order id, echoed back on every response

Send only the minimum patient demographics your workflow requires. Data is processed under your service agreement.

2. Upload the files

PUT each file to its presigned URL. No API key header, the URL itself carries authorization and expires after one hour.

curl -s -X PUT --upload-file study.zip "$UPLOAD_URL"

Accepted formats:

.zip containing a DICOM study (one or more series). Recommended.
Loose .dcm files, one presigned URL per file.

Single-file uploads support up to 5 GB. If an upload URL expires before you finish, create a new study; creation is free and instant.

3. Start processing

curl -s -X POST "https://api.vitalview.ai/v1/studies/a1b2c3d4/process" \
  -H "X-API-Key: $KEY"

Response (202):

{
  "study_id": "a1b2c3d4",
  "scan_id": "9f8e7d6c5b4a",
  "status": "queued",
  "job_id": "c0ffee...",
  "selected_series": {
    "series_uid": "1.2.840.113619.2.55...",
    "series_description": "AX BRAIN 5.0",
    "file_count": 312,
    "processable": true
  },
  "detected_series": [ ... ]
}

Series selection is automatic: we inspect the upload, list every DICOM series found, and pick the best processable one. If your PACS already knows which series to send, pass it explicitly:

curl -s -X POST ".../studies/a1b2c3d4/process" \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"series_uid": "1.2.840.113619.2.55..."}'

If no series is processable you get 422 no_processable_series with the full detected_series list and per-series reasons.

Calling process twice returns 409 already_processing with the existing scan_id; the study is never dispatched twice.

Next: Retrieve results