DICOMweb servicesURLs, media types and status codes
One page with the DICOMweb transactions of PS3.18: which URL and method does what, which media types come back, which query parameters search and render, what the status codes mean, and how each maps to the older DIMSE service.
91 rows
The DICOMweb services
PS3.18 defines one URI service and several REST services. Each service is a set of transactions on a set of resources.
| Service | What it manages | Also known as |
|---|---|---|
| Studies Service | Studies, series, instances, and their metadata, rendered, thumbnail, frame and bulk data variants. | WADO-RS (retrieve), STOW-RS (store), QIDO-RS (search) |
| Worklist Service | A worklist of workitems (UPS instances): create, retrieve, update, change state, cancel, search and subscribe. | UPS-RS |
| URI Service | Retrieval of single composite instances by a query string. | WADO-URI |
| Non-Patient Instance Service | Non-patient instances such as color palettes. | |
| Storage Commitment Service | A request that the server takes safekeeping of instances. | |
| Modality Scheduled Procedure Step Service | Searching for scheduled procedure steps. | |
| Modality Performed Procedure Step Service | Reporting progress on performed procedure steps. |
No rows match the filter in this table.
Every REST service must implement the Retrieve Capabilities transaction: an `OPTIONS` request on the base URI that returns a machine readable description of what the server supports, as WADL (`application/vnd.sun.wadl+xml`) or `application/json`.
The Studies Service transactions
Three transactions, each with one HTTP method.
| Transaction | Method | Request payload | Success response | DIMSE counterpart |
|---|---|---|---|---|
Search (QIDO-RS) | GET | None | A list of matches | C-FIND |
Retrieve (WADO-RS) | GET | None | Instances, metadata, renderings, pixel data or bulk data | C-MOVE or C-GET |
Store (STOW-RS) | POST | Instances | A Store Instances Response | C-STORE |
| Retrieve Capabilities | OPTIONS | None | A Capabilities Description | No equivalent |
No rows match the filter in this table.
An origin server may be a native implementation or a DIMSE proxy that converts web requests into DIMSE requests and back. A proxy has fewer mandatory search resources.
Search URLs (QIDO-RS)
Six search resources. Native servers support all; DIMSE proxies must support the hierarchical ones.
| Resource | URL template | Native | Proxy | Query type |
|---|---|---|---|---|
| All Studies | /studies{?search*} | Mandatory | Mandatory | Hierarchical |
| Study's Series | /studies/{study}/series{?search*} | Mandatory | Mandatory | Hierarchical |
| Study's Series' Instances | /studies/{study}/series/{series}/instances{?search*} | Mandatory | Mandatory | Hierarchical |
| Study's Instances | /studies/{study}/instances{?search*} | Mandatory | Optional | Relational |
| All Series | /series{?search*} | Mandatory | Optional | Relational |
| All Instances | /instances{?search*} | Mandatory | Optional | Relational |
No rows match the filter in this table.
Examples from the standard: `/studies?PatientID=11235813&StudyDate=20130509-20130510` and `/studies?00100010=SMITH*&limit=25`. A key can be a keyword or an 8-digit tag.
Search query parameters
All search transactions support these parameters on the origin server. The user agent may use them.
| Parameter | Meaning | DIMSE counterpart | Detail |
|---|---|---|---|
| Attribute = value | A matching key | Matching key | Same matching types as C-FIND: single value, wild card, range, UID list. Each attribute once. Characters such as #, [, ], &, = and , must be percent-encoded. |
includefield | More attributes to return, or all | Return key | A comma-separated list, or all. If all is present no other includefield is allowed. |
limit | Maximum number of matches in one response | - | An unsigned integer. The server may apply its own system limit. |
offset | Number of matches to skip | - | An unsigned integer, default 0. The same request returns the same ordered list if the data has not changed. |
fuzzymatching | Fuzzy matching of person names | Extended negotiation | true or false, default false. If not supported the server searches literally and adds a Warning: 299 header. |
emptyvaluematching | Match attributes that have an empty value | - | Optional, default false. If not supported the server adds a Warning header. |
multiplevaluematching | Match attributes with several values | - | Optional, default false. If not supported the server adds a Warning header. |
No rows match the filter in this table.
If more results exist the response carries `Warning: 299 <service>: There are <remaining> additional results that can be requested`. A search with no matches is a 200 with an empty payload (an empty JSON array for application/dicom+json). An unsupported parameter is ignored; a supported parameter with an invalid value gives 400.
Required matching attributes and what a search returns
The levels follow the Study Root model: the patient attributes belong to the study. These are the required matching attributes per level.
| Level | Required matching attributes | Always returned |
|---|---|---|
| Study | Study Date (0008,0020), Study Time, Accession Number (0008,0050), Modalities In Study (0008,0061), Referring Physician Name, Patient Name, Patient ID, Study Instance UID (0020,000D), Study ID | The matching attributes plus Patient's Birth Date and Sex, Number of Study Related Series (0020,1206) and Instances (0020,1208), and Retrieve URL (0008,1190) when retrievable |
| Series | Modality (0008,0060), Series Instance UID (0020,000E), Series Number, Performed Procedure Step Start Date and Time, Request Attributes Sequence | Plus Number of Series Related Instances (0020,1209), and Series Description if known |
| Instance | SOP Class UID (0008,0016), SOP Instance UID (0008,0018), Instance Number | Plus Rows, Columns, Bits Allocated and Number of Frames if known, and Retrieve URL |
No rows match the filter in this table.
The list is consistent with the keys of IHE RAD-14. Optionally the server can support the Repository Query attributes Prior Record Key (0008,041C) and Maximum Number of Records (0008,0429). The response may include Available Transfer Syntax UID (0008,3002).
Retrieve URLs (WADO-RS)
The resources of the Retrieve Transaction. All are `GET`.
| What you get | URL template | Support |
|---|---|---|
| Instances of a study, series or one instance | /studies/{study}, .../series/{series}, .../instances/{instance} | Mandatory |
| Metadata (without bulk data) | /studies/{study}/metadata, .../series/{series}/metadata, .../instances/{instance}/metadata | Mandatory |
| Rendered images or documents | .../rendered on a study, series or instance, and .../frames/{frames}/rendered | Mandatory |
| Thumbnail | .../thumbnail on a study, series, instance or frames | Optional, all or none |
| Bulk data | {bulkdataURI}, and .../bulkdata on a study, series or instance | Bulk Data URI mandatory, the /bulkdata resources optional |
| Pixel data | .../pixeldata on a study, series or instance | Optional |
| Frames | /studies/{study}/series/{series}/instances/{instance}/frames/{frames} | Mandatory |
| Rendered MPR volume | .../renderedmpr | Optional |
| Rendered 3D volume | .../rendered3d | Optional |
No rows match the filter in this table.
`{frames}` is a comma-separated list of frame numbers in ascending order. The retrieve transaction has no request payload. A Bulk Data URI can be absolute, relative with an absolute path, or relative to the metadata request.
Media types
The Accept header chooses the representation. These are the defaults and requirements from PS3.18.
| Resource | Media type | Usage |
|---|---|---|
| Instances (retrieve) | multipart/related; type="application/dicom" | Default |
| Instances (retrieve) | multipart/related; type="application/octet-stream" | Required (the same as retrieving the bulk data) |
| A single instance | application/dicom | Optional. Single part: only for a resource that is one item. |
| Metadata | application/dicom+json | Default. JSON for several instances is one top-level array. |
| Metadata | multipart/related; type="application/dicom+xml" | Required |
| Bulk data and pixel data | multipart/related; type="application/octet-stream" | Required |
| Thumbnail | image/jpeg | Default |
| Rendered single frame image | image/jpeg (default), image/gif and image/png (required for REST) | Also optional: image/jp2, image/jph, image/jxl |
| Rendered text | text/html (default), text/plain (required), text/xml (required for REST) | Also optional: text/rtf, application/pdf |
| Rendered video | video/mpeg, video/mp4, video/H265 | Optional |
| Search results | application/dicom+json (default), multipart/related; type="application/dicom+xml" (required) | |
| Capabilities | application/vnd.sun.wadl+xml or application/json |
No rows match the filter in this table.
Two parameters refine a DICOM media type: `transfer-syntax=<UID or *>` and `charset=`. A media type may have only one transfer-syntax value, so several choices are given as several media types with q values. Implicit VR Little Endian and the retired Explicit VR Big Endian must not be used. The default for an uncompressed instance is Explicit VR Little Endian (`1.2.840.10008.1.2.1`).
Parameters for rendered images
These work on the /rendered resources. They are applied as if they were a presentation state, and all are optional for the user agent.
| Parameter | Value | Meaning | Errors |
|---|---|---|---|
accept | A rendered media type | The format of the image | 406 if not supported |
annotation | patient and/or technique | Burns patient or technique information into the picture. Absent means no annotation. | 400 for non-keywords; unsupported values are ignored with a Warning |
quality | 1 to 100 | Requested quality for formats that allow lossy compression | 400 if not an integer from 1 to 100 |
viewport | vw,vh or vw,vh,sx,sy,sw,sh | Crop a source region and scale it to fit the viewport without distortion. Without it the image keeps its own size. | 400 if ill-formed |
window | center,width,function | Window center and width, function linear, linear-exact or sigmoid. All three are required. | 400 if missing or ill-formed, and not allowed on a presentation state |
iccprofile | no, yes, srgb, adobergb, rommrgb or displayp3 | Whether and which ICC profile is in the rendered image |
No rows match the filter in this table.
The grayscale or color space of a rendered image is not defined by the standard, even if the pipeline works in P-Values. For a presentation state as target the viewport can only be `vw,vh`.
Status codes
DICOMweb uses ordinary HTTP status codes. These are the ones the transactions use most.
| Code | Meaning in DICOMweb | Where |
|---|---|---|
200 OK | All representations are in the payload. For a search with no matches: an empty list. A store where every instance was stored. | Search, Retrieve, Store |
201 Created | One or more new resources were created. | Create |
202 Accepted | The request was accepted but not completed, or for a store only some instances were stored and others have warnings or failures. | Store |
204 No Content | Success without a payload, for example a conditional retrieve that is not modified. | Various |
304 Not Modified | A conditional request found the cached copy up to date. | Capabilities |
400 Bad Request | Bad syntax, an invalid query parameter value, or an invalid header. | All |
401 Unauthorized | No valid credentials. The server sends a WWW-Authenticate header. | All |
403 Forbidden | Understood but refused, for example insufficient privileges. A server may use 404 instead. | All |
404 Not Found | The target resource does not exist, or the server does not disclose that it does. | Retrieve |
405 Method Not Allowed | The method is not supported by the resource. The response has an Allow header. | All |
406 Not Acceptable | No representation matches the Accept header or query parameter. | Retrieve |
409 Conflict | Nothing could be stored because of a conflict: unsupported SOP Class, Study Instance UID mismatch. | Store |
410 Gone | The resource was deleted. | Retrieve |
413 Payload Too Large | A retrieved resource is too large to return, or a search was too broad. | Retrieve, Search |
415 Unsupported Media Type | The Content-Type of the request is not supported. | Store |
501 Not Implemented | Used for SOP Class not supported errors. | Various |
503 Service Unavailable | Temporary overload or maintenance. | All |
No rows match the filter in this table.
A failure response should have a Status Report in the payload. The standard notes that policy may require a 404 in place of a 401 or 403 so that a client cannot infer that a resource exists.
DICOMweb next to DIMSE
The services map on each other, but not one to one.
| DIMSE | DICOMweb | Difference |
|---|---|---|
C-FIND (Study Root) | Search GET /studies, /series, /instances | Matching keys are query parameters, return keys are includefield. Paging has limit and offset. A search with no match returns 200. |
C-MOVE / C-GET | Retrieve GET /studies/{study}... | No sub-association and no move destination: the data comes back in the HTTP response. |
C-STORE | Store POST /studies | Many instances in one request, with a multipart body. The status is 200, 202 or 409. |
| Association negotiation (SOP Classes, transfer syntaxes) | Accept header, transfer-syntax parameter, Retrieve Capabilities | The client names the formats it accepts per request. |
UPS N-CREATE, N-GET, N-SET, N-ACTION, N-EVENT-REPORT | UPS-RS: Create, Retrieve, Update, Change State, Request Cancellation, Subscribe; notifications over a WebSocket connection | A workitem is a UPS instance and the worklist is a single collection per service. |
Status codes such as FF00, 0000, A700 | HTTP status codes plus a Warning header | A DICOM status code can be carried in the Warning header text. |
No rows match the filter in this table.
WADO-URI: the older single-instance service
The URI Service retrieves one composite instance with one GET. The resource is identified by query parameters, not by a path.
| Parameter | Value | Meaning |
|---|---|---|
requestType | WADO | Required. Anything else the server does not support gives 400. |
studyUID | A UID | Required, the Study Instance UID. |
seriesUID | A UID | Required, the Series Instance UID. |
objectUID | A UID | Required, the SOP Instance UID. |
contentType | application/dicom or a rendered media type | Optional. Transfer-syntax and charset media type parameters are forbidden and give 400. |
charset | A character set | Optional. |
No rows match the filter in this table.
Without a `contentType` and with an Accept header of `*/*` the response defaults to `image/jpeg`, a rendered instance. The URI Service retrieves only single instances and is more limited than the Retrieve Transaction of the Studies Service.
UPS-RS: the Worklist Service
The Worklist Service manages one worklist per service, holding workitems.
| Transaction | Method | URL | DIMSE counterpart |
|---|---|---|---|
| Create | POST | /workitems?{workitem} | N-CREATE |
| Retrieve | GET | /workitems/{workitem} | N-GET |
| Update | POST | /workitems/{workitem}?{TransactionUid} | N-SET |
| Change State | PUT | /workitems/{workitem}/state?requester={aetitle} | N-ACTION |
| Request Cancellation | POST | /workitems/{workitem}/cancelrequest?requester={aetitle} | N-ACTION |
| Search | GET | /workitems with match, includefield, fuzzymatching, offset and limit | C-FIND |
| Subscribe | POST | /workitems/{resource}/subscribers/{subscriber}, with optional deletionlock and filter | N-ACTION |
| Unsubscribe | DELETE | The subscription resource | N-ACTION |
No rows match the filter in this table.
The workitem UID goes in a query parameter of the Create request, where DIMSE uses the Affected SOP Instance UID. Notifications correspond to N-EVENT-REPORT. The client opens a WebSocket notification connection with `GET /subscribers/{requester}`, and the server sends the event reports over it.
Glossary
- Origin server
- The server that holds the resources and answers requests. A DICOMweb PACS endpoint.
- User agent
- The client that sends the request: a viewer, a scanner, an importer.
- Resource
- Something with a URL, such as a study, a series, an instance or a frame.
- Representation
- One encoding of a resource, chosen with a media type.
- Multipart payload
- A body with several parts, each with its own Content-Type and Content-Location, used for instances, frames and bulk data.
- Bulk data
- Large values in a data set, such as pixel data, that can be retrieved separately by a URI.
- Native / proxy
- A server that stores DICOM itself, or one that converts web requests into DIMSE requests for another system.
- Workitem
- One procedure step in the UPS worklist, called a UPS instance in DIMSE.
Summary
- Search, Retrieve and Store are
GET /studies...,GET /studies/{study}/...andPOST /studies: QIDO-RS, WADO-RS and STOW-RS. - Search keys are query parameters, with
includefield,limit,offsetandfuzzymatchingas extras. application/dicom+jsonis the default for search and metadata. Instances and bulk data come inmultipart/related.- A rendered image is
GET .../renderedand defaults toimage/jpegfor a single frame image. - A search with no matches returns 200 with an empty list. 202 on a store means only part of it was stored.
- Implicit VR Little Endian is not allowed in web services. The default uncompressed transfer syntax is Explicit VR Little Endian.
Common questions
What are the DICOMweb URLs for a study?
Search: /studies and /studies/{study}/series. Retrieve: /studies/{study} for the instances, /studies/{study}/metadata for the metadata, /studies/{study}/rendered for rendered images, with the same pattern for series and instances. Store: POST /studies or POST /studies/{study}.
Is it QIDO, WADO or STOW?
QIDO-RS searches (GET), WADO-RS retrieves (GET) and STOW-RS stores (POST). They are the Search, Retrieve and Store transactions of the Studies Service. WADO-URI is a separate, older service that retrieves one instance through a query string.
How do I page through a large search result?
Use limit and offset. The server returns a Warning header saying how many more results can be requested. The same request gives the same order as long as the data has not changed, but if studies are added or removed between requests the pages can be inconsistent.
Why does my search for an Accession Number or name return nothing?
The matching rules are those of C-FIND. A name is matched literally unless the server supports fuzzy matching, so a wild card such as SMITH* is usually needed. If you ask for fuzzy matching and the server does not support it, it searches literally and tells you with a Warning header.
Which transfer syntax do I get?
The one in the transfer-syntax parameter of the media type, if the server supports it and can supply it. Without one, the default is Explicit VR Little Endian for uncompressed data, unless the server only has the pixels in a compressed form that cannot be sent that way.
Can a web client delete studies?
The Studies Service transactions in PS3.18 2026d are Search, Retrieve and Store. Deleting is not one of them, though the status code 410 shows that a deleted resource is reported as gone.