REST API¶
VoxelKit ships with a FastAPI server. It exposes the same inspect, preview, and report operations as the CLI and Python library — but over HTTP, so you can call them from any language or service.
Starting the server¶
The API will be live at http://127.0.0.1:8000.
Interactive docs
FastAPI generates Swagger UI automatically. Open http://127.0.0.1:8000/docs in your browser to try every endpoint interactively without writing any code.
Health check¶
Returns {"status": "ok"} if the server is running. Useful as a liveness probe.
Endpoint overview¶
All endpoints accept multipart/form-data file uploads. JSON endpoints return application/json. Preview endpoints return image/png.
| Endpoint | Method | Returns | Page |
|---|---|---|---|
/nifti/metadata |
POST | JSON metadata | → |
/nifti/preview |
POST | PNG image | → |
/h5/inspect |
POST | JSON metadata | → |
/h5/slice |
POST | PNG image | → |
/tiff/metadata |
POST | JSON metadata | → |
/tiff/preview |
POST | PNG image | → |
/tiff/report |
POST | JSON QA report | → |
/embedding/report |
POST | JSON QA report | → |
/embedding/preview |
POST | PNG heatmap | → |
/health |
GET | {"status":"ok"} |
above |
General request pattern¶
Every endpoint takes a file upload. For JSON responses:
For PNG responses, save to a file:
curl -X POST "http://127.0.0.1:8000/nifti/preview?plane=axial" \
-F "file=@scan.nii.gz" \
--output preview.png
Error responses¶
| Status | Meaning |
|---|---|
400 |
Bad request — wrong file type, missing required parameter, invalid input |
500 |
Server error — the file could not be processed |