Skip to content Skip to navigation

REST API

RESTful Web Services Application Programmer Interface (API)

Note

All calls should be preceded by /v2, for example http:epad.stanford.edu:8080/epad/v2/projects/

Sessions

POST /session/ Create a session using HTTP Basic Authentication (username and password Base64 encoded in header). Don't use /v2 for this call.
Parameters
Name Type Description
redirectUrl string redirect path
DELETE /session/:session Delete a session by passing the session identifier. Don't use /v2 for this call.

Projects

GET /projects/ Get all projects.
Parameters
Name Type Description
annotationCount boolean Return the annotation count? Default is true.
GET /projects/:project Get this project.
Parameters
Name Type Description
annotationCount boolean Return the annotation count? Default is true.
includeAims boolean Include aims for streaming? Default is true.
format string connectedSummary or stream.
includeAnnotationStatus boolean Include annotation status for series, uses the logged-in username. Default is false
PUT /projects/:project Update an existing project.
Parameters
Name Type Description
projectName string The name of the project.
projectDescription string The description of the project.
defaultTemplate string The default template id to use when creating annotations in this project.
type string The type of project: public or private.
DELETE /projects/:project Delete the project.
POST /projects/:project Create a new project.
Parameters
Name Type Description
projectName string The name of the project.
projectDescription string The description of the project.
defaultTemplate string The default template id to use when creating annotations in this project.

Users

GET /users Get users.
GET /users/:user Get a user. User is user ID or email.
POST /users/:user Create a user.
Input

firstname=first&lastname=last&email=first.last@gmail.com&password=pw&type=new

PUT /users/:user Modify user. All parameters are optional, old password is required only when modifying current password, old password is not required if an admin is logged in.
Parameters
Name Type Description
firstname string The first name of the user.
lastname string The last name of the user.
email string The email of the user.
password string The password of the user.
addPermission string Permissions include CreateProject, CreateUser, CreatePAC,
CreateAutoPACQuery, CreateWorkList
colorpreference string The color of the user's annotations.
DELETE /users/:user Delete user.
PUT /users/:user/sendnewpassword/ Generate a new password and send it to the user's email.
GET /projects/:project/users/ Get the project's users.
PUT /projects/:project/users/:user Modify the user in the project.
Parameters
Name Type Description
role string Member, Collaborator, or Owner
defaultTemplate string Template id of the default template for the user in the project
DELETE /projects/:project/users/:user Remove a user from the project.

Groups

GET /users/:user/groups/ Get groups for user.
PUT /users/:user/groups/:group Create group for user.
DELETE /users/:user/groups/:group Remove group for user.

Patients

GET /subjects/ Get the subjects.
GET /subjects/:subject Get the subject.
GET /projects/:project/subjects/ Get the project's subjects.
Parameters
Name Type Description
start integer Starting subject number.
count integer Return this number of subjects.
includeAnnotationStatus boolean Include annotation status for series, uses the logged-in username. Default is false
GET /projects/:project/subjects/:subject Get a subject in the project.
Parameters
Name Type Description
includeAims boolean Include aims for streaming? Default is true.
format string connectedSummary, summary, file or stream. Default is summary
includeAnnotationStatus boolean Include annotation status for series, uses the logged-in username. Default is false
PUT /projects/:project/subjects/:subject Create or modify a subject in the project.
Parameters
Name Type Description
subjectName string Subject name.
gender string F or M
dob string yyyymmdd
PUT /projects/:project/subjects/:subject/status/:status Set status of the subject.
DELETE /projects/:project/subjects/:subject Remove a subject from a project.
Parameters
Name Type Description
all string Remove subject from all projects? Default is false.
PUT /users/:user/worklists/:worklist/subjects/:subject Add subject to a worklist.
POST /users/:user/worklists/:worklist/subjects/ Add subjects to a worklist.
Input

 {
     "Subjects": [
                "7",
               "LIDC-IDRI-0314",
                "AAA 20120823",
                "AMA 62139"
               ]
}

Studies

