# Studies

## Create

`StudyCreateResponse Viewer.Studies.Create(StudyCreateParamsparameters, CancellationTokencancellationToken = default)`

**post** `/v1/viewer/studies`

Creates a new study in the Viewer system with the specified DICOM Study Instance UID and metadata. The study can be optionally assigned to a user.

### Parameters

- `StudyCreateParams parameters`

  - `required Severity severity`

    Priority level of the study. 'normal' for routine, 'high' for urgent, 'stat' for immediate attention

    - `"normal"Normal`

    - `"high"High`

    - `"stat"Stat`

  - `required string studyDescription`

    Description of the study/scan (e.g., 'Brain MRI with Contrast', 'Chest CT')

  - `required string studyInstanceUid`

    DICOM Study Instance UID. Must be a valid DICOM UID format (e.g., '1.2.840.10008.5.1.4.1.1.2')

  - `string assignedTo`

    User ID to assign the study to. Format: usr_{32-hex-chars}

  - `string expressCustomerID`

    Express customer ID for the study. Format: cus_{32-hex-chars}

  - `IReadOnlyDictionary<string, string> metadata`

    Custom key-value metadata for the study. Maximum 50 pairs, keys up to 100 chars, values up to 1000 chars

### Returns

- `class StudyCreateResponse:`

  A study entity in the Viewer system with viewing status

  - `required DateTimeOffset? CancelledAt`

    Timestamp when the study was cancelled, null if not cancelled

  - `required DateTimeOffset? CreatedAt`

    Timestamp when the study was created

  - `required Boolean IsCancelled`

    Whether the study has been cancelled

  - `required Severity Severity`

    Priority level of the study. 'normal' for routine, 'high' for urgent, 'stat' for immediate attention

    - `"normal"Normal`

    - `"high"High`

    - `"stat"Stat`

  - `required string StudyDescription`

    Description of the study/scan (e.g., 'Brain MRI with Contrast', 'Chest CT')

  - `required string StudyID`

    Unique study identifier. Format: stu_{32-hex-chars}

  - `required string StudyInstanceUid`

    DICOM Study Instance UID. Must be a valid DICOM UID format (e.g., '1.2.840.10008.5.1.4.1.1.2')

  - `required StudyViewerStatus StudyViewerStatus`

    - `"incomplete"Incomplete`

    - `"complete"Complete`

  - `required DateTimeOffset? UpdatedAt`

    Timestamp when the study was last updated

  - `UserReference? AssignedTo`

    A reference to a user with basic identifying information

    - `required string Email`

      User's email address

    - `required string UserID`

      Unique user identifier. Format: usr_{32-hex-chars}

    - `string FirstName`

      User's first name

    - `string LastName`

      User's last name

    - `string MiddleName`

      User's middle name

    - `string Suffix1`

      Name suffix (e.g., 'MD', 'Jr.')

    - `string Suffix2`

      Additional name suffix

  - `ApiKeyReference? CreatedByApiKey`

    A reference to an API key with basic identifying information

    - `required string ApiKeyID`

      Unique API key identifier (UUIDv4 format)

    - `required string Description`

      Human-readable description of the API key

    - `Boolean IsViewerEnabled`

      Whether this API key has access to the Viewer product

  - `UserReference? CreatedByUser`

    A reference to a user with basic identifying information

    - `required string Email`

      User's email address

    - `required string UserID`

      Unique user identifier. Format: usr_{32-hex-chars}

    - `string FirstName`

      User's first name

    - `string LastName`

      User's last name

    - `string MiddleName`

      User's middle name

    - `string Suffix1`

      Name suffix (e.g., 'MD', 'Jr.')

    - `string Suffix2`

      Additional name suffix

  - `ExpressCustomerReference? ExpressCustomer`

    A reference to an Express customer with basic identifying information

    - `required string ExpressCustomerID`

      Unique Express customer identifier. Format: cus_{32-hex-chars}

    - `required string ExpressCustomerName`

      Name of the Express customer

  - `IReadOnlyDictionary<string, string> Metadata`

    Custom key-value metadata for the study. Maximum 50 pairs, keys up to 100 chars, values up to 1000 chars

