Secure DICOM workflows for cloud, on premise and hybrid use support@dicom.link
Knowledge Base

API Reference

REST API endpoints including DICOMweb QIDO-RS, WADO-RS, STOW-RS, proxy operations, and administrative APIs.

Base URL: http://localhost:8080 (or configured HTTP port) Base URL (SSL): https://localhost:8443

Interactive API documentation: GET /openapi.json

Authentication

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
X-API-Key: your-api-key-here

DICOMweb — QIDO-RS

Search for studies

GET /wado/studies

Query parameters:

Parameter Description
PatientName Patient name (wildcards supported)
PatientID Patient identifier
StudyDate Date or range (YYYYMMDD-YYYYMMDD)
StudyInstanceUID Study instance UID
ModalitiesInStudy Comma-separated modalities
AccessionNumber Accession number
limit Max results (default 100)
offset Pagination offset 
curl "http://localhost:8080/wado/studies?PatientName=DOE*&StudyDate=20240101-20241231&limit=50"

Search for series

GET /wado/studies/{studyInstanceUID}/series

Search for instances

GET /wado/studies/{studyInstanceUID}/series/{seriesInstanceUID}/instances

DICOMweb — WADO-RS

Retrieve study / series / instance

GET /wado/studies/{studyInstanceUID}
GET /wado/studies/{studyInstanceUID}/series/{seriesInstanceUID}
GET /wado/studies/{studyInstanceUID}/series/{seriesInstanceUID}/instances/{sopInstanceUID}

Accept headers: application/dicom, multipart/related; type="application/dicom", application/json

Retrieve metadata

GET /wado/studies/{studyInstanceUID}/metadata
GET /wado/studies/{studyInstanceUID}/series/{seriesInstanceUID}/metadata
GET /wado/studies/{studyInstanceUID}/series/{seriesInstanceUID}/instances/{sopInstanceUID}/metadata

Retrieve rendered image

GET /wado/studies/{studyUID}/series/{seriesUID}/instances/{instanceUID}/rendered

Query parameters: viewport (e.g. 512,512), window (center,width), quality (1–100) Accept headers: image/jpeg, image/png, image/gif

DICOMweb — STOW-RS

Store study

POST /wado/studies
Content-Type: multipart/related; type="application/dicom"

curl -X POST \
  -H "Content-Type: multipart/related; type=\"application/dicom\"" \
  --data-binary @study.dcm \
  http://localhost:8080/wado/studies

Proxy APIs

C-ECHO — test connectivity

POST /proxy/echo/{serverid}

{ "success": true, "server_id": "pacs1", "response_time_ms": 45 }

C-STORE — store to specific PACS

POST /proxy/cstore/{serverid}
Content-Type: application/dicom

Proxy QIDO-RS / WADO-RS

GET /proxy/wado/{serverid}/rs/studies
GET /proxy/wado/{serverid}/rs/studies/{studyUID}/series
GET /proxy/wado/{serverid}/rs/studies/{studyUID}/series/{seriesUID}/instances
GET /proxy/wado/{serverid}/rs/studies/{studyUID}

Administrative APIs

System status

GET /api/status

{
  "service_name": "DICOM Proxy",
  "version": "1.09.1",
  "uptime_seconds": 3600,
  "studies_count": 1542,
  "storage_used_gb": 156.7,
  "license_status": "Valid"
}

Connection status

GET /api/connections

Configuration

GET /api/config
PUT /api/config

Server management

GET    /api/servers
POST   /api/servers
PUT    /api/servers/{serverid}
DELETE /api/servers/{serverid}

Database operations

GET    /api/database/studies
GET    /api/database/series/{studyInstanceUID}
DELETE /api/database/studies/{studyInstanceUID}
POST   /api/database/cleanup
POST   /api/database/reindex

Metrics

GET /api/metrics

Returns CPU, memory, disk I/O, network stats, and per-DICOM-service request rates.

TUS resumable upload

POST  /files/
PATCH /files/{upload-id}
HEAD  /files/{upload-id}

Error format

{
  "error": {
    "code": "INVALID_DICOM_DATA",
    "message": "The DICOM file contains invalid data",
    "details": "Missing required tag: PatientID (0010,0020)",
    "timestamp": "2024-03-15T14:30:00Z",
    "request_id": "req-123456"
  }
}

Common error codes

Code Description
INVALID_PARAMETERS Request parameters are invalid
INVALID_DICOM_DATA DICOM data is invalid or corrupted
STORAGE_FULL Storage quota exceeded
SERVER_UNREACHABLE Configured PACS server unreachable
LICENSE_EXPIRED Software licence has expired
RATE_LIMIT_EXCEEDED Too many requests

Rate limiting

  • Default: 1 000 requests/hour per IP
  • Authenticated: 5 000 requests/hour
  • Response headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

Pagination

?limit=100&offset=0

Response headers: X-Total-Count, Link (next/prev/first/last)

Quick client examples

JavaScript/Node.js

const axios = require('axios');

async function searchStudies(params = {}) {
  const res = await axios.get('http://localhost:8080/wado/studies', { params });
  return res.data;
}

async function storeStudy(dicomBuffer) {
  const res = await axios.post('http://localhost:8080/wado/studies', dicomBuffer, {
    headers: { 'Content-Type': 'application/dicom' }
  });
  return res.data;
}

Python

import requests

def search_studies(**params):
    return requests.get('http://localhost:8080/wado/studies', params=params).json()

def store_study(dicom_bytes):
    return requests.post(
        'http://localhost:8080/wado/studies',
        data=dicom_bytes,
        headers={'Content-Type': 'application/dicom'}
    ).json()

Next: SDK Documentation | Examples & Tutorials