GET /projects/:project/subjects/:subject/studies/ Get the studies.
Parameters
includeAnnotationStatus boolean Include annotation status for series, uses the logged-in username. Default is false
PUT /projects/:project/subjects/:subject/studies/:study Add a study to the project.
Parameters
Name Type Description
description string Study description.
studyDate string Study date yymmdd.
GET /projects/:project/subjects/:subject/studies/:study Get a study.
Parameters
Name Type Description
includeAims boolean Include aims for streaming? Default is true.
format string connectedSummary, summary, file or stream. Default is summary
includeAnnotationStatus boolean Include annotation status for series, uses the logged-in username. Default is false
DELETE /projects/:project/subjects/:subject/studies/:study Remove a study from a project.
Parameters
Name Type Description
all boolean Remove study from all projects? Default is false.
deleteAims boolean Remove annotations? Default is false.
GET /pacs/:pac/subjects/:subject/studies/ Get studies for a subject in a connection.
Parameters
Name Type Description
studyDateFilter string Filter by studies after date yyyymmdd
GET /users/:user/worklists/:worklist/studies/ Get studies in a worklist.
GET /users/:user/worklists/:worklist/subjects/:subject/studies/ Get studies in a worklist.
GET /users/:user/worklists/:worklist/subjects/ Get subjects for worklist.
PUT /users/:user/worklists/:worklist/subjects/:subject Modify subject status.
Parameters
Name Type Description
status string Status of the worklist.
started boolean Has it been started?
completed boolean Has it completed?
PUT /users/:user/worklists/:worklist/subjects/:subject/studies/:study Add or modify study in a worklist.
Parameters
Name Type Description
status string Status of the study.
started boolean Has it been started?
completed boolean Has it completed?

Series

GET /studies/:study/series Get the series collection.
GET /projects/:project/subjects/:subject/studies/:study/series/ Get the series collection.
Parameters
Name Type Description
filterDSO boolean Ignore DICOM SEG series. Default is false
includeAnnotationStatus boolean Include annotation status for series, uses the logged-in username. Default is false
GET /projects/:project/subjects/:subject/studies/:study/series/:series Get the series.
Parameters
Name Type Description
includeAims boolean Include aims for streaming? Default is true.
format string connectedSummary, summary, file or stream. Default is summary
includeAnnotationStatus boolean Include annotation status for series, uses the logged-in username. Default is false
PUT /projects/:project/subjects/:subject/studies/:study/series/:series Create a non-dicom series or update series annotation status
Parameters
Name Type Description
description string series description
seriesDate date series date
annotationStatus integer Number indicating the annotation status 1 (NOT_STARTED) , 2 (IN_PROGRESS) or 3 (DONE)
DELETE /projects/:project/subjects/:subject/studies/:study/series/:series Delete a series.
Parameters
Name Type Description
all boolean Remove series from all projects? Default is false.
deleteAims boolean Remove annotations? Default is false.
GET /pacs/:pacs/subjects/:subject/studies/:study/series/ Get list of series for this study and subject in connection.

Images

GET /wado/ get the WADO instance. (Note /v2 is not required in URL)
Parameters
Name Type Description
requestType boolean WADO.
studyUID string study id.
seriesUID string series id.
objectUID string instance id.
contentType string application%2Fdicom
GET /studies/:study/series/:series/images/:image Get the image.
GET /projects/:project/subjects/:subject/studies/:study/series/:series/images/ get the images in the series
GET /projects/:project/subjects/:subject/studies/:study/series/:series/images/:image Get an image in the collection.
DELETE /projects/:project/subjects/:subject/studies/:study/series/:series/images/:image Delete an image.
GET /projects/:project/subjects/:subject Download images for this subject to zip file.
Parameters
Name Type Description
format string file or stream.
GET /projects/:project/subjects/:subject/studies/:study Get images for this study in a zip file.
Parameters
Name Type Description
format string stream or file.
GET /projects/:project/subjects/:subject/studies/:stud/series/:series Download images for this series in a zip file.
Parameters
Name Type Description
format string file or stream.

Frames

GET /studies/:study/series/:series/images/:image/frames Get the frames.
GET /projects/:project/subjects/:subject/studies/:study/series/:series/images/:image/frames Get the frames.
Parameters
Name Type Description
includePixels boolean Return the pixel values as an array
allTags boolean Return DICOM tags for all frames
GET /projects/:project/subjects/:subject/studies/:study/series/:series/images/:image/frames/:frameNumber Get the frame.
Parameters
Name Type Description
includePixels boolean Return the pixel values as an array
POST /projects/:project/subjects/:subject/studies/:study/series/:series/images/:image/frames Edit a DICOM SEG series, multiple part request, json edit request followed by mask files.
POST /projects/:project/subjects/:subject/studies/:study/series/:series/images/:image/frames Create a new DICOM SEG series, multiple part request, json edit request followed by mask files. SeriesUID is series of the source dicom.
Parameters
Name Type Description
type string new
name string Name of series
GET /projects/:project/subjects/:subject/studies/:study/series/:series/images/:image/frames/:frame Get the frame.

