2.1. API v1

2.1.1. General information

To do a call to API, the URL needs to be constructed as follows:

<server_address>/api/v1/<api_command>/

and the following header parameters are required for each call:

X-USERNAME: The username of the user.
X-PASSWORD: The password of the user.

2.1.2. Calls

The following API calls are available:

Note

Api calls related to retina do not use the SeriesInstanceUID of the file for the SeriesInstanceUID. Instead, the SOPInstanceUID of the file for the SeriesInstanceUID field is used.

Limiting your filenames to only include alphanumeric characters, dashes and underscores is highly encouraged. Characters other then these (e.g. spaces, parentheses) will be removed/replaced by the application to create a cleaner filename and this might cause inconsistencies between input/output filenames.

2.1.2.2. Patient commands 

2.1.2.2.1. Get patient 

Description:	Get patient data
URL:	/patient/get/
Method:	GET
Parameters:	`Project`: Project of the patient `Archive`: Archive of the patient `PatientID`: ID of the patient
Error types:	object_not_found, method_not_allowed
Suberror types:	patient_not_found
Returns:	`PatientBirthDate`: Birthdate of the patient `PatientID`: ID of the patient `PatientName`: Name of the patient `PatientSex`: Sex of the patient
Permission:	`api_get_patient`

2.1.2.2.2. Delete patient 

Description:	Delete patient
URL:	/patient/delete/
Method:	GET
Parameters:	`Project`: Project of the patient `Archive`: Archive of the patient `PatientID`: ID of the patient
Error types:	object_not_found, method_not_allowed
Suberror types:	patient_not_found
Returns:	`status`: Ok or Error
Permission:	`api_delete_patient`

2.1.2.3. Study commands 

2.1.2.3.1. Get study 

Description:	Get study data
URL:	/study/get/
Method:	GET
Parameters:	`Project`: Project of the patient `Archive`: Archive of the patient `PatientID`: ID of the Patient `StudyInstanceUID`: Study instance UID of the study
Error types:	object_not_found, method_not_allowed
Suberror types:	study_not_found
Returns:	`StudyInstanceUID`: Study instance UID of the study `StudyDate`: Date of the study `StudyTime`: Time of the study `StudyDescription`: Description of the study `ReferringPhysicianName`: Name of the referring physician `InstitutionName`: Name of the institution `AccessionNumber`: A number that identifies the order for the Study
Permission:	`api_get_study`

2.1.2.3.2. List studies 

Description:	List all studies of a patient
URL:	/patient/studies/list/
Method:	GET
Parameters:	`Project`: Project of the patient `Archive`: Archive of the patient `PatientID`: ID of the patient
Error types:	object_not_found, method_not_allowed
Suberror types:	patient_not_found
Returns:	List of study objects (see Get study for a list of returned parameters per study).
Permission:	`api_list_studies`

2.1.2.3.3. Delete study 

Description:	Delete study
URL:	/study/delete/
Method:	GET
Parameters:	`Project`: Project of the patient `Archive`: Archive of the patient `PatientID`: ID of the patient `StudyInstanceUID`: Study instance UID of the study
Error types:	object_not_found, method_not_allowed
Suberror types:	study_not_found
Returns:	`status`: Ok or Error
Permission:	`api_delete_study`

2.1.2.4. Series commands 

2.1.2.4.1. Get series 

Description:	Get series data
URL:	/series/get/
Method:	GET
Parameters:	`Project`: Project of the patient `Archive`: Archive of the patient `PatientID`: ID of the Patient `StudyInstanceUID`: Study instance UID of the study `SeriesInstanceUID`: Series instance UID of the series
Error types:	object_not_found, method_not_allowed
Suberror types:	series_not_found
Returns:	`SeriesInstanceUID`: Series instance UID of the series `SOPClassUID`: SOP class UID of the series `SeriesDate`: Date of the series `SeriesTime`: Time of the series `SeriesDescription`: Description of the series `Manufacturer`: Manufacturer of the machine used to take the series `ManufacturerModelName`: Name of the model of the machine used code:’status’: The status of the series in the database code:’status_message’: Status message of the series in the database
Permission:	`api_get_series`

2.1.2.4.2. List series 

