The DICOM Toolbox, REST API Guide

A comprehensive guide to the headless automation and remote control capabilities of the DICOM Toolbox REST API Server.

Security

API Key Authentication

Secure all REST API endpoints using a configurable X-API-Key header. Toggleable granular access control ensures only authorised scripts and users can execute commands against the server.

How to use it Enable "Require API Key" in the UI. Pass X-API-Key: YOUR_SECRET_KEY in the headers of your cURL or Postman requests to authenticate.
DICOM Network

Headless DICOM Networking

Trigger DICOM C-ECHO (Ping), Modality Worklist (MWL) Queries, and C-STORE (Send) operations remotely by posting JSON payloads. No need to click buttons in the UI.

How to use it POST to /api/v1/network/store with a JSON body specifying the target AE Title, IP, Port, and a list of local file paths. The toolbox will send them in the background.
DICOM Files

Automated Anonymisation & Tag Editing

Programmatically strip PHI and PID from DICOM files, or inject/modify specific DICOM tags (e.g., Patient Name, Study Date) via REST endpoints.

How to use it POST to /api/v1/files/anonymize with a directory path. The toolbox will process hundreds of files using your pre-configured anonymisation profile automatically.
Remote UI Control

Remote GUI Orchestration

Control the application's physical user interface from a script. Load files into the workspace, clear the screen, exclude files, and get a JSON listing of everything currently loaded in the UI.

How to use it POST a file path to /api/v1/ui/load. Watch the DICOM Toolbox UI on your monitor automatically populate with the DICOM files you just sent via API.
HL7 Integration

HL7 Send & Validate Hooks

Leverage the toolbox's HL7 engine from your own applications. Send raw HL7 text to the API, and the toolbox will route it via MLLP, or validate its schema compliance.

How to use it Your custom web-app doesn't know how to send MLLP over TCP. Just HTTP POST the HL7 text to /api/v1/hl7/send, and the toolbox handles the complex MLLP transmission and returns the ACK.
DICOM Files

PDF & SR Data Extraction

Extract clinical text from Structured Reports (SR) or inject a standard PDF document into a valid DICOM wrapper (Encapsulated PDF) purely via API calls.

How to use it POST a local PDF file path and patient demographics to /api/v1/ui/insert-pdf. The toolbox generates a DICOM file containing your PDF, ready to be sent to a PACS.
System

Health Diagnostics & Status

Check the heartbeat of the toolbox. Returns a JSON payload detailing uptime, active feature toggles, version info, and total requests served.

How to use it GET /api/v1/status. Integrate this with your IT monitoring dashboard (like Datadog or PRTG) to ensure the DICOM Toolbox API is online and responding.
System

Real-Time Traffic Log

Every REST API request is intercepted and logged into the GUI traffic console, displaying the HTTP Method, Endpoint, Client IP, Status Code, and processing time in milliseconds.

How to use it Useful for debugging your Python/PowerShell scripts. Send an API request and look at the Toolbox UI to see exactly how fast it responded and if it hit any 401 Unauthorised errors.