v3 Storage External API

Table of contents

  1. Introduction
  2. Global information
  3. Permissions
  4. Study commands
  5. Image commands

Introduction

The API is implemented as a REST like interface. A call is made to a URL using either a POST, a GET or DELETE. The URL will return either a HTTP error code, a JSON data structure or a byte stream. All URLs below need to be prefixed with {engine_fqdn}/api/v3/storage.

Global information

Permissions

A role has the following permission flags. The default roles are Admin, User, PHR and Anonymous and have the following settings.

Flag Admin
Value
User
Value
PHR
Value
Anonymous
Value
Description
account_edit 1 0 0 0 Can they add and edit the account
account_view 1 0 0 0 Can they view account information
account_user_view 1 0 0 0 Can they view or list the users in the account
account_user_edit 1 0 0 0 Can they add, edit and remove users from an account
user_edit 0 0 0 0 Can they create and edit users on the grid
destination_view 1 0 0 0 Can they view or list the destinations in the account
destination_edit 1 0 0 0 Can they add, edit and remove destinations from an account
destination_search 0 0 0 0 Can they search a destination
destination_search_mwl 0 0 0 0 Can they run a modality worklist search on a destination
group_view 1 0 0 0 Can they view or list the groups in the account
group_edit 1 0 0 0 Can they add, edit and remove groups from an account
location_view 1 0 0 0 Can they view or list the locations in the account
location_edit 1 0 0 0 Can they add, edit and remove locations from an account
role_view 1 0 0 0 Can they view or list the roles in the account
role_edit 1 0 0 0 Can they add, edit and remove roles from an account
route_view 1 0 0 0 Can they view or list the routes in the account
route_edit 1 0 0 0 Can they add, edit and remove routes from an account
node_view 1 0 0 0 Can they view or list the nodes in the account
node_edit 1 0 0 0 Can they add, edit and remove nodes from an account
study_approve 1 0 1 0 Can they approve or reject shared studies in the account, group, location
study_view 1 1 1 1 Can they view the studies in the account, group, location
study_edit 1 0 1 0 Can they edit the PHI of the study
↳ study_edit_approved 1 1 1 0 Can they edit the PHI of an approved study
↳ study_edit_unapproved 1 1 1 0 Can they edit the PHI of an unapproved study
study_star 1 1 0 0 Can they star studies
study_tag 1 1 0 0 Can they tag studies
study_upload 1 0 0 0 Can they upload a study to the account, group, location
study_upload_validate 0 0 0 0 An upload requires session validation
study_report_detail 1 0 1 0 Can they get the detail report for studies in the account, group, location
study_download 1 0 1 0 Can they download the study
study_download_viewer 1 0 1 0 Can they download the local study viewer
study_download_iso 1 0 1 0 Can they download the study ISO
study_browse 1 1 1 1 Can they view studies in the web viewer
study_push 1 0 0 0 Can they push the study to a destination
study_share 1 0 1 0 Can they share the study
↳ study_share_email 0 0 1 0 Can they share the study via email
↳ study_share_share_code 1 1 1 0 Can they share the study via a share code
↳ study_share_account 1 1 1 0 Can they share the study with accounts
↳ study_share_location 1 1 1 0 Can they share the study with locations
↳ study_share_group 1 1 1 0 Can they share the study with groups
↳ study_share_user 1 1 1 0 Can they share the study with users
↳ study_share_rsna 0 0 0 0 Can they share the study with the RSNA network
study_delete 0 0 1 0 Can they delete a study
study_delete_image 0 0 0 0 Can they delete images and series within a study
study_thin 0 0 0 0 Can they create a thin study
study_report_view 1 1 1 1 Can they view attached reports for a study
study_report_view_approved 1 1 1 1 Can they view attached reports for an approved study
study_report_view_unapproved 0 0 0 0 Can they view attached reports for an unapproved study
study_report_hl7_view 1 1 1 1 Can they view HL7 reports for a study
study_report_hl7_view_approved 1 1 1 1 Can they view HL7 reports for an approved study
study_report_hl7_view_unapproved 0 0 0 0 Can they view HL7 reports for an unapproved study
study_report_upload 1 0 1 0 Can they upload a report to a study
study_report_upload_approved 1 1 1 0 Can they upload a report to an approved study
study_report_upload_unapproved 0 0 0 0 Can they upload a report to an unapproved study
study_report_delete 1 0 1 0 Can they delete a report from a study
study_report_delete_approved 1 1 1 0 Can they delete a report from an approved study
study_report_delete_unapproved 0 0 0 0 Can they delete a report from an unapproved study
study_sync 0 0 0 0 Can they force a study to sync against storage and re-run routing rules
study_status_view 0 0 0 0 Can they view the status of the study
study_status_edit 0 0 0 0 Can they edit the status of the study
study_comment_view 0 0 0 0 Can they view the comments for the study
study_comment_edit 0 0 0 0 Can they edit comments for the study
study_audio_record 0 0 0 0 Can they record an audio report for the study
study_audio_play 0 0 0 0 Can they playback audio reports for the study
study_move 0 0 0 0 Can they move the study to another PHI namespace
study_duplicate 0 0 0 0 Can they duplicate studies to another namespace
study_manual_route 0 0 0 0 Can they manually route a study
study_field_patient_name
study_field_patientid
study_field_study_description
study_field_accession_number
study_field_modality
study_field_referring_physician
study_field_patient_sex
study_field_study_date
study_field_patient_birth_date
study_field_customfield_UUID
F F F F Permission for study fields. Customfields contain the UUID of the customfield. Valid values are.
  • F = Full permissions
  • H = Hidden field
  • O = Read only field
  • R = Required field
