canonical: https://jentic.com/apis/orthanc-server.com/orthanc-server

# Orthanc Server Orthanc API

The Orthanc API exposes the full REST interface of the Orthanc DICOM server, letting clients ingest, retrieve, and orchestrate medical imaging data across studies, series, instances, and patients. It supports DICOM-Web (QIDO-RS, WADO-RS, STOW-RS), DICOMweb proxies, modality work-list queries, and asynchronous DICOM transfers, plus Lua and Python scripting hooks. With 299 endpoints, the API covers everything from raw instance retrieval to peer routing, anonymisation, and modification of imaging tags.

## For AI agents

Query, store, and route DICOM medical imaging data through an Orthanc server. Agents can list studies, fetch instances, anonymise tags, and trigger DICOM transfers between modalities and peers.

## Scope

Does not handle electronic health records, appointment scheduling, or billing - use for DICOM imaging storage, retrieval, and routing only.

## Capabilities

- Retrieve DICOM instances, series, and studies by Orthanc identifier or DICOM UID
- Anonymise or modify DICOM tags on a single instance or whole study before export
- Query and retrieve images from remote modalities using DICOM C-FIND and C-MOVE
- Send studies to peers, modalities, or DICOM-Web servers asynchronously with job tracking
- Stream changes from the Orthanc event log to drive downstream imaging pipelines
- Run server-side Lua and Python scripts to react to incoming DICOM events

## Use cases

### Imaging Research Data Pipeline

Research teams use the Orthanc API to pull anonymised DICOM studies into machine-learning training pipelines. The `/studies/{id}/anonymize` endpoint strips PHI tags in place, while `/instances/{id}/file` returns the raw DICOM binary for storage in object stores. Throughput is bounded by Orthanc's local disk and any configured DICOM peers, and integration typically takes a day for a basic ingest loop.

Example prompt: Anonymise study with Orthanc ID abc123 by calling POST `/studies/abc123/anonymize` and download the resulting DICOM ZIP from the returned job.

### Clinical Modality Routing

Hospitals route DICOM studies between modalities, PACS, and viewers using Orthanc as a hub. Agents call `/modalities/{id}/store` to push selected studies to a remote modality, and use /jobs to track asynchronous transfers. The /queries endpoint supports DICOM C-FIND for upstream queries, enabling federated imaging workflows across departments.

Example prompt: Send study with ID xyz to modality 'RADIOLOGY_PACS' via POST `/modalities/RADIOLOGY_PACS/store` with the study resource ID and poll the returned job until completion.

### DICOM Tag Cleanup and Modification

Imaging coordinators correct or harmonise DICOM tags across cohorts using the Orthanc modify endpoints. `/instances/{id}/modify` and `/studies/{id}/modify` rewrite tags such as PatientName, AccessionNumber, or StudyDescription while preserving image pixel data. Bulk operations are handled through asynchronous jobs, making it practical to fix tag inconsistencies across thousands of instances.

Example prompt: Update PatientName on study abc123 to 'ANON_001' by POSTing to `/studies/abc123/modify` with the Replace dictionary set accordingly.

### AI Agent DICOM Orchestration via Jentic

AI agents that triage radiology cases need a programmable DICOM layer. Through Jentic, an agent searches for 'retrieve a DICOM study', loads the matching Orthanc operation schema, and executes the call with a scoped credential. This avoids embedding raw Orthanc credentials in agent prompts and lets the agent compose retrieval, anonymisation, and routing into a single workflow.

