# Bulk Inference

Process an entire folder of DICOM images in a single API call. The engine iterates through all .dcm files found in the input folder (including sub-directories), runs AI inference on each, and saves per-patient results to the output folder.

# `POST /bulk_inference`

This endpoint requires a valid JWT token in the Authorization header. See Authentication.

# Request

Headers

Header	Value
`Content-Type`	`application/json`
`Authorization`	`<your_jwt_token>`

Body (JSON)

{
  "input_folder_path": "/path/to/your/dicom/folder/",
  "output_folder_path": "/path/to/output/folder/"
}

Field	Type	Required	Description
`input_folder_path`	`string`	Yes	Absolute path to a folder containing `.dcm` DICOM files
`output_folder_path`	`string`	Yes	Absolute path where per-patient output folders will be created

# Response

{
  "Result": "Success",
  "Data": null,
  "Message": "Bulk inference completed successfully."
}

{
  "Result": "Failure",
  "Data": null,
  "Message": "input_folder_path is required in the request"
}

{
  "Result": "Failure",
  "Data": null,
  "Message": "No Dicom images found in the provided path"
}

{
  "Result": "Failure",
  "Data": null,
  "Message": "Token missing"
}

{
  "Result": "Failure",
  "Data": null,
  "Message": "Bulk inference failed due to an internal error"
}

# Output Structure

For each DICOM image processed, a sub-folder is created inside the output folder named by the Patient ID from the DICOM metadata. Each sub-folder contains:

<output_folder_path>/
  ├── <patient_id_1>/
  │   ├── <patient_id_1>_predictions.json
  │   ├── <patient_id_1>_heatmap.png
  │   ├── <patient_id_1>_source_image.png
  │   └── <patient_id_1>_report.pdf
  ├── <patient_id_2>/
  │   ├── <patient_id_2>_predictions.json
  │   ├── <patient_id_2>_heatmap.png
  │   ├── <patient_id_2>_source_image.png
  │   └── <patient_id_2>_report.pdf
  └── ...

File	Description
`_predictions.json`	AI prediction results (findings, confidence scores, metadata)
`_heatmap.png`	AI-generated heatmap overlay highlighting areas of concern
`_source_image.png`	Original DICOM image converted to PNG
`_report.pdf`	Auto-generated clinical-style PDF report

The prediction JSON structure is identical to the one documented in Single Inference → Prediction JSON Structure.

# Important Notes

Skipped Files

Files that fail during processing (unreadable DICOM, missing Patient ID, inference error) are silently skipped. The bulk operation continues with remaining files. Check server logs for details on skipped files.

The engine scans recursively through the input folder — sub-directories are included.
Only files with the .dcm extension are picked up for processing.
If multiple DICOM files share the same Patient ID, their outputs will overwrite each other in the same patient folder.

# Validation Rules

Check	Error Code	Message
Missing required fields	`400`	`<field> is required in the request`
Invalid input path	`400`	`Invalid path input_folder_path: ...`
Input folder does not exist	`400`	`Input folder path does not exist: ...`
No `.dcm` files found	`400`	`No Dicom images found in the provided path`
Output folder creation fails	`500`	`Unable to create output folder: ...`

# cURL Example

curl -X POST http://<server-ip>:8500/bulk_inference \
  -H "Content-Type: application/json" \
  -H "Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "input_folder_path": "/data/dicom/batch_001/",
    "output_folder_path": "/data/output/batch_001/"
  }'