audit_view 1 0 1 0 Can they view audit information
analytics_view 1 0 1 0 Can they view analytics information
study_search_require_patient_name 0 0 0 0 Patient name is required for a study search
study_search_require_patient_sex 0 0 0 0 Patient gender is required for a study search
study_search_require_accession_number 0 0 0 0 Accession number is required for a study search
study_search_require_patient_birth_date 0 0 0 0 Patient birth date is required for a study search
study_search_require_patientid 0 0 0 0 MRN is required for a study search
filter_share 1 0 1 0 Can they share filters
customfield_view 1 0 0 0 Can they view or list the customfields in the account
customfield_edit 1 0 0 0 Can they add, edit and remove customfields from an account
case_view 0 0 0 0 Can they view or list the cases in the account
case_edit 0 0 0 0 Can they add, edit and remove cases from an account
patient_view 0 0 0 0 Can they view or list the patients in the account
patient_edit 0 0 0 0 Can they add, edit and remove patients from an account
order_view 0 0 0 0 Can they view or list the orders in the account
order_edit 0 0 0 0 Can they add, edit and remove orders from an account
webhook_view 0 0 0 0 Can they view or list the webhooks in the account
webhook_edit 0 0 0 0 Can they add, edit and remove webhooks from an account
can_proxy_login 0 0 0 0 Can they proxy login for "owned" users in an account
radreport_view 0 0 0 0 Can they view or list the radreports in the account
radreport_edit 0 0 0 0 Can they add, edit and remove radreports from an account
radreport_html_format 0 0 0 0 Can they use HTML formating in radreports
dictionary_view 0 0 0 0 Can they view or list the dictionaries in the account
dictionary_edit 0 0 0 0 Can they add, edit and remove dictionaries from an account
hl7_template_view 0 0 0 0 Can they view or list the HL7 templates in the account
hl7_template_edit 0 0 0 0 Can they add, edit and remove HL7 templates from an account
hl7_transform_view 0 0 0 0 Can they view or list the HL7 transformations in the account
hl7_transform_edit 0 0 0 0 Can they add, edit and remove HL7 transformations from an account
annotation_view 1 1 1 1 Can they view annotations on a study
annotation_view_only_own 0 0 0 0 Can they view only their annotations on a study
annotation_edit 1 1 1 0 Can edit annotations on a study
meeting_view 1 1 1 1 Can they view meetings for a study
meeting_edit 0 0 0 0 Can create and edit meetings for a study
keyimage_view 1 1 1 1 Can they view key images on a study
keyimage_edit 1 1 1 0 Can edit key images on a study
validate_view 0 0 0 0 Can they view or list the validation rules in the account
validate_edit 0 0 0 0 Can they add, edit and remove validation rules from an account
purge_view 0 0 0 0 Can they view or list the purge rules in the account
purge_edit 0 0 0 0 Can they add, edit and remove purge rules from an account
link_direct 1 1 1 1 Can they view and copy the direct link to the study
link_view 0 0 0 0 Can they view or list the links in the account
link_edit 0 0 0 0 Can they add, edit and remove links from an account
link_edit_upload 0 0 0 0 Can they add, edit and remove study upload links from an account
message_view 1 1 1 0 Can they view messages in the namespace
message_edit 1 0 1 0 Can they send messages to the namespace
user_modify_sharecode 1 1 1 0 Can they modify their personal share code
user_modify_defaults 1 1 1 0 Can they modify their personal defaults
user_modify_notifications 1 1 1 0 Can they modify their notifications
user_request_access 1 1 1 0 Can they request access to an org
channel_study 1 1 1 1 Can they subscribe to a study channel
channel_activity 1 1 1 0 Can they subscribe to an activity channel
viewer_config JSON viewer configuration for the role. Optionally pass in the UUID of a user and that users viewer configuration will be copied into the role

Study commands