Description:	List all series of a study
URL:	/patient/study/series/list/
Method:	GET
Parameters:	`Project`: Project of the patient `Archive`: Archive of the patient `PatientID`: ID of the Patient `StudyInstanceUID`: Study instance UID of the study
Error types:	object_not_found, method_not_allowed
Suberror types:	study_not_found
Returns:	List of series objects (see Get series for a list of returned parameters
Permission:	`api_list_series`

2.1.2.4.3. Get series dicom 

Description:	Get series dicom data
URL:	/dicom/get/
Method:	GET
Parameters:	`Project`: Project of the patient `Archive`: Archive of the patient `PatientID`: ID of the Patient `StudyInstanceUID`: Study instance UID of the study `SeriesInstanceUID`: Series instance UID of the series
Error types:	object_not_found, method_not_allowed
Suberror types:	series_not_found, no_dicom_available
Returns:	`zipfile`: Zip file containing all dicom files of the series. The zip file can contain multiple dicom files if the series has multiple instances.
Permission:	`api_dicom_get`

2.1.2.4.4. Delete series 

Description:	Delete series
URL:	/series/delete/
Method:	GET
Parameters:	`Project`: Project of the patient `Archive`: Archive of the patient `PatientID`: ID of the patient `StudyInstanceUID`: Study instance UID of the study `SeriesInstanceUID`: Series instance UID of the series
Error types:	object_not_found, method_not_allowed
Suberror types:	series_not_found
Returns:	`status`: Ok or Error
Permission:	`api_delete_series`

2.1.2.5. Result commands 

2.1.2.5.1. Get algorithm results 

Description:	Get algorithm results
URL:	/series/results/
Method:	GET
Parameters:	`Project`: Project of the patient `Archive`: Archive of the patient `PatientID`: ID of the Patient `StudyInstanceUID`: Study instance UID of the study `SeriesInstanceUID`: Series instance UID of the series `Type`: Type of the result (cad4tb/retina) `Results`: Name of the result requested. Multiple results can be requested simultanously by specifying them in a list. (e.g. results1,result2,result3)
Error types:	object_not_found, method_not_allowed
Suberror types:	result_not_found
Returns: (int/float/string type results)	`name`: Name of the algorithm `algorithm`: Type of algorithm `value`: Result score
Returns: (other type results)	`zipfile`: Zipfile including all the result files. In case a combination of int/float/string typed results and others is requested, the int/float/string typed results are combined in an xml file which is added to the zipfile.
Permission:	`api_series_results`

2.1.2.6. Reporting commands 

2.1.2.6.1. Get reportings 

Description:	List reportings
URL:	/patient/study/series/forms/list/
Method:	GET
Parameters:	`Project`: Project of the patient `Archive`: Archive of the patient `PatientID`: ID of the patient `StudyInstanceUID`: Study instance UID of the study `SeriesInstanceUID`: Series instance UID of the series
Error types:	object_not_found, method_not_allowed
Suberror types:	series_not_found
Returns:	`id`: ID of the reportings `entry`: Reporting represented as JSON data `entry_formatted`: Formatted representation of the entry `user`: Email of the user who created the reportings `series`: Series instance UID belonging to the report `form`: Name of the form the report belongs to
Permission:	`api_list_forms`

2.1.2.6.2. Add reportings 

Description:	Add new reportings
URL:	/patient/study/series/forms/add/
Method:	POST
Body:	`Project`: Project of the patient `Archive`: Archive of the patient `PatientID`: ID of the patient `StudyInstanceUID`: Study instance UID of the study `SeriesInstanceUID`: Series instance UID of the series `FormName`: Name of the form for which you want to add a submission `FormSubmission`: The form submission in valid JSON
Error types:	object_not_found, method_not_allowed, multiple_objects_found
Suberror types:	series_not_found, form_not_found
Permission:	`api_add_form_submission`

2.1.3. Example calls

There are several ways to do the calls to our system, such as cURL, python requests, etc. In this section, examples are shown using the Python requests package.

2.1.3.1. Python requests package

Example call to get a patient with the following information:

PatientID: 12345
Archive: some-archive
Project: some-project

import requests

# Call required parameters:
payload = {'Project': 'some-project', 'Archive': 'some-archive', 'PatientID': '12345'}

# Credentials:
credentials = {'X‐USERNAME': 'some-username','X-PASSWORD': 'some-password'}

# Make the request:
r = requests.get("<server_address>/api/v1/patient/get/", params=payload, headers=credentials)

# Returned data
print(r.content)
# Prints: '{"PatientName": "Anonymous", "PatientID": "12345",
#           "PatientSex": "M", "PatientBirthDate": "1900-01-01"}'

Example call to get the result of a given series with the following information:

PatientID: 12345
StudyInstanceUID: 1.2.3.4.5
SeriesInstanceUID: 1.2.3.4.5.6
Type: cad4tb
Results: CAD4TB 5
Archive: some-archive
Project: some-project

import requests

# Call required parameters:
payload = {'Project': 'some-project',
           'Archive': 'some-archive',
           'PatientID': '12345',
           'StudyInstanceUID': '1.2.3.4.5',
           'SeriesInstanceUID': '1.2.3.4.5.6',
           'Type': 'cad4tb'
           'Results': 'CAD4TB 5'}

# Credentials:
credentials = {'X‐USERNAME': 'some-username','X-PASSWORD': 'some-password'}

# Make the request:
r = requests.get("<server_address>/api/v1/patient/get/", params=payload, headers=credentials)

# Returned data
print(r.content)
# Prints: '[{"name": "CAD4TB 5", "algorithm": "CAD4TB", "value": 12.345}]'