Skip to content

WADO-RS — Retrieve Instances

The Retrieve transaction (PS3.18 §10.4) retrieves stored studies, series, instances, frames, metadata, rendered images, and thumbnails by reference.

Method Path Description
GET /studies/{study} Retrieve all instances within a study
GET /studies/{study}/metadata Retrieve metadata for all instances within a study
GET /studies/{study}/series/{series} Retrieve all instances within a series
GET /studies/{study}/series/{series}/metadata Retrieve metadata for all instances within a series
GET /studies/{study}/series/{series}/instances/{instance} Retrieve a single instance
GET /studies/{study}/series/{series}/instances/{instance}/metadata Retrieve metadata for a single instance
GET /studies/{study}/series/{series}/instances/{instance}/frames/{frames} Retrieve one or many frames from a single instance (comma-separated frame numbers, 1-indexed)
GET /studies/{study}/series/{series}/instances/{instance}/rendered Retrieve an instance rendered into an image format (renders frame 0)
GET /studies/{study}/series/{series}/instances/{instance}/frames/{frames}/rendered Retrieve frame(s) rendered into an image format
GET /studies/{study}/series/{series}/instances/{instance}/thumbnail Retrieve a thumbnail of an instance (renders frame 0)
GET /studies/{study}/series/{series}/instances/{instance}/frames/{frames}/thumbnail Retrieve thumbnail(s) of frame(s)

Authorization

When viewer-JWT verification is enabled for the deployment, every request to this interface must carry Authorization: Bearer <jwt>, and the study named in the path must be included in the token's scope. See JWT Authorization for the token format, scope semantics, and status codes.

Retrieve instances within a study, series, or a single instance

The following Accept headers are supported:

  • multipart/related; type="application/dicom"
  • application/dicom
  • application/*
  • */* (defaults to multipart/related; type="application/dicom")

Transfer syntax negotiation

The transfer-syntax Accept-header parameter (PS3.18 §8.7.3.5.2) is supported. When a specific transfer syntax is requested and differs from the stored one, each instance is transcoded on the fly before being returned. transfer-syntax=* (or omitting the parameter) returns instances in their stored transfer syntax — which may be the result of ingest-time transcoding.

Each part's Content-Type carries a transfer-syntax parameter identifying the actual returned syntax (PS3.18 §8.7.9).

Transcoding is available between any pair of supported transfer syntaxes. A requested transfer syntax that is unsupported, or for which no codec is available, results in 406 (Not Acceptable).

Retrieve frames

Frame numbers are 1-indexed and comma-separated in the path.

The following Accept headers are supported:

  • multipart/related — returns multipart/related; type="<frame media type>" with the appropriate media type based on the instance's transfer syntax
  • application/octet-stream
  • application/*
  • */*

The frame media type is derived from the returned transfer syntax:

Media type Transfer syntax
application/octet-stream Uncompressed
image/dicom-rle RLE Lossless
image/jpeg JPEG Baseline or JPEG Lossless
image/jls JPEG-LS
image/jp2 JPEG 2000
image/jxl JPEG XL
image/jphc High-Throughput JPEG 2000

Notes:

  • A single-part response carries the frame media type, not application/octet-stream. A request for one frame under Accept: */* against a JPEG-encoded instance is answered Content-Type: image/jpeg; only an instance in an uncompressed transfer syntax is answered application/octet-stream. The bytes are the stored frame, and the header names what they actually are.
  • A request naming more than one frame is always answered as multipart/related, whatever the Accept header allows, because separate frames need separate body parts (PS3.18 §10.4.3).
  • The Accept header is checked against every frame media type this service can produce, not against the one this instance will produce. A request with Accept: application/octet-stream for a JPEG-encoded frame is therefore answered 200 with Content-Type: image/jpeg rather than 406. A client that can only decode one encoding should name the transfer syntax it wants with the transfer-syntax Accept-header parameter, which does govern what comes back. That parameter is read from a multipart/related, application/dicom, application/* or */* media range only — carried on a concrete image media type such as image/jpeg, it is ignored.

Transfer syntax negotiation

The transfer-syntax Accept-header parameter (PS3.18 §8.7.3.5.2) is supported. When a specific transfer syntax is requested and differs from the stored one, each frame is transcoded on the fly before being returned, and the frame media type reflects the target syntax. transfer-syntax=* (or omitting the parameter) returns frames in their stored transfer syntax — which may be the result of ingest-time transcoding.

Transcoding is available between any pair of supported transfer syntaxes. A requested transfer syntax that is unsupported, or for which no codec is available, results in 406 (Not Acceptable).

Retrieve metadata (for study, series, or instance)

The Accept header must allow application/dicom+json — application/*, */*, or no Accept header at all are accepted.

Metadata is returned in DICOM JSON format as defined in PS3.18 Annex F.

  • Compression: Metadata responses are served gzip-compressed when the client sends Accept-Encoding: gzip.
  • Bulk pixel data (PixelData, 7FE0,0010) is never included in metadata responses; retrieve it via the frames or instance endpoints.
  • ETag / cache validation is not supported for metadata endpoints.

Retrieve rendered images (for instance or frame)

The following Accept headers are supported:

  • image/png
  • image/jpeg
  • image/bmp
  • image/* (defaults to PNG)
  • */* (defaults to PNG)
  • multipart/related or application/octet-stream (defaults to PNG) — accepted so a client that names only a container gets a rendered image rather than a 406

The service renders the specified instance or frame(s) into the requested image format. For instance endpoints, frame 0 is rendered. Multiple frames are returned as multipart/related with individual image parts.