Description Gets the schema of a study.
URL /study/{namespace}/{studyUid}/schema?sid={sid}&phi_namespace={phi_namespace}&extended={1,0}&attachments_only={0,1}
Parameters sid • The session id (Required).
phi_namespace • A string, set to the UUID of the namespace where the file was attached if it was attached to a shared instance of the study outside of the original storage namespace
extended • is an integer, when set to 1 will include the optional phi_version and transfer_attributes name/value pairs in the response.
attachments_only • is an integer, when set to 1 will only include a list of the attachments in the study.
Returns Study Schema • The study schema in a JSON format representation.
Errors Permission Denied • If the sid is not valid or the user does not have permission to view the study.
Conflict (409) • Returned if an inconsistency is found while recomputing the schema cache. Retry the request after a short delay.
Notes
  1. The call must be GET or HEAD
Python Sample + Code
top

Description Deletes a study.
URL /study/{namespace}/{studyUid}?sid={sid}&keep_attachments={1,0}
Parameters sid • The session id (Required).
keep_attachments • An integer value of 1 or 0.
Returns HTTP CODE • 202 Accepted.
Errors Permission Denied • If the sid is not valid or the user does not have permission to edit the study.
Notes
  1. The call must be DELETE
  2. If the optional parameter keep_attachments is set to 1, then:
      all DICOM images will be deleted.
      reports and attachments related to the study will be kept.
Python Sample + Code
top

Description Deletes a single image from a study (to delete multiple images, use study/delete/images/).
URL /study/{namespace}/{studyUid}/image/{imageUid}?sid={sid}
Parameters sid • The session id (Required).
imageUid • The image version
Returns HTTP CODE • 202 Accepted.
Errors Permission Denied • If the sid is not valid or the user does not have study_delete_image permission for the study.
Image Not Found (404) • If image doesn't exist
Notes
  1. The HTTP method must be DELETE
  2. This method sends a STUDY_DELETE notification to Services after the image is deleted
  3. This method is synchronous - it doesn't return until the image is deleted and Services notification is sent
Python Sample + Code
top

Description Delete multiple images from a study.
URL /study/{namespace}/{studyUid}/images?sid={sid}
Parameters sid • The session id (Required).
request body • Comma-separated list of multiple image UIDs (Required)
Returns HTTP CODE • 202 Accepted.
Errors Permission Denied • If the sid is not valid or the user does not have study_delete_image permission for the study.
Unprocessable Entity (422) • If request body is empty
Study Not Found (404) • If study doesn't exist
Notes
  1. The HTTP method must be DELETE
  2. This method sends one STUDY_DELETE notification to Services after the images are deleted
  3. This method is synchronous - it doesn't return until all images are deleted and Services notification is sent
top

Description Gets study file count.
URL /study/{namespace}/{studyUid}/count?sid={sid}&images_only={1,0}&attachments_only={1,0}&count_files={1,0}
Parameters sid • The session id (Required).
images_only • an integer, zero or 1, returns the number of images in the study with superseded images by way of study update not counted.
attachments_only • an integer, zero or 1, returns the number of attachments which have been added to this study.
count_files • if present and set to 1 will count files stored on-disk for images and/or attachments, instead of counting from (possibly cached) meta data.
Returns Study count • A JSON representation of the study count for attachments and images.
Errors Permission Denied • If the sid is not valid or the user does not have permission to view the study.
Notes
  1. The call must be GET or HEAD.
Python Sample + Code
top

Description Gets study tags.
URL /study/{namespace}/{studyUid}/tag?sid={sid}&phi_namespace={phi_namespace}
Parameters sid • The session id (Required).
phi_namespace • A string, set to the UUID of the namespace where the file was attached if it was attached to a shared instance of the study outside of the original storage namespace
Returns Study PHI tags • A JSON representation of the study PHI tags.
Errors Permission Denied • If the sid is not valid or the user does not have permission to view the study.
Notes
  1. The call must be GET or HEAD.
Python Sample + Code
top

Description Gets study image attributes.
URL /study/{namespace}/{studyUid}/image/{imageUid}/version/{imageVersion}/attribute?sid={sid}&phi_namespace={phi_namespace}
Parameters sid • The session id (Required).
phi_namespace • A string, set to the UUID of the namespace where the file was attached if it was attached to a shared instance of the study outside of the original storage namespace
groups • The groups parameter will allow the client to filter tags to only those in a certain set of top-level DICOM groups. Comma-separated list of decimal values, or hex values preceeded with "0x".
include_tags • Comma-separated list of top-level DICOM tags to include. Format: 00080018,00080020 Nested tags (00081111:00080550) only filter at the top level, everything is included within the sequence
exclude_unnamed • A string containing "1" or "0" (default 0). When "1", private tags (with "name": "?") are not included
Returns Study image attributes • A JSON representation of the image attributes.
HTTP CODE • 404 (NOT FOUND) if the study does not exist.
Errors Permission Denied • If the sid is not valid or the user does not have permission to view the study.
Notes
  1. The call must be GET or HEAD.