Example prompt: Use Jentic to search 'retrieve a DICOM study', load the GET `/studies/{id}` schema, and execute it for the patient currently being triaged.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/studies` | List all studies stored on the server |
| GET | `/studies/{id}` | Get details for a specific study |
| POST | `/studies/{id}/anonymize` | Anonymise a study and return a new resource |
| POST | `/studies/{id}/modify` | Modify DICOM tags across a study |
| GET | `/instances/{id}/file` | Download the raw DICOM file for an instance |
| POST | `/modalities/{id}/store` | Send a resource to a configured DICOM modality |
| GET | `/changes` | Read the server change log |
| GET | `/jobs` | List asynchronous jobs and their status |

## Key resources

- **Instances** — Individual DICOM instances; retrieve, modify, anonymise, or download as raw DICOM
- **Series and Studies** — Series and study-level operations including listing, retrieval, and modification
- **Patients** — Patient-level grouping of studies, with archive and protection controls
- **Modalities and Peers** — Configured DICOM modalities and Orthanc peers used for store, find, and move operations
- **Jobs and Changes** — Asynchronous job tracking and the server change log used to drive downstream automations

## Why Jentic

- **Setup:** The Orthanc API can run without credentials, but wiring it by hand still means handling any basic auth a hardened deployment adds and mapping the study, instance, and modality routes yourself. Through Jentic you install once, import Orthanc from the API Directory, store any credential once, and your agent calls it.
- **Permission scoping:** You choose which Orthanc operations the agent may call, so you can limit it to the operations it needs, such as listing studies and reading instance files, while destructive operations like modifying or anonymizing a study or storing to a modality stay out of the allowed set unless you add them.
- **Credential handling:** Any HTTP basic credentials your hardened Orthanc deployment uses are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'anonymize a DICOM study' or 'download an instance file', and Jentic returns the matching Orthanc operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **OSF API** — OSF stores research artefacts and metadata while Orthanc handles DICOM imaging; together they cover an open imaging research stack.
- **Figshare API** — Figshare publishes anonymised research datasets that often originate from imaging archives like Orthanc.
- **Crossref API** — Crossref provides DOI metadata for the publications that cite Orthanc-derived imaging cohorts.

## FAQ

### What authentication does the Orthanc API use?

The published OpenAPI specification declares no security schemes, so by default the Orthanc REST API is reachable without credentials on the demo server. In production deployments operators usually enable HTTP Basic auth via the Orthanc configuration file. When called through Jentic, any configured Basic credential is held in your Jentic One instance and injected at execution time, so it never enters the agent's prompt.

### Can I anonymise a DICOM study with the Orthanc API?

Yes. POST `/studies/{id}/anonymize` creates a new anonymised resource derived from the original study, with PHI tags such as PatientName and PatientID replaced. The same pattern exists at the instance and series level via `/instances/{id}/anonymize` and `/series/{id}/anonymize.`

### What are the rate limits for the Orthanc API?

Orthanc itself does not impose documented rate limits in its OpenAPI spec; throughput is constrained by the host server's CPU, disk, and any front-line reverse proxy or firewall. For long-running operations such as anonymisation or modality store, the API returns a job ID and you poll `/jobs/{id}` for completion rather than blocking on the request.

### How do I send a study to another DICOM modality through Jentic?

Through Jentic, search for 'send a study to a DICOM modality', load the schema for POST `/modalities/{id}/store`, and execute it with the modality alias and the Orthanc resource ID. The call returns a job ID that you can pass to GET `/jobs/{id}` to verify completion.

### Is the Orthanc API free to use?

Orthanc is open-source under the GPLv3 licence and the REST API is included with every Orthanc deployment at no cost. There is no per-call pricing - operational cost is the infrastructure you run Orthanc on.

### Can the Orthanc API stream new imaging events?

Yes. GET /changes returns a paginated change log of every event the server has seen, including NewInstance, NewStudy, and StablePatient. Agents poll /changes with the last seen sequence to react to new imaging data without scanning the full dataset.

### Can I limit what my agent is allowed to do with the Orthanc API?

Yes. Because you run your own self-hosted Jentic One instance, you decide which Orthanc operations the agent may call, so you can restrict it to read-only work such as listing studies with GET /studies and downloading instance files with GET `/instances/{id}/file.` Destructive operations, like modifying a study with POST `/studies/{id}/modify`, anonymising one with POST `/studies/{id}/anonymize`, or pushing a study to a device with POST `/modalities/{id}/store`, stay outside the allowed set unless you explicitly add them. Your own rules govern which operations and credentials the agent can use.