# Studies ## Create `client.viewer.studies.create(StudyCreateParamsbody, RequestOptionsoptions?): StudyCreateResponse` **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 - `body: StudyCreateParams` - `severity: "normal" | "high" | "stat"` Priority level of the study. 'normal' for routine, 'high' for urgent, 'stat' for immediate attention - `"normal"` - `"high"` - `"stat"` - `studyDescription: string` Description of the study/scan (e.g., 'Brain MRI with Contrast', 'Chest CT') - `studyInstanceUid: string` DICOM Study Instance UID. Must be a valid DICOM UID format (e.g., '1.2.840.10008.5.1.4.1.1.2') - `assignedTo?: string` User ID to assign the study to. Format: usr_{32-hex-chars} - `expressCustomerId?: string` Express customer ID for the study. Format: cus_{32-hex-chars} - `metadata?: Record` Custom key-value metadata for the study. Maximum 50 pairs, keys up to 100 chars, values up to 1000 chars ### Returns - `StudyCreateResponse` A study entity in the Viewer system with viewing status - `cancelledAt: string | null` Timestamp when the study was cancelled, null if not cancelled - `createdAt: string | null` Timestamp when the study was created - `isCancelled: boolean` Whether the study has been cancelled - `severity: "normal" | "high" | "stat"` Priority level of the study. 'normal' for routine, 'high' for urgent, 'stat' for immediate attention - `"normal"` - `"high"` - `"stat"` - `studyDescription: string` Description of the study/scan (e.g., 'Brain MRI with Contrast', 'Chest CT') - `studyId: string` Unique study identifier. Format: stu_{32-hex-chars} - `studyInstanceUid: string` DICOM Study Instance UID. Must be a valid DICOM UID format (e.g., '1.2.840.10008.5.1.4.1.1.2') - `studyViewerStatus: "incomplete" | "complete"` - `"incomplete"` - `"complete"` - `updatedAt: string | null` Timestamp when the study was last updated - `assignedTo?: UserReference | null` A reference to a user with basic identifying information - `email: string` User's email address - `userId: string` Unique user identifier. Format: usr_{32-hex-chars} - `firstName?: string` User's first name - `lastName?: string` User's last name - `middleName?: string` User's middle name - `suffix1?: string` Name suffix (e.g., 'MD', 'Jr.') - `suffix2?: string` Additional name suffix - `createdByApiKey?: APIKeyReference | null` A reference to an API key with basic identifying information - `apiKeyId: string` Unique API key identifier (UUIDv4 format) - `description: string` Human-readable description of the API key - `isViewerEnabled?: boolean` Whether this API key has access to the Viewer product - `createdByUser?: UserReference | null` A reference to a user with basic identifying information - `email: string` User's email address - `userId: string` Unique user identifier. Format: usr_{32-hex-chars} - `firstName?: string` User's first name - `lastName?: string` User's last name - `middleName?: string` User's middle name - `suffix1?: string` Name suffix (e.g., 'MD', 'Jr.') - `suffix2?: string` Additional name suffix - `expressCustomer?: ExpressCustomerReference | null` A reference to an Express customer with basic identifying information - `expressCustomerId: string` Unique Express customer identifier. Format: cus_{32-hex-chars} - `expressCustomerName: string` Name of the Express customer - `metadata?: Record` Custom key-value metadata for the study. Maximum 50 pairs, keys up to 100 chars, values up to 1000 chars ### Example ```typescript import Avara from 'avara'; const client = new Avara({ apiKey: process.env['AVARA_API_KEY'], // This is the default and can be omitted }); const study = await client.viewer.studies.create({ severity: 'high', studyDescription: 'CT Chest/Abdomen/Pelvis', studyInstanceUid: '1.2.840.113619.2.55.3.604688119.868.1234567890.123', }); console.log(study.studyInstanceUid); ``` ## List `client.viewer.studies.list(StudyListParamsquery?, RequestOptionsoptions?): CursorStudies` **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 - `query: StudyListParams` - `assignedTo?: string | null` Filter by assigned user ID (null = explicitly unassigned). Format: usr_<32-hex-chars> - `cursor?: string` Base64 encoded cursor from previous response - `expressCustomerId?: string | null` Filter by Express customer ID (null = studies with no customer). Format: cus_{32-hex-chars} - `isCancelled?: boolean | null` Filter by cancellation status - `limit?: number` Number of results to return (1-100) - `severity?: "normal" | "high" | "stat"` Filter by study severity - `"normal"` - `"high"` - `"stat"` - `studyDescription?: string` Filter by study description (contains match) - `studyViewerStatus?: "incomplete" | "complete"` Filter by study viewer status - `"incomplete"` - `"complete"` ### Returns - `StudyListResponse` A study entity in the Viewer system with viewing status - `cancelledAt: string | null` Timestamp when the study was cancelled, null if not cancelled - `createdAt: string | null` Timestamp when the study was created - `isCancelled: boolean` Whether the study has been cancelled - `severity: "normal" | "high" | "stat"` Priority level of the study. 'normal' for routine, 'high' for urgent, 'stat' for immediate attention - `"normal"` - `"high"` - `"stat"` - `studyDescription: string` Description of the study/scan (e.g., 'Brain MRI with Contrast', 'Chest CT') - `studyId: string` Unique study identifier. Format: stu_{32-hex-chars} - `studyInstanceUid: string` DICOM Study Instance UID. Must be a valid DICOM UID format (e.g., '1.2.840.10008.5.1.4.1.1.2') - `studyViewerStatus: "incomplete" | "complete"` - `"incomplete"` - `"complete"` - `updatedAt: string | null` Timestamp when the study was last updated - `assignedTo?: UserReference | null` A reference to a user with basic identifying information - `email: string` User's email address - `userId: string` Unique user identifier. Format: usr_{32-hex-chars} - `firstName?: string` User's first name - `lastName?: string` User's last name - `middleName?: string` User's middle name - `suffix1?: string` Name suffix (e.g., 'MD', 'Jr.') - `suffix2?: string` Additional name suffix - `createdByApiKey?: APIKeyReference | null` A reference to an API key with basic identifying information - `apiKeyId: string` Unique API key identifier (UUIDv4 format) - `description: string` Human-readable description of the API key - `isViewerEnabled?: boolean` Whether this API key has access to the Viewer product - `createdByUser?: UserReference | null` A reference to a user with basic identifying information - `email: string` User's email address - `userId: string` Unique user identifier. Format: usr_{32-hex-chars} - `firstName?: string` User's first name - `lastName?: string` User's last name - `middleName?: string` User's middle name - `suffix1?: string` Name suffix (e.g., 'MD', 'Jr.') - `suffix2?: string` Additional name suffix - `expressCustomer?: ExpressCustomerReference | null` A reference to an Express customer with basic identifying information - `expressCustomerId: string` Unique Express customer identifier. Format: cus_{32-hex-chars} - `expressCustomerName: string` Name of the Express customer - `metadata?: Record` Custom key-value metadata for the study. Maximum 50 pairs, keys up to 100 chars, values up to 1000 chars ### Example ```typescript import Avara from 'avara'; const client = new Avara({ apiKey: process.env['AVARA_API_KEY'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const studyListResponse of client.viewer.studies.list()) { console.log(studyListResponse.studyInstanceUid); } ``` ## Retrieve `client.viewer.studies.retrieve(stringstudyID, RequestOptionsoptions?): StudyRetrieveResponse` **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 - `studyID: string` Unique study identifier. Format: stu_{32-hex-chars} ### Returns - `StudyRetrieveResponse` A study entity in the Viewer system with viewing status - `cancelledAt: string | null` Timestamp when the study was cancelled, null if not cancelled - `createdAt: string | null` Timestamp when the study was created - `isCancelled: boolean` Whether the study has been cancelled - `severity: "normal" | "high" | "stat"` Priority level of the study. 'normal' for routine, 'high' for urgent, 'stat' for immediate attention - `"normal"` - `"high"` - `"stat"` - `studyDescription: string` Description of the study/scan (e.g., 'Brain MRI with Contrast', 'Chest CT') - `studyId: string` Unique study identifier. Format: stu_{32-hex-chars} - `studyInstanceUid: string` DICOM Study Instance UID. Must be a valid DICOM UID format (e.g., '1.2.840.10008.5.1.4.1.1.2') - `studyViewerStatus: "incomplete" | "complete"` - `"incomplete"` - `"complete"` - `updatedAt: string | null` Timestamp when the study was last updated - `assignedTo?: UserReference | null` A reference to a user with basic identifying information - `email: string` User's email address - `userId: string` Unique user identifier. Format: usr_{32-hex-chars} - `firstName?: string` User's first name - `lastName?: string` User's last name - `middleName?: string` User's middle name - `suffix1?: string` Name suffix (e.g., 'MD', 'Jr.') - `suffix2?: string` Additional name suffix - `createdByApiKey?: APIKeyReference | null` A reference to an API key with basic identifying information - `apiKeyId: string` Unique API key identifier (UUIDv4 format) - `description: string` Human-readable description of the API key - `isViewerEnabled?: boolean` Whether this API key has access to the Viewer product - `createdByUser?: UserReference | null` A reference to a user with basic identifying information - `email: string` User's email address - `userId: string` Unique user identifier. Format: usr_{32-hex-chars} - `firstName?: string` User's first name - `lastName?: string` User's last name - `middleName?: string` User's middle name - `suffix1?: string` Name suffix (e.g., 'MD', 'Jr.') - `suffix2?: string` Additional name suffix - `expressCustomer?: ExpressCustomerReference | null` A reference to an Express customer with basic identifying information - `expressCustomerId: string` Unique Express customer identifier. Format: cus_{32-hex-chars} - `expressCustomerName: string` Name of the Express customer - `metadata?: Record` Custom key-value metadata for the study. Maximum 50 pairs, keys up to 100 chars, values up to 1000 chars ### Example ```typescript import Avara from 'avara'; const client = new Avara({ apiKey: process.env['AVARA_API_KEY'], // This is the default and can be omitted }); const study = await client.viewer.studies.retrieve('stu_1234567890abcdef1234567890abcdef'); console.log(study.studyInstanceUid); ``` ## Update `client.viewer.studies.update(stringstudyID, StudyUpdateParamsbody?, RequestOptionsoptions?): StudyUpdateResponse` **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 - `studyID: string` Unique study identifier. Format: stu_{32-hex-chars} - `body: StudyUpdateParams` - `assignedTo?: string` User ID to assign the study to, or null to unassign. Format: usr_{32-hex-chars} - `metadata?: Record | null` - `severity?: "normal" | "high" | "stat"` Priority level of the study. 'normal' for routine, 'high' for urgent, 'stat' for immediate attention - `"normal"` - `"high"` - `"stat"` - `studyDescription?: string` Description of the study/scan (e.g., 'Brain MRI with Contrast', 'Chest CT') - `studyViewerStatus?: "incomplete" | "complete"` - `"incomplete"` - `"complete"` ### Returns - `StudyUpdateResponse` A study entity in the Viewer system with viewing status - `cancelledAt: string | null` Timestamp when the study was cancelled, null if not cancelled - `createdAt: string | null` Timestamp when the study was created - `isCancelled: boolean` Whether the study has been cancelled - `severity: "normal" | "high" | "stat"` Priority level of the study. 'normal' for routine, 'high' for urgent, 'stat' for immediate attention - `"normal"` - `"high"` - `"stat"` - `studyDescription: string` Description of the study/scan (e.g., 'Brain MRI with Contrast', 'Chest CT') - `studyId: string` Unique study identifier. Format: stu_{32-hex-chars} - `studyInstanceUid: string` DICOM Study Instance UID. Must be a valid DICOM UID format (e.g., '1.2.840.10008.5.1.4.1.1.2') - `studyViewerStatus: "incomplete" | "complete"` - `"incomplete"` - `"complete"` - `updatedAt: string | null` Timestamp when the study was last updated - `assignedTo?: UserReference | null` A reference to a user with basic identifying information - `email: string` User's email address - `userId: string` Unique user identifier. Format: usr_{32-hex-chars} - `firstName?: string` User's first name - `lastName?: string` User's last name - `middleName?: string` User's middle name - `suffix1?: string` Name suffix (e.g., 'MD', 'Jr.') - `suffix2?: string` Additional name suffix - `createdByApiKey?: APIKeyReference | null` A reference to an API key with basic identifying information - `apiKeyId: string` Unique API key identifier (UUIDv4 format) - `description: string` Human-readable description of the API key - `isViewerEnabled?: boolean` Whether this API key has access to the Viewer product - `createdByUser?: UserReference | null` A reference to a user with basic identifying information - `email: string` User's email address - `userId: string` Unique user identifier. Format: usr_{32-hex-chars} - `firstName?: string` User's first name - `lastName?: string` User's last name - `middleName?: string` User's middle name - `suffix1?: string` Name suffix (e.g., 'MD', 'Jr.') - `suffix2?: string` Additional name suffix - `expressCustomer?: ExpressCustomerReference | null` A reference to an Express customer with basic identifying information - `expressCustomerId: string` Unique Express customer identifier. Format: cus_{32-hex-chars} - `expressCustomerName: string` Name of the Express customer - `metadata?: Record` Custom key-value metadata for the study. Maximum 50 pairs, keys up to 100 chars, values up to 1000 chars ### Example ```typescript import Avara from 'avara'; const client = new Avara({ apiKey: process.env['AVARA_API_KEY'], // This is the default and can be omitted }); const study = await client.viewer.studies.update('stu_1234567890abcdef1234567890abcdef'); console.log(study.studyInstanceUid); ``` ## Cancel `client.viewer.studies.cancel(StudyCancelParamsbody?, RequestOptionsoptions?): StudyCancelResponse` **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 - `body: StudyCancelParams` - `studyId?: string` Unique study identifier. Format: stu_{32-hex-chars} - `studyInstanceUid?: string` DICOM Study Instance UID. Must be a valid DICOM UID format (e.g., '1.2.840.10008.5.1.4.1.1.2') ### Returns - `StudyCancelResponse` Response for cancelling a study in Viewer - `success: boolean` - `message?: string` ### Example ```typescript import Avara from 'avara'; const client = new Avara({ apiKey: process.env['AVARA_API_KEY'], // This is the default and can be omitted }); const response = await client.viewer.studies.cancel(); console.log(response.success); ``` ## Uncancel `client.viewer.studies.uncancel(StudyUncancelParamsbody?, RequestOptionsoptions?): StudyUncancelResponse` **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 - `body: StudyUncancelParams` - `studyId?: string` Unique study identifier. Format: stu_{32-hex-chars} - `studyInstanceUid?: string` DICOM Study Instance UID. Must be a valid DICOM UID format (e.g., '1.2.840.10008.5.1.4.1.1.2') ### Returns - `StudyUncancelResponse` Response for uncancelling a study in Viewer - `success: boolean` - `message?: string` ### Example ```typescript import Avara from 'avara'; const client = new Avara({ apiKey: process.env['AVARA_API_KEY'], // This is the default and can be omitted }); const response = await client.viewer.studies.uncancel(); console.log(response.success); ``` ## Reroute URL `client.viewer.studies.rerouteURL(StudyRerouteURLParamsbody?, RequestOptionsoptions?): StudyRerouteURLResponse` **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 - `body: StudyRerouteURLParams` - `studyId?: string` Unique study identifier. Format: stu_{32-hex-chars} - `studyInstanceUid?: string` DICOM Study Instance UID. Must be a valid DICOM UID format (e.g., '1.2.840.10008.5.1.4.1.1.2') ### Returns - `StudyRerouteURLResponse` Response containing the generated reroute URL for a study in Viewer - `url: string` ### Example ```typescript import Avara from 'avara'; const client = new Avara({ apiKey: process.env['AVARA_API_KEY'], // This is the default and can be omitted }); const response = await client.viewer.studies.rerouteURL(); console.log(response.url); ``` ## Retrieve By Uid `client.viewer.studies.retrieveByUid(stringstudyInstanceUid, RequestOptionsoptions?): StudyRetrieveByUidResponse` **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 - `studyInstanceUid: string` DICOM Study Instance UID. Format: numbers and dots (e.g., 1.2.840.10008.5.1.4.1.1.2). ### Returns - `StudyRetrieveByUidResponse` A study entity in the Viewer system with viewing status - `cancelledAt: string | null` Timestamp when the study was cancelled, null if not cancelled - `createdAt: string | null` Timestamp when the study was created - `isCancelled: boolean` Whether the study has been cancelled - `severity: "normal" | "high" | "stat"` Priority level of the study. 'normal' for routine, 'high' for urgent, 'stat' for immediate attention - `"normal"` - `"high"` - `"stat"` - `studyDescription: string` Description of the study/scan (e.g., 'Brain MRI with Contrast', 'Chest CT') - `studyId: string` Unique study identifier. Format: stu_{32-hex-chars} - `studyInstanceUid: string` DICOM Study Instance UID. Must be a valid DICOM UID format (e.g., '1.2.840.10008.5.1.4.1.1.2') - `studyViewerStatus: "incomplete" | "complete"` - `"incomplete"` - `"complete"` - `updatedAt: string | null` Timestamp when the study was last updated - `assignedTo?: UserReference | null` A reference to a user with basic identifying information - `email: string` User's email address - `userId: string` Unique user identifier. Format: usr_{32-hex-chars} - `firstName?: string` User's first name - `lastName?: string` User's last name - `middleName?: string` User's middle name - `suffix1?: string` Name suffix (e.g., 'MD', 'Jr.') - `suffix2?: string` Additional name suffix - `createdByApiKey?: APIKeyReference | null` A reference to an API key with basic identifying information - `apiKeyId: string` Unique API key identifier (UUIDv4 format) - `description: string` Human-readable description of the API key - `isViewerEnabled?: boolean` Whether this API key has access to the Viewer product - `createdByUser?: UserReference | null` A reference to a user with basic identifying information - `email: string` User's email address - `userId: string` Unique user identifier. Format: usr_{32-hex-chars} - `firstName?: string` User's first name - `lastName?: string` User's last name - `middleName?: string` User's middle name - `suffix1?: string` Name suffix (e.g., 'MD', 'Jr.') - `suffix2?: string` Additional name suffix - `expressCustomer?: ExpressCustomerReference | null` A reference to an Express customer with basic identifying information - `expressCustomerId: string` Unique Express customer identifier. Format: cus_{32-hex-chars} - `expressCustomerName: string` Name of the Express customer - `metadata?: Record` Custom key-value metadata for the study. Maximum 50 pairs, keys up to 100 chars, values up to 1000 chars ### Example ```typescript import Avara from 'avara'; const client = new Avara({ apiKey: process.env['AVARA_API_KEY'], // This is the default and can be omitted }); const response = await client.viewer.studies.retrieveByUid('1.2.840.10008.5.1.4.1.1.2'); console.log(response.studyInstanceUid); ```