Python Sample + Code
top

Description Gets study image PHI.
URL /study/{namespace}/{studyUid}/image/{imageUid}/version/{imageVersion}/phi?sid={sid}&phi_namespace={phi_namespace}
Parameters sid • The session id (Required).
phi_namespace • A string, set to the UUID of the namespace where the file was attached if it was attached to a shared instance of the study outside of the original storage namespace
Returns Study image PHI data • A JSON representation of the image PHI data.
HTTP CODE • 404 (NOT FOUND) if the study does not exist.
Errors Permission Denied • If the sid is not valid or the user does not have permission to view the study.
Notes
  1. The call must be GET or HEAD.
Python Sample + Code
top

Description Gets study PHI data.
URL /study/{namespace}/{studyUid}/phi?sid={sid}&phi_namespace={phi_namespace}
Parameters sid • The session id (Required).
phi_namespace • A string, set to the UUID of the namespace where the file was attached if it was attached to a shared instance of the study outside of the original storage namespace
Returns Study PHI data • A JSON representation of the study PHI data.
HTTP CODE • 404 (NOT FOUND) if the study does not exist.
Errors Permission Denied • If the sid is not valid or the user does not have permission to view the study.
Notes
  1. The call must be GET or HEAD.
Python Sample + Code
top

Description Gets study image thumbnail.
URL /study/{namespace}/{studyUid}/image/{imageUid}/version/{imageVersion}/frame/{frameNumber}/thumbnail?sid={sid}&depth={8,16}&phi_namespace={phi_namespace}
Parameters sid • The session id (Required).
phi_namespace • A string, set to the UUID of the namespace where the file was attached if it was attached to a shared instance of the study outside of the original storage namespace
depth • Set the bit depth of the JPEG output (8 or 16).
Returns Study image thumbnail • A JPEG stream.
HTTP CODE • 404 (NOT FOUND) if the study does not exist.
Errors Permission Denied • If the sid is not valid or the user does not have permission to view the study.
Notes
  1. The call must be GET or HEAD.
Python Sample + Code
top

Description Gets study diagnostic image.
URL /study/{namespace}/{studyUid}/image/{imageUid}/version/{imageVersion}/frame/{frameNumber}/diagnostic?sid={sid}&phi_namespace={phi_namespace}&depth={8,16}&size=[max-edge-length|{width}x{height}]
Parameters sid • The session id (Required).
phi_namespace • A string, set to the UUID of the namespace where the file was attached if it was attached to a shared instance of the study outside of the original storage namespace
depth • Set the bit depth of the JPEG output (8 or 16).
size • Specify size of output. Omitted or 0 indicates no change; one number sets the maximum edge length in pixels; wxh sets maximum width and height
Returns Study image • Gets the selected DICOM frame as a 16-bit diagnostic PNG image formatted for the browser.
Errors Permission Denied • If the sid is not valid or the user does not have permission to view the study.
Notes
  1. The call must be GET or HEAD.
Python Sample + Code
top

Description Gets study image frame.
URL /study/{namespace}/{studyUid}/image/{imageUid}/version/{imageVersion}/frame/{frameNumber:[0-9][0-9]*\..*|[0-9][0-9]*}?sid={sid}&phi_namespace={phi_namespace}&depth={8,16}&quality={0.0-1.0}&size=[max-edge-length|{width}x{height}]
Parameters sid • The session id (Required).
phi_namespace • A string, set to the UUID of the namespace where the file was attached if it was attached to a shared instance of the study outside of the original storage namespace
depth • Set the bit depth of the JPEG output (8 or 16).
quality • Set the JPEG compression quality 0 < q ≤ 1.0 (default 0.9) size • Specify size of output. Omitted or 0 indicates no change; one number sets the maximum edge length in pixels; wxh sets maximum width and height
Returns Study image frame • Gets the selected DICOM frame as a JPEG image. The response body is the actual JPEG byte stream.
HTTP CODE • 404 (NOT FOUND) if the study does not exist.
Errors Permission Denied • If the sid is not valid or the user does not have permission to view the study.
Notes
  1. The call must be GET or HEAD.
Python Sample + Code
top