### Example

```csharp
StudyCreateParams parameters = new()
{
    Severity = Severity.High,
    StudyDescription = "CT Chest/Abdomen/Pelvis",
    StudyInstanceUid = "1.2.840.113619.2.55.3.604688119.868.1234567890.123",
};

var study = await client.Viewer.Studies.Create(parameters);

Console.WriteLine(study);
```

## List

`StudyListPageResponse Viewer.Studies.List(StudyListParams?parameters, CancellationTokencancellationToken = default)`

**get** `/v1/viewer/studies`

Retrieves a paginated list of studies with optional filtering by assignment, severity, description, cancellation status, and viewer status. Returns up to 100 studies per request.

### Parameters

- `StudyListParams parameters`

  - `string? assignedTo`

    Filter by assigned user ID (null = explicitly unassigned). Format: usr_<32-hex-chars>

  - `string cursor`

    Base64 encoded cursor from previous response

  - `string? expressCustomerID`

    Filter by Express customer ID (null = studies with no customer). Format: cus_{32-hex-chars}

  - `Boolean? isCancelled`

    Filter by cancellation status

  - `Double limit`

    Number of results to return (1-100)

  - `Severity severity`

    Filter by study severity

    - `"normal"Normal`

    - `"high"High`

    - `"stat"Stat`

  - `string studyDescription`

    Filter by study description (contains match)

  - `StudyViewerStatus studyViewerStatus`

    Filter by study viewer status

    - `"incomplete"Incomplete`

    - `"complete"Complete`

### Returns

- `class StudyListPageResponse:`

  Paginated list of Viewer studies

  - `required Boolean HasMore`

  - `required IReadOnlyList<StudyListResponse> Studies`

    - `required DateTimeOffset? CancelledAt`

      Timestamp when the study was cancelled, null if not cancelled

    - `required DateTimeOffset? CreatedAt`

      Timestamp when the study was created

    - `required Boolean IsCancelled`

      Whether the study has been cancelled

    - `required Severity Severity`

      Priority level of the study. 'normal' for routine, 'high' for urgent, 'stat' for immediate attention

      - `"normal"Normal`

      - `"high"High`

      - `"stat"Stat`

    - `required string StudyDescription`

      Description of the study/scan (e.g., 'Brain MRI with Contrast', 'Chest CT')

    - `required string StudyID`

      Unique study identifier. Format: stu_{32-hex-chars}

    - `required string StudyInstanceUid`

      DICOM Study Instance UID. Must be a valid DICOM UID format (e.g., '1.2.840.10008.5.1.4.1.1.2')

    - `required StudyViewerStatus StudyViewerStatus`

      - `"incomplete"Incomplete`

      - `"complete"Complete`

    - `required DateTimeOffset? UpdatedAt`

      Timestamp when the study was last updated

    - `UserReference? AssignedTo`

      A reference to a user with basic identifying information

      - `required string Email`

        User's email address

      - `required string UserID`

        Unique user identifier. Format: usr_{32-hex-chars}

      - `string FirstName`

        User's first name

      - `string LastName`

        User's last name

      - `string MiddleName`

        User's middle name

      - `string Suffix1`

        Name suffix (e.g., 'MD', 'Jr.')

      - `string Suffix2`

        Additional name suffix

    - `ApiKeyReference? CreatedByApiKey`

      A reference to an API key with basic identifying information

      - `required string ApiKeyID`

        Unique API key identifier (UUIDv4 format)

      - `required string Description`

        Human-readable description of the API key

      - `Boolean IsViewerEnabled`

        Whether this API key has access to the Viewer product

    - `UserReference? CreatedByUser`

      A reference to a user with basic identifying information

      - `required string Email`

        User's email address

      - `required string UserID`

        Unique user identifier. Format: usr_{32-hex-chars}

      - `string FirstName`

        User's first name

      - `string LastName`

        User's last name

      - `string MiddleName`

        User's middle name

      - `string Suffix1`

        Name suffix (e.g., 'MD', 'Jr.')

      - `string Suffix2`

        Additional name suffix

    - `ExpressCustomerReference? ExpressCustomer`

      A reference to an Express customer with basic identifying information

      - `required string ExpressCustomerID`

        Unique Express customer identifier. Format: cus_{32-hex-chars}

      - `required string ExpressCustomerName`

        Name of the Express customer

    - `IReadOnlyDictionary<string, string> Metadata`

      Custom key-value metadata for the study. Maximum 50 pairs, keys up to 100 chars, values up to 1000 chars

  - `string Cursor`

