# Response Format & 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 a JWT token string for `/token`, or `null` for inference endpoints
`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`	`output_folder_path 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`	`Patient ID is empty or None...`	DICOM has no Patient ID tag
`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 JSON output follows this schema:

{
  "name": "string",
  "presence": true | false,
  "confidence": 0.0 - 1.0
}

Field	Type	Description
`name`	`string`	Disease name (e.g., `"Tuberculosis"`, `"Cardiomegaly"`)
`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.

# Metadata Schema

{
  "model_version": "v1.0.1",
  "patient_id": "string",
  "patient_name": "string",
  "sop_instance_uid": "string",
  "age": "string",
  "sex": "string"
}

Field	Source	Description
`model_version`	Static	AI model version
`patient_id`	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 (e.g., `"045Y"`)
`sex`	DICOM tag `PatientSex`	Patient sex (`"M"`, `"F"`, or `"O"`)