Description Gets study image frame as a TIFF.
URL /study/{namespace}/{studyUid}/image/{imageUid}/version/{imageVersion}/frame/{frameNumber:[0-9]*}/tiff?sid={sid}&phi_namespace={phi_namespace}&depth={8,16}&size=[max-edge-length|{width}x{height}]
Parameters sid • The session id (Required).
phi_namespace • A string, set to the UUID of the namespace where the file was attached if it was attached to a shared instance of the study outside of the original storage namespace
depth • Set the bit depth of the TIFF output (8 or 16).
size • Specify size of output. Omitted or 0 indicates no change; one number sets the maximum edge length in pixels; wxh sets maximum width and height
Returns Study image frame • Gets the selected DICOM frame as a TIFF image. The response body is the actual TIFF byte stream.
HTTP CODE • 404 (NOT FOUND) if the study does not exist.
Errors Permission Denied • If the sid is not valid or the user does not have permission to view the study.
Notes
  1. The call must be GET or HEAD.
top

Description Gets a study encapsulated pdf file.
URL /study/{namespace}/{studyUid}/image/{imageUid}/version/{imageVersion}/pdf?sid={sid}
Parameters sid • The session id (Required).
Returns Study encapsulated pdf • Gets the encapsulated PDF from a DICOM file.
HTTP CODE • 415 (Unsupported Media Type) if there is not an encapsulated pdf file.
Errors Permission Denied • If the sid is not valid or the user does not have permission to view the study.
Notes
  1. The call must be GET or HEAD.
Python Sample + Code
top

Description Gets all DICOM attributes for an individual image
URL /study/{namespace}/{studyUid}/image/{imageUid}/version/{imageVersion}/json?sid={sid}&phi_namespace={phi_namespace}
Parameters sid • The session id (Required).
phi_namespace • A string, set to the UUID of the namespace where the file was attached if it was attached to a shared instance of the study outside of the original storage namespace
exclude_unnamed • A string containing "1" or "0" (default 0). When "1", private tags (with "name": "?") are not included
all_dicom_values • A string containing "1" or "0" (default 0). When "1", all values from a multi-value DICOM tag will be returned, separated by "\". Otherwise, only the first value is returned
Returns Study image attributes • Gets all DICOM attributes as a JSON object.
HTTP CODE • 404 (NOT FOUND) if there image/frame does not exist.
Errors Permission Denied • If the sid is not valid or the user does not have permission to view the study.
Notes
  1. The call must be GET or HEAD.
Python Sample + Code
top

Description Gets DICOM attributes for all images in a study.
URL /study/{namespace}/{studyUid}/json?sid={sid}&phi_namespace={phi_namespace}&groups={group ids}&include_tags={tags}
Parameters sid • The session id (Required).
phi_namespace • A string, set to the UUID of the namespace where the file was attached if it was attached to a shared instance of the study outside of the original storage namespace
groups • The groups parameter will allow the client to filter tags to only those in a certain set of top-level DICOM groups. Comma-separated list of decimal values, or hex values preceeded with "0x".
include_tags • Comma-separated list of top-level DICOM tags to include. Format: 00080018,00080020 Nested tags (00081111:00080550) only filter at the top level, everything is included within the sequence
exclude_unnamed • A string containing "1" or "0" (default 0). When "1", private tags (with "name": "?") are not included
all_dicom_values • A string containing "1" or "0" (default 0). When "1", all values from a multi-value DICOM tag will be returned, separated by "\". Otherwise, only the first value is returned
series_uid • A string containing a Series Instance UID. If specified, the results will only include DICOM tags from images from the specified series
Returns Study attributes • Gets all DICOM attributes for all images in a study as a JSON array of objects.
HTTP CODE • 404 (NOT FOUND) if there image/frame does not exist.
Errors Permission Denied • If the sid is not valid or the user does not have permission to view the study.
Notes
  1. The call must be GET or HEAD.
Python Sample + Code
top

Description Gets the selected attachment.
URL /study/{namespace}/{studyUid}/attachment/{attachmentId}/version/{version}?sid={sid}&phi_namespace={phi_namespace}
Parameters sid • The session id (Required).
phi_namespace • A string, set to the UUID of the namespace where the file was attached if it was attached to a shared instance of the study outside of the original storage namespace
Returns Study attachment • Gets the attachment as a byte stream.
HTTP CODE • 404 (NOT FOUND) if there image/frame does not exist.
Errors Permission Denied • If the sid is not valid or the user does not have permission to view the study.
Notes
  1. The call must be GET or HEAD.
Python Sample + Code
top

Description Gets the latest attachment for a study.
URL /study/{namespace}/{studyUid}/attachment/{filename:latest\..*|latest}?sid={sid}&phi_namespace={phi_namespace}
Parameters sid • The session id (Required).
phi_namespace • A string, set to the UUID of the namespace where the file was attached if it was attached to a shared instance of the study outside of the original storage namespace
Returns Study latest attachment • Gets the latest attachment as a byte stream.
HTTP CODE • 404 (NOT FOUND) if there image/frame does not exist.
Errors Permission Denied • If the sid is not valid or the user does not have permission to view the study.
Notes
  1. The call must be GET or HEAD.
Python Sample + Code
top