### Example

```csharp
StudyListParams parameters = new();

var page = await client.Viewer.Studies.List(parameters);
await foreach (var item in page.Paginate())
{
    Console.WriteLine(item);
}
```

## Retrieve

`StudyRetrieveResponse Viewer.Studies.Retrieve(StudyRetrieveParamsparameters, CancellationTokencancellationToken = default)`

**get** `/v1/viewer/studies/{studyId}`

Retrieves a single study by its unique study ID. Returns the complete study object with all metadata and status information.

### Parameters

- `StudyRetrieveParams parameters`

  - `required string studyID`

    Unique study identifier. Format: stu_{32-hex-chars}

### Returns

- `class StudyRetrieveResponse:`

  A study entity in the Viewer system with viewing status

  - `required DateTimeOffset? CancelledAt`

    Timestamp when the study was cancelled, null if not cancelled

  - `required DateTimeOffset? CreatedAt`

    Timestamp when the study was created

  - `required Boolean IsCancelled`

    Whether the study has been cancelled

  - `required Severity Severity`

    Priority level of the study. 'normal' for routine, 'high' for urgent, 'stat' for immediate attention

    - `"normal"Normal`

    - `"high"High`

    - `"stat"Stat`

  - `required string StudyDescription`

    Description of the study/scan (e.g., 'Brain MRI with Contrast', 'Chest CT')

  - `required string StudyID`

    Unique study identifier. Format: stu_{32-hex-chars}

  - `required string StudyInstanceUid`

    DICOM Study Instance UID. Must be a valid DICOM UID format (e.g., '1.2.840.10008.5.1.4.1.1.2')

  - `required StudyViewerStatus StudyViewerStatus`

    - `"incomplete"Incomplete`

    - `"complete"Complete`

  - `required DateTimeOffset? UpdatedAt`

    Timestamp when the study was last updated

  - `UserReference? AssignedTo`

    A reference to a user with basic identifying information

    - `required string Email`

      User's email address

    - `required string UserID`

      Unique user identifier. Format: usr_{32-hex-chars}

    - `string FirstName`

      User's first name

    - `string LastName`

      User's last name

    - `string MiddleName`

      User's middle name

    - `string Suffix1`

      Name suffix (e.g., 'MD', 'Jr.')

    - `string Suffix2`

      Additional name suffix

  - `ApiKeyReference? CreatedByApiKey`

    A reference to an API key with basic identifying information

    - `required string ApiKeyID`

      Unique API key identifier (UUIDv4 format)

    - `required string Description`

      Human-readable description of the API key

    - `Boolean IsViewerEnabled`

      Whether this API key has access to the Viewer product

  - `UserReference? CreatedByUser`

    A reference to a user with basic identifying information

    - `required string Email`

      User's email address

    - `required string UserID`

      Unique user identifier. Format: usr_{32-hex-chars}

    - `string FirstName`

      User's first name

    - `string LastName`

      User's last name

    - `string MiddleName`

      User's middle name

    - `string Suffix1`

      Name suffix (e.g., 'MD', 'Jr.')

    - `string Suffix2`

      Additional name suffix

  - `ExpressCustomerReference? ExpressCustomer`

    A reference to an Express customer with basic identifying information

    - `required string ExpressCustomerID`

      Unique Express customer identifier. Format: cus_{32-hex-chars}

    - `required string ExpressCustomerName`

      Name of the Express customer

  - `IReadOnlyDictionary<string, string> Metadata`

    Custom key-value metadata for the study. Maximum 50 pairs, keys up to 100 chars, values up to 1000 chars