Annotations

GET /aims/ Get the annotations.
Parameters
Name Type Description
start integer Annotation number to start with.
count integer Number of annotations returned.
format string Annotations returned as xml documents or summary will return a JSON summary.
GET /aims/:aim Get the annotation.
Parameters
Name Type Description
version string all or previous Get all versions of the annotations or the previous version.
format string Annotations returned as xml documents or summary will return a JSON summary.
GET /aims/:aim Get json data for this annotation and plugin.
Parameters
Name Type Description
templateName string template identifier
format string data
PUT /aims/:aim Undo OR Redo last change in the annotation.
Parameters
Name Type Description
action string undo or redo
PUT /aims/:aim Set color for the annotation.
Parameters
Name Type Description
color string hex color value
DELETE /aims/:aim Delete the annotation.
Parameters
Name Type Description
deleteDSO boolean Also delete the SEG DICOM files associate with the annotation. Default value is false.
GET /subjects/:subject/aims/ Get the annotations for the subject.
Parameters
Name Type Description
start integer Retrieve annotations starting at number.
count integer Number of annotations to return.
format string summary
GET /projects/:project/aims/ Get the annotations for the project.
Parameters
Name Type Description
start integer Retrieve annotations starting at number.
count integer Number of annotations to return.
format string summary If no format is specified, the xml annotation will be returned.
patientId string Filter by subject identifier.
seriesUID string Filter by series identifier.
annotationUID string,string,string Filter by by a comma separated list of annotation identifiers.
aimQL string Filter by an aimQL query.
GET /projects/:project/aims/:aim Get the annotation for the project.
Parameters
Name Type Description
format string summary, data or connectedSummary. If no format is specified, the xml annotation will be returned.
PUT /projects/:project/aims/ Run the specified plugin template on the annotation IDs.
Parameters
Name Type Description
annotationUID string, string, string List of annotations.
templateName string Template id for the plugin.
PUT /projects/:project/aims/:aim Create a new annotation.
GET /projects/:project/subjects/:subject/aims/ Get the annotations for the subject in the project.
Parameters
Name Type Description
start integer Retrieve annotations starting at number.
count integer Number of annotations to return.
format string summary
PUT /projects/:project/subjects/:subject/aims/:aim Create an annotation in a project for a subject.
GET /studies/:study/series/:series/images/:image/aims/ Get the annotations for the image.
Parameters
Name Type Description
start integer Retrieve annotations starting at number.
count integer Number of annotations to return.
format string summary
GET /projects/:project/subjects/:subject/studies/:study/aims/ Get the annotations.
Parameters
Name Type Description
start integer Retrieve annotations starting at number.
count integer Number of annotations to return.
format string summary
PUT /projects/:project/subjects/:subject/studies/:study/aims/:aim Create a new annotation.
GET /projects/:project/subjects/:subject/studies/:study/series/:series/aims/ Get the annotations. If no format is specified, the xml annotation will be returned. Include Study Aims if parameter is set to true.
Parameters
Name Type Description
start integer Retrieve annotations starting at number.
count integer Number of annotations to return.
format string summary
includeStudyAims boolean
PUT /projects/:project/subjects/:subject/studies/:study/series/:series/aims/:aim Create an annotation in the series.
GET /projects/:project/subjects/:subject/studies/:study/series/:series/images/:image/aims/ get the annotations IDs for the image.
Parameters
Name Type Description
start integer Retrieve annotations starting at number.
count integer Number of annotations to return.
PUT /projects/:project/subjects/:subject/studies/:study/series/:series/images/:image/aims/:aim create an annotation for the image
GET /projects/:project/subjects/:subject/studies/:study/series/:series/images/:image/frames/:frame/aims/ get the annotations for the frame. If no format is specified, the xml annotation will be returned.
Parameters
Name Type Description
start integer Retrieve annotations starting at number.
count integer Number of annotations to return.
GET /users/:user/reviewees/:reviewee/aims/ Get annotations for reviewee.

Files