Parameter Format Description
viewport vw,vh[,sx,sy,sw,sh] Scaling dimensions (width and height are required positive integers). Crop parameters (sx, sy, sw, sh) are accepted but currently ignored
window center,width,function Windowing parameters. center and width must be numbers; function must be linear or sigmoid
quality 1-100 JPEG quality (integer 1–100, applies only to JPEG output)

Image formats are selected in priority order: PNG > JPEG > BMP.

Retrieve thumbnails (for instance or frame)

The following Accept headers are supported:

  • image/jpeg (default per the DICOM spec)
  • image/png
  • image/bmp
  • image/* (defaults to JPEG)
  • */* (defaults to JPEG)
  • multipart/related or application/octet-stream (defaults to JPEG) — accepted so a client that names only a container gets a thumbnail rather than a 406

The service generates a thumbnail of the specified instance or frame(s). For instance endpoints, frame 0 is rendered. Multiple frames are returned as multipart/related with individual image parts.

Parameter Format Description
viewport vw,vh Thumbnail dimensions (width and height are required positive integers). Defaults to 128,128

Image formats are selected in priority order: JPEG > PNG > BMP.

Status codes

Code Description
200 (OK) All requested data was retrieved successfully
400 (Bad Request) Invalid query parameters (e.g. malformed viewport, window, or quality value, or a non-integer frame number), or a /rendered or /thumbnail request naming more frames than the service is configured to render at once
401* (Unauthorized) Viewer-JWT verification is enabled and the request carries no valid bearer token
403* (Forbidden) A valid token that does not grant the requested study (the study is not in the token's scope)
404 (Not Found) The specified DICOM resource could not be found, or the instance does not contain pixel data for rendered/thumbnail requests
406 (Not Acceptable) The specified Accept header is not supported, or a requested transfer-syntax cannot be transcoded to
500 (Internal Server Error) The server encountered an unexpected error (if a mid-stream error occurs after headers are sent, the connection is torn down instead)

* See above for an explanation of how to authorize using Viewer-JWT verification.

Examples

Retrieve all instances in a study

curl "http://localhost:3000/studies/1.2.840.113619.2.55.3.604688119.868.1234567890.1" \
 [-H 'Authorization: Bearer <jwt-token>' \ ]
  -H 'Accept: multipart/related; type="application/dicom"'

Response: multipart/related with one application/dicom part per instance.

Retrieve a single instance in a specific transfer syntax

curl "http://localhost:3000/studies/1.2.840.../series/1.2.840.../instances/1.2.840..." \
 [-H 'Authorization: Bearer <jwt-token>' \ ]
  -H 'Accept: multipart/related; type="application/dicom"; transfer-syntax=1.2.840.10008.1.2.4.202'

Each part's Content-Type names the transfer syntax actually returned:

Content-Type: multipart/related; type="application/dicom"; boundary=...;

--...
Content-Type: application/dicom; transfer-syntax=1.2.840.10008.1.2.4.202

Retrieve metadata for a study

curl "http://localhost:3000/studies/1.2.840.../metadata" \
 [-H 'Authorization: Bearer <jwt-token>' \ ]
  -H "Accept: application/dicom+json" \
  -H "Accept-Encoding: gzip"

Response: DICOM JSON, one dataset per instance, without bulk pixel data (truncated to one dataset):

[
  {
    "00080016": {
      "vr": "UI",
      "Value": ["1.2.840.10008.5.1.4.1.1.2"]
    },
    "00080018": {
      "vr": "UI",
      "Value": ["1.2.840.113619.2.55.3.12345.1"]
    },
    "00100010": {
      "vr": "PN",
      "Value": [{ "Alphabetic": "DOE^JOHN" }]
    },
    "00080060": {
      "vr": "CS",
      "Value": ["CT"]
    },
    "00280010": {
      "vr": "US",
      "Value": [512]
    },
    "00280011": {
      "vr": "US",
      "Value": [512]
    }
  }
]

Retrieve frames

Retrieve frames 1 and 2 of a multiframe instance:

curl "http://localhost:3000/studies/1.2.840.../series/1.2.840.../instances/1.2.840.../frames/1,2" \
 [-H 'Authorization: Bearer <jwt-token>' \ ]
  -H "Accept: multipart/related"

A request naming more than one frame is answered as multipart/related, with each part carrying the frame's media type. A request for a single frame against a JPEG-encoded instance is answered as a single part:

HTTP/1.1 200 OK
Content-Type: image/jpeg

Retrieve a rendered image

Render frame 0 as PNG, scaled to 512×512, with windowing applied:

curl "http://localhost:3000/studies/1.2.840.../series/1.2.840.../instances/1.2.840.../rendered?viewport=512,512&window=40,400,linear" \
 [-H 'Authorization: Bearer <jwt-token>' \ ]
  -H "Accept: image/png" \
  --output rendered.png

Retrieve a rendered frame as JPEG with quality control

curl "http://localhost:3000/studies/1.2.840.../series/1.2.840.../instances/1.2.840.../frames/1/rendered?viewport=256,256&quality=85" \
 [-H 'Authorization: Bearer <jwt-token>' \ ]
  -H "Accept: image/jpeg" \
  --output frame1.jpg

Retrieve a thumbnail

curl "http://localhost:3000/studies/1.2.840.../series/1.2.840.../instances/1.2.840.../thumbnail?viewport=128,128" \
 [-H 'Authorization: Bearer <jwt-token>' \ ]
  -H "Accept: image/jpeg" \
  --output thumbnail.jpg

See also