### Example

```csharp
StudyRetrieveParams parameters = new()
{
    StudyID = "stu_1234567890abcdef1234567890abcdef"
};

var study = await client.Viewer.Studies.Retrieve(parameters);

Console.WriteLine(study);
```

## Update

`StudyUpdateResponse Viewer.Studies.Update(StudyUpdateParamsparameters, CancellationTokencancellationToken = default)`

**patch** `/v1/viewer/studies/{studyId}`

Updates a study's properties including description, severity, assignment, organization, and metadata. All fields are optional - only provided fields will be updated.

### Parameters

- `StudyUpdateParams parameters`

  - `required string studyID`

    Unique study identifier. Format: stu_{32-hex-chars}

  - `string assignedTo`

    User ID to assign the study to, or null to unassign. Format: usr_{32-hex-chars}

  - `IReadOnlyDictionary<string, string>? metadata`

  - `Severity severity`

    Priority level of the study. 'normal' for routine, 'high' for urgent, 'stat' for immediate attention

    - `"normal"Normal`

    - `"high"High`

    - `"stat"Stat`

  - `string studyDescription`

    Description of the study/scan (e.g., 'Brain MRI with Contrast', 'Chest CT')

  - `StudyViewerStatus studyViewerStatus`

    - `"incomplete"Incomplete`

    - `"complete"Complete`

### Returns

- `class StudyUpdateResponse:`

  A study entity in the Viewer system with viewing status

  - `required DateTimeOffset? CancelledAt`

    Timestamp when the study was cancelled, null if not cancelled

  - `required DateTimeOffset? CreatedAt`

    Timestamp when the study was created

  - `required Boolean IsCancelled`

    Whether the study has been cancelled

  - `required Severity Severity`

    Priority level of the study. 'normal' for routine, 'high' for urgent, 'stat' for immediate attention

    - `"normal"Normal`

    - `"high"High`

    - `"stat"Stat`

  - `required string StudyDescription`

    Description of the study/scan (e.g., 'Brain MRI with Contrast', 'Chest CT')

  - `required string StudyID`

    Unique study identifier. Format: stu_{32-hex-chars}

  - `required string StudyInstanceUid`

    DICOM Study Instance UID. Must be a valid DICOM UID format (e.g., '1.2.840.10008.5.1.4.1.1.2')

  - `required StudyViewerStatus StudyViewerStatus`

    - `"incomplete"Incomplete`

    - `"complete"Complete`

  - `required DateTimeOffset? UpdatedAt`

    Timestamp when the study was last updated

  - `UserReference? AssignedTo`

    A reference to a user with basic identifying information

    - `required string Email`

      User's email address

    - `required string UserID`

      Unique user identifier. Format: usr_{32-hex-chars}

    - `string FirstName`

      User's first name

    - `string LastName`

      User's last name

    - `string MiddleName`

      User's middle name

    - `string Suffix1`

      Name suffix (e.g., 'MD', 'Jr.')

    - `string Suffix2`

      Additional name suffix

  - `ApiKeyReference? CreatedByApiKey`

    A reference to an API key with basic identifying information

    - `required string ApiKeyID`

      Unique API key identifier (UUIDv4 format)

    - `required string Description`

      Human-readable description of the API key

    - `Boolean IsViewerEnabled`

      Whether this API key has access to the Viewer product

  - `UserReference? CreatedByUser`

    A reference to a user with basic identifying information

    - `required string Email`

      User's email address

    - `required string UserID`

      Unique user identifier. Format: usr_{32-hex-chars}

    - `string FirstName`

      User's first name

    - `string LastName`

      User's last name

    - `string MiddleName`

      User's middle name

    - `string Suffix1`

      Name suffix (e.g., 'MD', 'Jr.')

    - `string Suffix2`

      Additional name suffix

  - `ExpressCustomerReference? ExpressCustomer`

    A reference to an Express customer with basic identifying information

    - `required string ExpressCustomerID`

      Unique Express customer identifier. Format: cus_{32-hex-chars}

    - `required string ExpressCustomerName`

      Name of the Express customer

  - `IReadOnlyDictionary<string, string> Metadata`

    Custom key-value metadata for the study. Maximum 50 pairs, keys up to 100 chars, values up to 1000 chars