GET /resourcesFile Get files under the resource folder, Note /v2 is not required in URL.
Parameters
Name Type Description
relativePath string path of file /dicom//studies/{id}/series/ {id}/images/{file}
GET /projects/:project/files/ Get non-DICOM files for this project.
Parameters
Name Type Description
fileType string Template
format string summary
GET /projects/:project/files/:file Get a non-DICOM file for this project.
Parameters
Name Type Description
format string summary or summary
GET /projects/:project/subjects/:subject/files/ Get non-DICOM files for this project and subject.
Parameters
Name Type Description
fileType string Template
format string summary or summary
GET /projects/:project/subjects/:subject/studies/:study/files/ get non-DICOM files for this project, subject and study.
Parameters
Name Type Description
fileType string Template
format string summary or summary
GET /projects/:project/subjects/:subject/studies/:study/series/:series/files/ Get non-DICOM files for this project, subject, study and series.
Parameters
Name Type Description
fileType string Template
format string summary or summary
POST /projects/{id}/files/?fileType=[Template | Annotation | Image]&description={value} Upload files for this project
POST /projects/{id}/subject/{id}/files/ Upload files for this project and subject
POST /projects/{id}/subject/{id}/studies/{id}/files/ Upload files for this project, subject and study
POST /projects/{id}/subject/{id}/studies/{id}/series/{id}/files/ Upload files for this project, subject, study and series
PUT /projects/{id}/files/{filename}?name={value}&description={value}&fileType={type} Change name, description, type for a file (all parameters are optional)
DELETE /projects/{id}/files/{name} delete a non-DICOM file in this project
DELETE /projects/{id}/subjects/{id}/files/{name} delete a non-DICOM file for this subject
DELETE /projects/{id}/subjects/{id}/studies/{id}/files/{name} delete a non-DICOM file for this study
DELETE /projects/{id}/subjects/{id}/studies/{id}/series/{id}/files/{name} delete a non-DICOM file for this series

Templates

GET /templates/ Get templates.
PUT /templates/ Upload template. Template will be validated against schema.
POST /templates/ Upload template. Template will be validated against schema.
GET /projects/:project/files/ Get the templates for this project.
Parameters
Name Type Description
fileType string Template
includeSystemTemplates boolean include system templates. Default value is true
POST /projects/:project/files/ Upload a new template for this project, xml will be validated.
Parameters
Name Type Description
fileType string Template
description string description of the file
PUT /projects/:project/templates/:templatecode enable/disable templates
Parameters
Name Type Description
enable boolean Enable or disable template in project.
PUT /templates/:templatecode Enable or disable template.
Parameters
Name Type Description
enable boolean enable or disable
DELETE /templates/:templatecode Delete template.

Tools

GET /plugins/ Get tools.
Parameters
Name Type Description
format string summary or json
PUT /plugins/:plugin Create tool.
Parameters
Name Type Description
name string name of tool
class string class name of tool
enabled boolean enable or disable tool
modality string tool works on specified modality
developer string tool author
documentation string what the tool does
rate string not sure
DELETE /plugins/:plugin Delete tool.
GET /projects/:project/plugins/ Get tools for this project.
Parameters
Name Type Description
format string summary or json
PUT /projects/:project/plugins/:plugin Enable or disable tools for this project.
Parameters
Name Type Description
enable boolean true or false
GET /projects/:project/plugins/:plugin/parameters/ Get tool parameters for this project.
PUT /projects/:project/plugins/:plugin/parameters/ Set tool parameters for this project.
Parameters
Name Type Description
param string parameter name
val string parameter value

Connections

GET /pacs/ Get connections.
GET /pacs/:pacs Get connection.
DELETE /pacs/:pacs Delete connection.
PUT /pacs/:pacs Modify or create connection.
Parameters
Name Type Description
aeTitle string aeTitle
hostname string host url
port integer port number
primaryDeviceType string primary device type
GET /pacs/:pacs/entities/ get list of studies/series/images in this Remote PAC. Formats for date filter - on: '20071001', from/to: '20071001-20080220', before: '-20080220', after: '20071001-' . If series= true, return series records as well as studies.
Parameters
Name Type Description
patientNameFilter string Filter names by filter string.
patientIDFilter string Filter patient identifiers by filter string.
studyDateFilter date Filter dates by filter string.
series boolean
GET /pacs/{id}/entities/?tagGroup={value}&tagElement={value}&tagValue={value}&tagType=[LongString | ShortString | Date | Time | Integer | Decimal | Code] get list of studies/series/images in this Remote PAC, filter by specified DICOM tag. The tagType parameter is optional (defaults to LongString). Unfortunately if the tag is not supported for query by the PAC, all records are returned. Example query by Body Part Tag: /pacs/epad-build/entities/?tagGroup=0x0018&tagElement=0x0015&tagValue=CHEST&tagType=ShortString
GET /pacs/{id}/subjects/?patientNameFilter={value}&patientIDFilter={value} get list of subjects in this Remote PAC.
GET /pacs/:pacs/entities/:entity Transfer this data (and all its children) from this Remote PAC to ePAD's dcm4chee and into this project.
Parameters
Name Type Description
projectID string Project id.
GET /pacs/getFromTCIA/ Download series from TCIA and add it to a project.
Parameters
Name Type Description
seriesUID string Series id.
projectID string Project id.

