# Ephemeral Sessions

## Create an ephemeral Viewer session

`client.viewer.ephemeralSessions.create(EphemeralSessionCreateParamsbody, RequestOptionsoptions?): EphemeralSessionCreateResponse`

**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.

### Parameters

- `body: EphemeralSessionCreateParams`

  - `retrievalId: string`

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

  - `hangingProtocol?: EphemeralHangingProtocol`

    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').

      - `"1x1"`

      - `"1x2"`

      - `"1x3"`

      - `"1x4"`

      - `"2x1"`

      - `"2x2"`

      - `"2x3"`

      - `"2x4"`

      - `"3x1"`

      - `"3x2"`

      - `"3x3"`

      - `"3x4"`

      - `"4x1"`

      - `"4x2"`

      - `"4x3"`

      - `"4x4"`

    - `viewportAssignments: Array<string | null>`

  - `options?: Record<string, 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.

### Returns

- `EphemeralSessionCreateResponse`

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

  - `url: string`

### Example

```typescript
import Avara from 'avara-software';

const client = new Avara({
  apiKey: process.env['AVARA_API_KEY'], // This is the default and can be omitted
});

const ephemeralSession = await client.viewer.ephemeralSessions.create({
  retrievalId: 'order-12345',
});

console.log(ephemeralSession.url);
```

#### Response

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

## Domain Types

### Ephemeral Session Create Response

- `EphemeralSessionCreateResponse`

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

  - `url: string`