# Ephemeral Sessions

## Create an ephemeral Viewer session

`viewer.ephemeral_sessions.create(EphemeralSessionCreateParams**kwargs)  -> 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

- `retrieval_id: str`

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

- `hanging_protocol: Optional[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"`

  - `viewport_assignments: List[Optional[str]]`

- `options: Optional[Dict[str, object]]`

  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

- `class EphemeralSessionCreateResponse: …`

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

  - `url: str`

### Example

```python
import os
from avara import Avara

client = Avara(
    api_key=os.environ.get("AVARA_API_KEY"),  # This is the default and can be omitted
)
ephemeral_session = client.viewer.ephemeral_sessions.create(
    retrieval_id="order-12345",
)
print(ephemeral_session.url)
```

#### Response

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

## Domain Types

### Ephemeral Session Create Response

- `class EphemeralSessionCreateResponse: …`

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

  - `url: str`