# Response Format and Error Codes

All LeapAI CXR API endpoints return responses in a consistent JSON structure.

# Standard Response Format

Every API response follows this schema:

{
  "Result": "Success | Warning | Failure",
  "Data": "<object | string | null>",
  "Message": "Human-readable message"
}

Field	Type	Description
`Result`	`string`	One of `Success`, `Warning`, or `Failure`
`Data`	`any`	Response payload. Contains an object for `/single_inference`, or `null` for `/bulk_inference`
`Message`	`string`	A descriptive message about the outcome

# HTTP Status Codes

Status Code	Meaning	When
`200`	OK	Request processed successfully
`400`	Bad Request	Missing or invalid request parameters
`401`	Unauthorized	Missing, expired, or invalid JWT token
`415`	Unsupported Media Type	Request body is not valid JSON
`500`	Internal Server Error	Unexpected server-side error during processing

# Common Error Responses

# Authentication Errors

Status	Message	Cause
`401`	`Token missing`	No `Authorization` header on protected endpoint
`401`	`Token expired`	JWT has expired (valid for 30 days)
`401`	`Invalid token`	Malformed or tampered JWT

# Single Inference Errors

Status	Message	Cause
`400`	`input_image_path is required in the request`	Missing required field
`400`	`save_to_disk is required in the request`	Missing required field
`400`	`Invalid path input_image_path: ...`	Path cannot be parsed
`400`	`Input image path does not exist: ...`	File not found on disk
`400`	`Requested image is not a DICOM file: ...`	File extension is not `.dcm`
`400`	`Invalid DICOM image, unable to fetch patient ID: ...`	Cannot read DICOM metadata
`400`	`Invalid patient_id: '...' in request body`	Request body `patient_id` is empty or invalid
`400`	`Patient ID is empty or None...`	DICOM has no Patient ID tag
`400`	`Invalid value for save_to_disk, should be a boolean: ...`	Invalid type for `save_to_disk`
`400`	`output_folder_path is required in the request when save_to_disk is True`	Missing output folder path
`500`	`Unable to create output folder: ...`	Filesystem permission issue
`500`	`Single Inference failed due to an internal error`	Unhandled server error

# Bulk Inference Errors

Status	Message	Cause
`400`	`input_folder_path is required in the request`	Missing required field
`400`	`output_folder_path is required in the request`	Missing required field
`400`	`Invalid path input_folder_path: ...`	Path cannot be parsed
`400`	`Input folder path does not exist: ...`	Folder not found on disk
`400`	`No Dicom images found in the provided path`	No `.dcm` files in input folder
`500`	`Unable to create output folder: ...`	Filesystem permission issue
`500`	`Bulk inference failed due to an internal error`	Unhandled server error

# Health Check

# `GET /ping`

A simple health-check endpoint to verify the server is running.

{
  "status": "ok"
}

The /ping endpoint does not require authentication and does not follow the standard response format.

# Disease Findings Schema

Each entry in the findings array within the prediction output follows this schema:

{
  "name": "string",
  "presence": true,
  "confidence": 0.0
}

Field	Type	Description
`name`	`string`	Disease name
`presence`	`boolean`	Whether the disease is detected (`true`) or not (`false`)
`confidence`	`float`	Confidence score between `0.0` and `1.0`

Confidence Threshold

A disease is marked as presence: true when its confidence score is >= 0.5.

# Conditions Covered

The findings array can include the following conditions:

Tuberculosis
Cardiomegaly
Pleural Thickening
Pleural Effusion
Pneumothorax
Consolidation
Atelectasis
Nodule/Mass
Fibrosis
Infiltration
Calcification

# Metadata Schema

{
  "model_version": "<string>",
  "patient_id": "<string>",
  "patient_name": "<string>",
  "sop_instance_uid": "<string>",
  "age": "<string>",
  "sex": "<string>"
}

Field	Source	Description
`model_version`	Static	Version identifier for the AI engine
`patient_id`	Request `patient_id` if provided, else DICOM tag `PatientID`	Patient identifier
`patient_name`	DICOM tag `PatientName`	Patient name
`sop_instance_uid`	DICOM tag `SOPInstanceUID`	Unique DICOM instance identifier
`age`	DICOM tag `PatientAge`	Patient age (for example, `045Y`)
`sex`	DICOM tag `PatientSex`	Patient sex (`M`, `F`, or `O`)