Spine Analysis API

Submit lumbar spine MRI DICOM files for AI-powered stenosis grading using QueenBee-Spine v1.

Overview

Model: QueenBee-Spine v1
Task: Lumbar spine MRI stenosis grading
Accuracy: 80.4% classifier, 95.7% LLM agreement
Speed: ~4.7 seconds end-to-end
Cost: 10 credits ($0.10) per scan

Submit Analysis

POST /v1/spine/analyze

Request Headers:

`Content-Type`	`multipart/form-data`
`X-Client-ID`	Your client ID
`X-Timestamp`	Unix timestamp
`X-Signature`	Ed25519 signature

Request Body:

dicom_file DICOM file (.dcm) or ZIP archive

Example:

curl -X POST https://api.hostswarm.io/v1/spine/analyze \
  -H "X-Client-ID: $CLIENT_ID" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Signature: $SIGNATURE" \
  -F "dicom_file=@spine_mri.dcm" \
  --output report.pdf

Success Response (200):

Returns PDF binary with headers:

`Content-Type`	`application/pdf`
`X-Inference-Time-Ms`	Processing time in milliseconds
`X-Study-Id`	Internal study identifier
`X-Severe-Count`	Number of severe findings
`X-Moderate-Count`	Number of moderate findings

PDF Report Contents

The generated PDF includes:

Study Information: Patient ID (if present), study date, series description
Findings Table: 5 lumbar levels (L1-L2 through L5-S1)
Stenosis Grading: For each level:
- Central canal stenosis
- Left subarticular stenosis
- Right subarticular stenosis
- Left foraminal stenosis
- Right foraminal stenosis
Severity Levels: Normal, Mild, Moderate, Severe
AI Summary: Clinical narrative generated by LLM

Supported Input Formats

Format	Extension	Content-Type
DICOM	.dcm, .dicom	application/dicom
ZIP (DICOM series)	.zip	application/zip

DICOM Requirements: Lumbar spine MRI with axial T2-weighted images. Sagittal series also accepted for reference.

Error Responses

Code	Error	Description
401	unauthorized	Invalid or missing signature
402	insufficient_credits	Need 10 credits, balance too low
422	invalid_dicom	File is not valid DICOM or unsupported modality
422	no_lumbar_series	No lumbar spine series found in study
500	inference_error	Model inference failed

Python Example

from hostswarm_cli import BeeClient

with BeeClient() as client:
    result = client.submit_spine(
        file_path="spine_mri.dcm",
        output_path="report.pdf",
    )

    print(f"Report saved: {result['pdf_path']}")
    print(f"Inference time: {result['inference_time_ms']}ms")
    print(f"Severe findings: {result['severe_count']}")