Create an ephemeral Viewer session

POST/v1/viewer/ephemeral-sessions

Mints a 30-second tokenized landing URL for a userless, studyless Viewer session. The token names a customer retrievalId (not an Avara study). Optional options are echoed verbatim on ephemeral.access_requested (max 3072 bytes JSON). Optional hangingProtocol applies a single-monitor layout when the viewer loads. Requires a customer study webhook on the API key.

Body ParametersJSONExpand Collapse

retrievalId: string

Opaque customer handle for this view session. Avara stores and echoes it; it is not an Avara study ID.

minLength1

maxLength1024

hangingProtocol: optional EphemeralHangingProtocol { layout, viewportAssignments }

Optional single-monitor hanging protocol applied when the ephemeral viewer loads. Omitted = no protocol. Invalid shape is rejected.

layout: ViewerLayout

Viewport grid layout for an ephemeral hanging protocol. Wire values match first-party viewer layouts (‘1x1’ through ‘4x4’).

One of the following:

"1x1"

"1x2"

"1x3"

"1x4"

"2x1"

"2x2"

"2x3"

"2x4"

"3x1"

"3x2"

"3x3"

"3x4"

"4x1"

"4x2"

"4x3"

"4x4"

viewportAssignments: array of string

options: optional map[unknown]

Optional JSON object echoed verbatim on ephemeral.access_requested. Avara does not read or edit it. Hard cap 3072 bytes on JSON.stringify. Examples: studyInstanceUids or internal ids for multi-study reads. Not for URLs or manifests.

ReturnsExpand Collapse

url: string

Create an ephemeral Viewer session

curl https://api.avarasoftware.com/v1/viewer/ephemeral-sessions \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $AVARA_API_KEY" \
    -d '{
          "retrievalId": "order-12345",
          "hangingProtocol": {
            "layout": "2x2",
            "viewportAssignments": [
              "Axial T1",
              "Axial T2",
              null,
              "Sagittal T2"
            ]
          }
        }'

{
  "url": "https://viewer.avarasoftware.com/token/landing?token=abc123"
}

Returns Examples

{
  "url": "https://viewer.avarasoftware.com/token/landing?token=abc123"
}