Description Posts an attachment to a study.
URL /study/{namespace}/{studyUid}/attachment?sid={sid}&phi_namespace={phi_namespace}&wrap_images={0,1}&return_html={0,1}&synchronous_wrap={0,1}&static_ids={0,1}
Parameters sid • The session id (Required).
phi_namespace • A string, set to the UUID of the namespace where the file was attached if it was attached to a shared instance of the study outside of the original storage namespace
wrap_images • An integer of value 1 or 0. If 1, for attachments that are images, or can be rendered to an image, generate a new DICOM image in the study containing (a rendered image of) the attachment (also controlled by namespace setting auto_wrap_images)
wrap_html_as_pdf • An integer of value 1 or 0. If 1, for attachments that are html, generate a new pdf and attach that (instead of the original html)
synchronous_wrap • An integer of value 1 or 0. If 1, do all processing for image wrapping before returning, including Services notifications. Additionally triggers wrap_images functionality
static_ids • An integer of value 1 or 0. If 1, the attachment, series and any images rendered from PDF are assigned (u)uids based on a hash of the attachment, which will be the same if the attachment is re-uploaded. The attachment is also allowed to be re-uploaded when set to 1.
return_html • An integer of value 1 or 0. Return results as Content Type text/html, instead of application/json (required for certain browsers)
data • the request entity must contain a single multipart/form-data element named data containing the content to be attached.
Returns Study attachment attributes • A JSON representation of the attachment's attributes.
HTTP CODE • 202 (ACCEPTED) if there image/frame does not exist.
Errors Permission Denied • If the sid is not valid or the user does not have permission to upload a report to the study.
Notes
  1. The call must be POST.
  2. If the optional parameter wrap_images or synchronous_wrap is set to 1, or the uploading account has the setting auto_wrap_images set to 1, then:
    • attachments of type image/jpeg or image/bmp are, asynchronously (unless synchronous_wrap=1) to the Store Attachment request, posted to the Wrap Attachment service, to be stored as a single DICOM image in a new series within the specified study.
    • attachments of type application/pdf are, asynchronously (unless synchronous_wrap=1) to the Store Attachment request, rendered to DICOM images at a resolution of 200 ppi, one image per page of the original PDF. The resulting are stored in a new series within the specified study. UIDs assigned to the series and images will be random unless static_ids=1
Python Sample + Code
top

Description Downloads a study ZIP file.
URL /study/{namespace}/{studyUid}/download?sid={sid}&phi_namespace={phi_namespace}&bundle={iso,dicom,osx,win}&include_wrapped_dicoms={0,1}&series_uid={series_uid[,series_uid...]}&image_uid={image_uid[,image_uid...]}
Parameters sid • The session id (Required).
phi_namespace • The shared-to namespace UUID of a shared instance of a study (Optional)
bundle • A string with value "dicom", "iso", "osx" or "win" (Required).
include_wrapped_dicoms • When "1", will also include the DICOM file of a wrapped DICOM. Default is to only include the unwrapped file.
series_uid • One or more Series Instance UIDs, comma-separated. Download will only include images from these series.
image_uid • One or more SOP Instance UIDs, comma-separated. Download will only include these images.
stop_on_failure • If "1", will not include the viewer app if there are any errors generating the download.
exclude_viewer • If "1", viewer app will not be included in the "iso", "osx", and "win" bundle. The viewer app can be retrieved separately via /download/viewer
v3 • If "1", viewer app will be pro viewer, and format/content will support pro viewer.
roche_directory • If "1", .dcm files will be organized into StudyDate-ClinicalTrialTimePointID/Modality/SeriesTime-SeriesDescription/ folders (instead of SER000X/ folders).
flat_directory • If "1", .dcm files will be flatly named IMG0001-IMG{image count}, and not be organized into SER folder.
Returns Study ZIP file • Downloads a study as a ZIP file.
HTTP CODE • 403 (NOT FOUND) if there image/frame does not exist.
Errors Permission Denied • If the sid is not valid or the user does not have permission to download a study bundle specified by the namespace and studyUid.
Notes
  1. The call must be GET or POST. POST is necessary if URL exceeds maximum supported length (~2,000 chars)
  2. If the optional parameter bundle is set then:
    • dicom - Include DICOM files and reports only.
    • iso - Include DICOM files, reports, transcoded SD and Diagnostic quality images, the MacOS and the Windows viewer bundle.
    • osx - Include transcoded SD and Diagnostic quality images, and the MacOS viewer bundle.
    • win - Include transcoded SD and Diagnostic quality images, and the Windows viewer bundle.
  3. Errors are reported in ERROR.txt file in the ZIP download.
Python Sample + Code
top

