API Reference

Viewer

Ephemeral Sessions

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Create an ephemeral Viewer session

EphemeralSessionCreateResponse viewer().ephemeralSessions().create(EphemeralSessionCreateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())

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.

ParametersExpand Collapse

EphemeralSessionCreateParams params

String retrievalId

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

minLength1

maxLength1024

Optional<EphemeralHangingProtocol> hangingProtocol

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

Optional<Options> options

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

class EphemeralSessionCreateResponse:

Tokenized landing URL for an ephemeral Viewer session (30-second token).

String url

Create an ephemeral Viewer session

Java

HTTP

TypeScript

Python

Java

C#

package com.avarasoftware.example;

import com.avarasoftware.client.AvaraClient;
import com.avarasoftware.client.okhttp.AvaraOkHttpClient;
import com.avarasoftware.models.viewer.ephemeralsessions.EphemeralSessionCreateParams;
import com.avarasoftware.models.viewer.ephemeralsessions.EphemeralSessionCreateResponse;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AvaraClient client = AvaraOkHttpClient.fromEnv();

        EphemeralSessionCreateParams params = EphemeralSessionCreateParams.builder()
            .retrievalId("order-12345")
            .build();
        EphemeralSessionCreateResponse ephemeralSession = client.viewer().ephemeralSessions().create(params);
    }
}

200 example

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

Returns Examples

200 example

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