### Example

```csharp
StudyUpdateParams parameters = new()
{
    StudyID = "stu_1234567890abcdef1234567890abcdef"
};

var study = await client.Viewer.Studies.Update(parameters);

Console.WriteLine(study);
```

## Cancel

`StudyCancelResponse Viewer.Studies.Cancel(StudyCancelParams?parameters, CancellationTokencancellationToken = default)`

**post** `/v1/viewer/studies/cancel`

Marks a study as cancelled. Cancelled studies are preserved but flagged as inactive. Can be identified by either study ID or DICOM Study Instance UID.

### Parameters

- `StudyCancelParams parameters`

  - `string studyID`

    Unique study identifier. Format: stu_{32-hex-chars}

  - `string studyInstanceUid`

    DICOM Study Instance UID. Must be a valid DICOM UID format (e.g., '1.2.840.10008.5.1.4.1.1.2')

### Returns

- `class StudyCancelResponse:`

  Response for cancelling a study in Viewer

  - `required Boolean Success`

  - `string Message`

### Example

```csharp
StudyCancelParams parameters = new();

var response = await client.Viewer.Studies.Cancel(parameters);

Console.WriteLine(response);
```

## Uncancel

`StudyUncancelResponse Viewer.Studies.Uncancel(StudyUncancelParams?parameters, CancellationTokencancellationToken = default)`

**post** `/v1/viewer/studies/uncancel`

Restores a cancelled study to active status. The study must have been previously cancelled. Can be identified by either study ID or DICOM Study Instance UID.

### Parameters

- `StudyUncancelParams parameters`

  - `string studyID`

    Unique study identifier. Format: stu_{32-hex-chars}

  - `string studyInstanceUid`

    DICOM Study Instance UID. Must be a valid DICOM UID format (e.g., '1.2.840.10008.5.1.4.1.1.2')

### Returns

- `class StudyUncancelResponse:`

  Response for uncancelling a study in Viewer

  - `required Boolean Success`

  - `string Message`

### Example

```csharp
StudyUncancelParams parameters = new();

var response = await client.Viewer.Studies.Uncancel(parameters);

Console.WriteLine(response);
```

## Reroute URL

`StudyRerouteUrlResponse Viewer.Studies.RerouteUrl(StudyRerouteUrlParams?parameters, CancellationTokencancellationToken = default)`

**post** `/v1/viewer/studies/reroute-url`

Generates a tokenized URL that redirects users directly to the Avara Viewer for the specified study. The URL includes authentication and is time-limited for security.

### Parameters

- `StudyRerouteUrlParams parameters`

  - `string studyID`

    Unique study identifier. Format: stu_{32-hex-chars}

  - `string studyInstanceUid`

    DICOM Study Instance UID. Must be a valid DICOM UID format (e.g., '1.2.840.10008.5.1.4.1.1.2')

### Returns

- `class StudyRerouteUrlResponse:`

  Response containing the generated reroute URL for a study in Viewer

  - `required string Url`

### Example