Description Deletes a study attachment.
URL /study/{namespace}/{studyUid}/attachment/{attachmentId}/version/{hash}?sid={sid}?phi_namespace={phi_namespace}
Parameters sid • The session id (Required).
phi_namespace • A string, set to the UUID of the namespace where the file was attached if it was attached to a shared instance of the study outside of the original storage namespace
Returns HTTP CODE • 202 (ACCEPTED) if the attachment was deleted without errors.
Errors Permission Denied • If the sid is not valid or the user does not have permission to delete a report from a study specified by the namespace and studyUid.
Notes
  1. The call must be DELETE.
Python Sample + Code
top

Description Gets a study encapsulated video.
URL /study/{namespace}/{studyUid}/image/{imageUid}/version/{imageVersion}/video?sid={sid}&reencode_video={0,1}
Parameters sid • The session id (Required).
reencode_video • An integer of value 1 or 0.
Returns Study encapsulated video • A stream of the video in an MPEG-4 format.
HTTP CODE • 415 (Unsupported Media Type) if a video was not found encapsulated in the DICOM file.
Errors Permission Denied • If the sid is not valid or the user does not have permission to delete a report from a study specified by the namespace and studyUid.
Notes
  1. The call must be GET or HEAD.
  2. reencode_video - when set the original video will be reencoded to a mp4 format.
Python Sample + Code
top

Description Split a study.
URL /study/{namespace}/{studyUid}/split?sid={sid}&phi_namespace={namespace}&to_namespace={namespace}&series_uid={series_uid,series_uid...series_uid}&delete_series_from_original={0,1}
Parameters sid • The session id (Required).
phi_namespace • An optional namespace UUID to burn-in PHI overrides to split study (defaults to no overrides)
to_namespace • An optional namespace UUID to create the split study (defaults to current namespace)
series_uid • An optional series instance uids list delimited by comas, only specified series will be split (defaults to split all image instances)
delete_series_from_original • An integer value of either 0 or 1. If 1 the series specified in the series_uid list will be deleted from the original study
Returns Study UID • The new study UID.
HTTP CODE • 401 (Unauthorized) if the user does not contain the proper permissions.
Errors Permission Denied • If the sid is not valid or the user does not have permission to split a study.
Study Not Found • If the study to be split cannot be located.
Notes
  1. The call must be POST.
  2. The system will create a copy of the "old study" and assign a new Study UID.
Python Sample + Code
top

Description Merge studies.
URL /study/{namespace}/{studyUid}/merge?sid={sid}&secondary_study_uid={secondary_study_uid}&delete_secondary_study={0,1}
Parameters sid • The session id (Required).
secondary_study_uid • A list of one or more comma-separated secondary Study UIDs to be merged into the studyUid(Required).
delete_secondary_study • An integer, when set to 1 the process will check that the sid provided has the required permission to delete the secondary study.
series_uids • A list of one or more comma-separated Series Instance UIDs, used to filter images merged from secondary study.
Returns HTTP CODE • 401 (Unauthorized) if the user does not contain the proper permissions.
HTTP CODE • 202 (Accepted) if the request was accepted.
HTTP CODE • 500 (Internal Server Error) if the SID provided does not have the proper permission to delete the secondary study if the optional parameter delete_secondary_study is set to 1.
Errors Permission Denied • If the sid is not valid or the user does not have permission to merge the two studies.
Notes
  1. This endpoint is only intended for AmbraHealth account administrators.
  2. The call must be GET.
  3. The system will take the studyUid as the primary study and will merge the secondary_study_uid into the primary.
  4. If the process is completed successfully the primary study will contain the images from the secondary study at the end of the process. If the optional parameter delete_secondary_study is set to 1, storage will delete the secondary study after the merge has been completed.
Python Sample + Code
top