AutoQueries

GET /pacs/:pacs/autoqueries/ List of configured automatic queries for this Remote PAC
GET /pacs/:pacs/autoqueries/:autoquery get configured automatic query for this Remote PAC and this subject
PUT /pacs/:pacs/autoqueries/:autoquery configure an automatic query for this Remote PAC and this subject. projectID is required, the other parameters are optional.
Parameters
Name Type Description
projectID string project
studyDate date study date
subjectName string subject name
modality string modality
PUT /pacs/:pacs/autoqueries/:autoquery enable/disable automatic query for this Remote PAC and this subject.
Parameters
Name Type Description
enable boolean enable or disable this query
DELETE /pacs/:pacs/autoqueries/:autoquery Delete query for this connection and this subject.
GET /pacs/dicomtags/ Get a list of dicom tags.

Queries

GET /queries/ Get queries.
PUT /queries/ Create a query.
Parameters
Name Type Description
connection string connection id
subject string subject id
modality string exam modality.
date date Find studies after this study date yyyymmdd.
enable boolean Default value is true.
GET /queries/:query Get this query.
DELETE /queries/:query Delete the query.
PUT /queries/:query Modify a query.
Parameters
Name Type Description
connection string connection id
subject string subject id
modality string exam modality.
date date Find studies after this study date yyyymmdd.
enable boolean Default value is true.

Worklists

GET /users/:user/worklists/ Get the worklists.
GET /users/:user/worklists/:worklist Get the worklist.
DELETE /users/:user/worklists/:worklist Delete the worklist.
PUT /users/:user/worklists/:worklist Create a worklist.
Parameters
Name Type Description
description string Description of the worklist.
dueDate date yyyymmdd
PUT /users/:user/worklists/:worklist Modify the worklist.
Parameters
Name Type Description
status string Status of the worklist.
started boolean Has it been started?
completed boolean Has it completed?

Logs

GET /users/:user/eventlogs/ Get a log of user actions.
Parameters
Name Type Description
start integer Start at log number.
count integer Return a number of log entries.

Task Status

GET /users/:user/taskstatus/ Get status of executing tasks.

Installation Status

GET /epad/status Get the status of the installation. (/v2 not required)
GET /epad/imagecheck Get the status of images. (/v2 not required)

Fixers

GET /epad/imagecheck/?seriesUID=:seriesUID Trigger png generating on a specific series. (/v2 not required)
GET /epad/dsoresave/?projectID=:projectID&seriesUID=:seriesUID&aimID=:aimID Resave the DSO to fix the old DSOs with DICOM tag issues. SeriesUID or aimID is enough (/v2 not required)
GET /epad/dsoresave/?projectID=:projectID&nameContains=:nameContains Resave the DSO to fix the old DSOs with DICOM tag issues. It will filter the aims with the name containing :nameContains and resave them (/v2 not required)

Installations

GET /epads/stats/ Get ePAD hosts.
Parameters
Name Type Description
year integer (four digits) The year to statistics for.
GET /epads/ Get ePAD hosts.
Parameters
Name Type Description
summary boolean Return summary for each host (latest statistics). Default value isfalse
monthly boolean Return monthly stats for each host (latest statistics). Default value isfalse
activeCount boolean Return active host count for number of activeLast days. Default value isfalse
activeLast boolean Number of days to check the active status. Default value is7
GET /epads/:epad Get usage statistics for the host.
GET /epads/version/ Get ePAD version.
GET /epads/version/ Download current ePAD version.
Parameters
Name Type Description
downloadLatestEPAD boolean Download the current release to your installation.