```csharp
StudyRerouteUrlParams parameters = new();

var response = await client.Viewer.Studies.RerouteUrl(parameters);

Console.WriteLine(response);
```

## Retrieve By Uid

`StudyRetrieveByUidResponse Viewer.Studies.RetrieveByUid(StudyRetrieveByUidParamsparameters, CancellationTokencancellationToken = default)`

**get** `/v1/viewer/studies/by-uid/{studyInstanceUid}`

Retrieves a single study by its DICOM Study Instance UID. This is useful when you have the DICOM UID but not the Avara study ID.

### Parameters

- `StudyRetrieveByUidParams parameters`

  - `required string studyInstanceUid`

    DICOM Study Instance UID. Format: numbers and dots (e.g., 1.2.840.10008.5.1.4.1.1.2).

### Returns

- `class StudyRetrieveByUidResponse:`

  A study entity in the Viewer system with viewing status

  - `required DateTimeOffset? CancelledAt`

    Timestamp when the study was cancelled, null if not cancelled

  - `required DateTimeOffset? CreatedAt`

    Timestamp when the study was created

  - `required Boolean IsCancelled`

    Whether the study has been cancelled

  - `required Severity Severity`

    Priority level of the study. 'normal' for routine, 'high' for urgent, 'stat' for immediate attention

    - `"normal"Normal`

    - `"high"High`

    - `"stat"Stat`

  - `required string StudyDescription`

    Description of the study/scan (e.g., 'Brain MRI with Contrast', 'Chest CT')

  - `required string StudyID`

    Unique study identifier. Format: stu_{32-hex-chars}

  - `required string StudyInstanceUid`

    DICOM Study Instance UID. Must be a valid DICOM UID format (e.g., '1.2.840.10008.5.1.4.1.1.2')

  - `required StudyViewerStatus StudyViewerStatus`

    - `"incomplete"Incomplete`

    - `"complete"Complete`

  - `required DateTimeOffset? UpdatedAt`

    Timestamp when the study was last updated

  - `UserReference? AssignedTo`

    A reference to a user with basic identifying information

    - `required string Email`

      User's email address

    - `required string UserID`

      Unique user identifier. Format: usr_{32-hex-chars}

    - `string FirstName`

      User's first name

    - `string LastName`

      User's last name

    - `string MiddleName`

      User's middle name

    - `string Suffix1`

      Name suffix (e.g., 'MD', 'Jr.')

    - `string Suffix2`

      Additional name suffix

  - `ApiKeyReference? CreatedByApiKey`

    A reference to an API key with basic identifying information

    - `required string ApiKeyID`

      Unique API key identifier (UUIDv4 format)

    - `required string Description`

      Human-readable description of the API key

    - `Boolean IsViewerEnabled`

      Whether this API key has access to the Viewer product

  - `UserReference? CreatedByUser`

    A reference to a user with basic identifying information

    - `required string Email`

      User's email address

    - `required string UserID`

      Unique user identifier. Format: usr_{32-hex-chars}

    - `string FirstName`

      User's first name

    - `string LastName`

      User's last name

    - `string MiddleName`

      User's middle name

    - `string Suffix1`

      Name suffix (e.g., 'MD', 'Jr.')

    - `string Suffix2`

      Additional name suffix

  - `ExpressCustomerReference? ExpressCustomer`

    A reference to an Express customer with basic identifying information

    - `required string ExpressCustomerID`

      Unique Express customer identifier. Format: cus_{32-hex-chars}

    - `required string ExpressCustomerName`

      Name of the Express customer

  - `IReadOnlyDictionary<string, string> Metadata`

    Custom key-value metadata for the study. Maximum 50 pairs, keys up to 100 chars, values up to 1000 chars

### Example

```csharp
StudyRetrieveByUidParams parameters = new()
{
    StudyInstanceUid = "1.2.840.10008.5.1.4.1.1.2"
};

var response = await client.Viewer.Studies.RetrieveByUid(parameters);

Console.WriteLine(response);
```