Description Produce a new study that is a copy of the old, with specified pixel regions obscured.
URL /study/{namespace}/{studyUid}/anonymize
Parameters sid • The session id (Required).
to_namespace • The storage namespace into which the new study should be placed (default: same as original).
new_study_uid * The Study Instance UID of the new study (default: randomly generated).
keep_image_uids * Should SOP Instance UIDs of modified copies be same as originals? (default: false)
color * HTML-formatted color (#rrggbb) of obscured regions (default: black-and-white checkerboard)
Returns HTTP CODE • 401 (Unauthorized) if the user does not contain the proper permissions.
HTTP CODE • 202 (Accepted) if the request was accepted.
Errors Permission Denied • If the sid is not valid or the user does not have permission to read or write the original or new study.
Notes
  1. The call must be POST
  2. The request entity is a JSON object specifying the regions to be obscured. Regions may be specified at study, series, or instance level; but only the highest matching level containing a regions field will be used. Example:
    { "series":{ "1.2.3.4.5":{"regions":[{"x":10,"y":10, "width":30, "height":40}]}, "1.3.5.7.9":{ "instances":{ "1.3.5.7.9.101":{"regions":[{"x":20,"y":20, "width":30, "height":20}] } } } }
top

Description Produce a new study that is a copy of the old, cropped to specified pixel region.
URL /study/{namespace}/{studyUid}/crop
Parameters sid • The session id (Required).
to_namespace • The storage namespace into which the new study should be placed (default: same as original).
new_study_uid * The Study Instance UID of the new study (default: randomly generated).
keep_image_uids * Should SOP Instance UIDs of modified copies be same as originals? 1/0 (default: 0/false)
Returns HTTP CODE • 412 (Precondition failed) if phi_namespace or to_namespace is not provided.
HTTP CODE • 401 (Unauthorized) if the user does not contain the proper permissions.
HTTP CODE • 202 (Accepted) if the request was accepted.
Errors Permission Denied • If the sid is not valid or the user does not have permission to read or write the original or new study.
Notes
  1. The call must be POST
  2. The request entity is a JSON object specifying the region to be cropped. Region may be specified at study, series, or instance level; but only the highest matching level containing a region field will be used. Example:
    { "series":{ "1.2.3.4.5":{"region":{"x":10,"y":10, "width":30, "height":40}}, "1.3.5.7.9":{ "instances":{ "1.3.5.7.9.101":{"region":{"x":20,"y":20, "width":30, "height":20} } } } }
top

Description Clears the image and metadata cache for the indicated study.
URL /study/{namespace}/{studyUid}/cache
Parameters sid • The session id (Required).
Returns HTTP CODE • 202 (ACCEPTED)
HTTP CODE • 404 (NOT FOUND) if the study does not exist.
Errors Permission Denied • If the sid is not valid.
Notes
  1. The call must be DELETE.
Python Sample + Code
top

Image commands

Description Upload image to a namespace.
URL /namespace/{namespace}/image?sid={sid}
Parameters sid • The session id (Required).
Returns Image attributes • A JSON representation of the image's attributes.
Errors Permission Denied • If the sid is not valid or the user does not have permission to upload an image from a study specified by the namespace.
Notes
  1. The call must be POST.
Python Sample + Code
top

Description Upload a non DICOM image.
URL /namespace/{namespace}/wrap?sid={sid}&render_wrapped_pdf={0,1}
Parameters sid • The session id (Required).
tags • Any DICOM tags to be overwrite or added should be provided as a form-data field.
file • The multipart file to be uploaded should be provided as a form-data field.
render_wrapped_pdf • An integer value of either 0 or 1.
Headers X-File-Size • The size (bytes) of the file to be DICOM-wrapped (required).
Returns Image attributes • A JSON representation of the image's attributes.
Errors Permission Denied (403) • If the sid is not valid or the user does not have permission to upload a non DICOM file from a study specified by the namespace.
Precondition Failed (412) • Returned if X-File-Size header is not provided or has an invalid value.
Request Entity Too Large (413) • Returned if the file to be DICOM-wrapped is larger than 2GiB (2^31 - 1 bytes).
Notes
  1. The call must be POST.
  2. render_wrapped_pdf - if optional parameter render_wrapped_pdf is set to 1, or if the account setting render_wrapped_pdf is set to 1 for the uploading account, PDF objects are rendered as DICOM images, one Explicit VR LE image per page.
Python Sample + Code
top

Description Gets graphical annotations according to vendor definitions for CAD SR object.
URL /study/{namespace}/{studyUid}/image/{imageUid}/version/{imageVersion}/cadsr?sid={sid}
Parameters sid • The session id (Required).
phi_namespace • A string, set to the UUID of the namespace where the file was attached if it was attached to a shared instance of the study outside of the original storage namespace
Returns Graphical annotations • A JSON array representation of the vendor-specified graphical annotations, empty if not implemented for the vendor or generating device.
HTTP CODE • 404 (NOT FOUND) if the study does not exist.
Errors Permission Denied • If the sid is not valid or the user does not have permission to view the study.
Notes
  1. The call must be GET or HEAD.
Python Sample + Code
top

Description Gets the HL7 report from services, converts to the DICOM SR and uploads to the storage.
URL /study/{namespace}/{studyUid}/hl7/{hl7Uuid}/sr?sid={sid}&phi_namespace={phi_namespace}
Parameters sid • The session id (Required).
phi_namespace • A string, set to the UUID of the namespace where the file was attached if it was attached to a shared instance of the study outside of the original storage namespace
hl7Uuid • hl7 report UUID from services to convert to DICOM SR.
Returns HTTP CODE • 202 Accecpted for the upload to storage.
HTTP CODE • 500 (SERVER ERROR) if hl7 report data not converted to DICOM.
Errors Permission Denied • If the sid is not valid or the user does not have permission to view the study.
Notes
  1. The call must be POST
top