Backend API Requests Documentation

Overview

The backend APIs are a series of available REST API endpoints that developer may interface with for data queries. The knowledge about these endpoints are not required by average users, since all the request and communications are hidden from users. However, these will likely come in handy for people who want to modify the backend or develope their own frontend pipelines.

There are many modules among the backend APIs, which can be divided based on functionalities.

Authentication Module for User (Research/Admin/Mobile) related actions.
Queries Module for requesting data from database.
SQL Database Update Module for changing patient/device information in database.
Upload Module for handling file uploads from user.
Survey Module for handling online-survey related changes. This is non-neurostimulator specific module.

Authentication Module

The Authentication Module file contain all routes that handles account creation and authentication. Most functions are wrapper around the Django REST Knox library that performs Authentication Token management.

class APIs.Auth.UserRegister(**kwargs)

User Registration (Web Account Only).

POST: /api/registration

Parameters

Email (string) – Email address will also serve as unique username. Must be a properly formated Email address and unique within database.
UserName (string) – Human readable name of the user.
Institute (string) – Common institute name of the user. This allow sharing of data among multiple users within same institute.
Password (string) – Password of the account. Database will hash the password for security. User may also choose to perform end-to-end encryption during transmission if they desire.

Returns

Response Code 200 if success or 400 if error. Response Body contains authentication token and user object.

class APIs.Auth.UserAuth(**kwargs)

User Authentication (Web Account Only).

POST: /api/authenticate

Parameters

Email (string) – Email address also serves as unique username.
Password (string) – Password of the account. Database will hash the password for security. User may also choose to perform end-to-end encryption during transmission if they desire.
Persistent (Boolean) – If the token’s expiration date should be extremely long or not.

Returns

Response Code 200 if success or 400 if error. Response Body contains authentication token and user object.

class APIs.Auth.UserTokenRefresh(**kwargs)

class APIs.Auth.FetchAuthorizedInstitute(**kwargs): NOT IMPLEMENTED

class APIs.Auth.UserSignout(**kwargs)

User logout while detroying the authentication token.

POST: /api/logout

Parameters: refresh (string) – the refresh-token for persistent connection.
Returns: Response Code 204.

class APIs.Auth.Handshake(**kwargs)

Confirming that the BRAVO server exist.

POST: /api/handshake

Returns: Response Code 200.

Queries Module

The Queries Module file contain all routes called by React Frontend to request data for display. These functions are mostly top-level wrappers that call low-level computation and processing scripts outlined in other documentation.

All Queries require UserAuthentication in request, indicating that if a request is made without Authentication Token will be automatically rejected. Therefore, NotAuthenticated error will not be discussed in each function but implied.

All Queries will be subjected to a simple “Access Verification” function that determine what data the user has access to. Currently only 3 tier of access control is added:

Tier 0 = Not Accessible
Tier 1 = Owner Access (You uploaded the data or that you are Admin/Clinician account)
Tier 2 = Permissible Access (You didn’t upload the data but an Admin has granted you access through Admin Panel).

class APIs.Queries.QueryDatabaseInfo(**kwargs)

Query current database information.

POST: /api/queryDatabaseInfo

Returns: Response Code 200. Response Body contains number of unique patients in database and size of data the user has access to.

class APIs.Queries.QueryPatientList(**kwargs)

Query list of accessible patients in database.

POST: /api/queryPatients

Returns: Response Code 200. Response Body contains list of patient object.

class APIs.Queries.QueryPatientAccessTable(**kwargs)

Query list of accessible patients in database.

POST: /api/queryPatientAccessTable

Returns: Response Code 200. Response Body contains list of patient object with access information.

class APIs.Queries.QueryPatientInfo(**kwargs)

Query detailed patient information.

POST: /api/queryPatientInfo

Parameters: id (uuid) – Patient Unique Identifier as provided from QueryPatientList route.
Returns: Response Code 200. Response Body contains a single patient object with detailed information.

class APIs.Queries.QueryProcessingQueue(**kwargs)

Query current processing queue list

POST: /api/queryProcessingQueue

Returns: Response Code 200. Response Body contains list of processing queue items owned by the request owner.

class APIs.Queries.QueryTherapyHistory(**kwargs)

Query all therapy histories from desired patient.

The therapy histories include both therapy change logs and clinician configurations.

The therapy histories do not include how patient adjust their stimulation amplitude within range because this information is not saved. If BrainSense is enabled, user may query the stimulation amplitude changes through Chronic BrainSense.

POST: /api/queryTherapyHistory

Parameters: id (uuid) – Patient Unique Identifier as provided from QueryPatientList route.
Returns: Response Code 200 if success or 400 if error. Response Body contains list of all Therapy Change Logs and Therapy Configurations.

class APIs.Queries.QueryBrainSenseSurveys(**kwargs)

Query all BrainSense Survey data.

The BrainSense Survey query will return processed power spectral density calculated from time-domain data. This is not the same as the on-board FFT result shown on Medtronic Tablet.

Raw time-domain data will not be returned from this route.

POST: /api/queryBrainSenseSurveys

Parameters: id (uuid) – Patient Unique Identifier as provided from QueryPatientList route.
Returns: Response Code 200 if success or 400 if error. Response Body contains list of all BrainSense Surveys.

class APIs.Queries.QueryBrainSenseStreaming(**kwargs)

Query BrainSense Streaming Data.

The BrainSense Streaming query allows for multiple type of requests, based on what is sent in request body.

POST: /api/queryBrainSenseStreaming

Request List of Available BrainSense Streaming Data

{
  "requestOverview": true,
  "id": "(uuid)",
}

Request specific BrainSense Streaming Recording based on recording ID

requestFrequency is optional if user want to request power value from different frequency instead of the automated algorithm

{
  "requestData": true,
  "id": "(uuid)",
  "recordingId": "(uuid)",
  "[requestFrequency]": "(int)"
}

Request update on power spectrum data for rendering

channel is the Medtronic convention of channel identification, which is usually CONTACT_CONTACT_HEMISPHERE (i.e.: ZERO_TWO_LEFT)

This is a faster operation than request BrainSense Streaming Recording using requestFrequency because this operation does not transmit raw data.

{
  "updateStimulationPSD": true,
  "id": "(uuid)",
  "recordingId": "(uuid)",
  "channel": "(string)",
  "centerFrequency": "(int)",
  "stimulationReference": "(string)",
}

Update BrainSense Streaming result with or without cardiac filter

Permission denied unless you are the data owner (Permission == 1)

{
  "updateCardiacFilter": "(boolean)",
  "id": "(uuid)",
  "recordingId": "(uuid)"
}

Returns: Response Code 200 if success or 400 if error. Response Body contains requested data, often large due to time-domain data transmission.

class APIs.Queries.QueryIndefiniteStreaming(**kwargs)

Query all Indefinite Streaming Data.

The Indefinite Streaming query allows for multiple type of requests, based on what is sent in request body.

POST: /api/queryIndefiniteStreaming

Request List of Available Indefinite Streaming Data

{
  "requestOverview": true,
  "id": "(uuid)",
}

Request specific Indefinite Streaming Recording based on list of provided devices and timestamps

{
  "requestData": true,
  "id": "(uuid)",
  "timestamps": ["(int)"],
  "devices": ["(uuid)"]
}

Returns: Response Code 200 if success or 400 if error. Response Body contains requested data, often large due to time-domain data transmission.

class APIs.Queries.QueryChronicBrainSense(**kwargs)

Query all Chronic BrainSense Data.

The Chronic BrainSense data includes single power-band recorded using BrainSense-enabled group, patient-reported events and event power spectrums.

POST: /api/queryChronicBrainSense

Parameters

id (uuid) – Patient Unique Identifier as provided from QueryPatientList route.
requestData (boolean) – Always true to request data.
timezoneOffset (int) – seconds offset compare to Universal Time Coordinate. You can request this value from your browser through new Date().getTimezoneOffset()*60.

Returns

Response Code 200 if success or 400 if error. Response Body contains Chronic BrainSense and Event PSDs.

class APIs.Queries.QueryAdaptiveStimulation(**kwargs)

Query all Chronic BrainSense Data.

The Chronic BrainSense data includes single power-band recorded using BrainSense-enabled group, patient-reported events and event power spectrums.

POST: /api/queryAdaptiveStimulation

Parameters

id (uuid) – Patient Unique Identifier as provided from QueryPatientList route.
requestData (boolean) – Always true to request data.
timezoneOffset (int) – seconds offset compare to Universal Time Coordinate. You can request this value from your browser through new Date().getTimezoneOffset()*60.

Returns

Response Code 200 if success or 400 if error. Response Body contains Chronic BrainSense and Event PSDs.

class APIs.Queries.QuerySessionOverview(**kwargs)

Query all JSON sessions related to a patient.

This route will provide user with all JSON files uploaded related to a specific patient ID. This is useful to identify raw unprocessed file for analysis outside of the web platform.

User may also request deletion of session file (and all associated data) by requesting deletion.

POST: /api/querySessionOverview

Parameters: id (uuid) – Patient Unique Identifier as provided from QueryPatientList route.
Returns: Response Code 200 if success or 400 if error. Response Body contains nothing if deleteSession is requested, otherwise contain list of available session files.

class APIs.Queries.QueryPredictionModel(**kwargs)

class APIs.Queries.QueryMultipleSegmentComparison(**kwargs)

class APIs.Queries.QueryPatientEvents(**kwargs)

class APIs.Queries.QueryCustomAnnotations(**kwargs)

class APIs.Queries.QueryCustomizedAnalysis(**kwargs): Query Customized Analysis.

class APIs.Queries.QueryMobileRecordings(**kwargs): Query Customized Analysis.

class APIs.Queries.QueryRecordingsForAnalysis(**kwargs): Query Recording Raw Data for Analysis.

class APIs.Queries.QueryImageModelDirectory(**kwargs)

Query all Image models store in the patient’s imaging folder.

This route will provide user with all model descriptor related to a specific patient, assuming there are imaging models in the patient’s imaging folder.

POST: /api/queryImageDirectory

Parameters: id (uuid) – Patient Unique Identifier as provided from QueryPatientList route.
Returns: Response Code 200 if success or 400 if error. Response Body contains descriptor, a dictionary that describe initial rendered objects and their parameters, and availableModels, an array of dictionary with field {file, type, mode}.

class APIs.Queries.QueryImageModel(**kwargs)

Query all Image models store in the patient’s imaging folder.

This route will provide user with all model descriptor related to a specific patient, assuming there are imaging models in the patient’s imaging folder.

POST: /api/queryImageModel

Parameters

Directory (uuid) – Patient Unique Identifier as provided from QueryPatientList route.
FileMode (string) – “single” or “multiple”, define whether the API should return individual file or pagination for multiple requests.
FileType (string) – “stl”, “tracts”, or “electrode”, define what kind of model the server should retrieve. This defines the decoder function.
FileName (string) – filename of the model.

Returns

Response Code 200 if success or 400 if error. Response Body contains an octet-stream (binary buffer) for “stl” and “electrode”, or array of points for tracts.

class APIs.Queries.QueryCircadianPower(**kwargs)

SQL Database Update Module

class APIs.UpdateRecordings.PatientInformationUpdate(**kwargs)

Update Patient Information in SQL Table

The Patient Information Update has multiple functions implemented for the route, depending on the command sent.

POST: /api/updatePatientInformation

Manually creating a new Patient entry in database

{
  "createNewPatientInfo": true,
  "StudyID": "(string)",
  "PatientID": "(string)",
  "Diagnosis": "(string)",
  "StudyID": "(string)",
  "DeviceName": "(string)",
}

Respond body will contain new patient object if successful.

Add new Device entry for specific patient

updatePatientInfo is the unique identifier for a specific Patient object. The saveDeviceID is a human readable identifier for the device. A random 32-byte unique identifier for the device will be randomly generated.

{
  "updatePatientInfo": "(uuid)",
  "saveDeviceID": "(string)",
  "newDeviceLocation": "(string)",
}

Change Device Name

updatePatientInfo is the unique identifier for a specific Patient object. updateDeviceID is the unique identifier for the device that name should be changed.

{
  "updatePatientInfo": "(uuid)",
  "updateDeviceID": "(uuid)",
  "newDeviceName": "(string)",
  "leadAnnotations": "[(string)]"
}

Update Patient Information

updatePatientInfo is the unique identifier for a specific Patient object.

{
  "updatePatientInfo": "(uuid)",
  "FirstName": "(string)",
  "LastName": "(string)",
  "Diagnosis": "(string)",
  "MRN": "(string)",
}

Returns: Response Code 200 if success or 400 if error.

class APIs.UpdateRecordings.BrainSenseStreamUpdate(**kwargs)

Update BrainSense Stream recording information.

Currently only recording contact change is implemented because this is the only information not stored in Percept JSON.

POST: /api/updateBrainSenseStream

Parameters

requestData (uuid) – Device Unique Identifier.
updateRecordingContactType (uuid) – BrainSense Recording Unique Identifier.
contactIndex (int) – Indicate for Left/Right hemisphere.
contactType (string) – Contact Type (Segment, Ring, A/B/C)

Returns

Response Code 200 if success or 400 if error.

class APIs.UpdateRecordings.UpdatePatientAccess(**kwargs)

Update Patient Access Table.

Currently only recording contact change is implemented because this is the only information not stored in Percept JSON.

POST: /api/updatePatientAccess

Parameters

requestData (uuid) – Device Unique Identifier.
updateRecordingContactType (uuid) – BrainSense Recording Unique Identifier.
contactIndex (int) – Indicate for Left/Right hemisphere.
contactType (string) – Contact Type (Segment, Ring, A/B/C)

Returns

Response Code 200 if success or 400 if error.

Upload Module

class APIs.Upload.DeidentificationTable(**kwargs)

class APIs.Upload.SessionUpload(**kwargs)

Upload JSON Session File.

Note

This is the only route in the server that uses MultiPart/Form Parser instead of JSON object.

This is the primary route that allow users to upload Medtronic JSON Session file. Due to read/write conflict, this route currently implemented a simple queue system. Only one file is being processed at a time, meaning that you can batch upload multiple files, but they will still be processed individually to avoid read/write conflict if files belong to the same patient which access the same cache folder and recording file.

POST: /api/uploadSessionFiles

Parameters

file (io) – File object whose content can be read into raw bytes array.
[deviceId] (uuid) – Device Unique Identifier if the uploader is not clinician/admin. this is to ensure deidentified JSON file will be properly organized to their own folder. If deviceId is not provided, the server will attempt to use deidentificationLookupTable to deidentify batch files.

Returns

Response Code 200 if success or 400 if error. Response Body may contain “newPatient” object if a new Patient object is created because the patient information is new.

class APIs.Upload.RequestProcessingQueue(**kwargs)

class APIs.Upload.SessionRemove(**kwargs)

Delete JSON Session File.

User may delete JSON session file and all recordings associated with that JSON session file. This is useful for purging database.

POST: /api/deleteSessionFiles

Parameters

patientId (uuid) – Patient Unique Identifier as provided from QueryPatientList route.
[deletePatient] (bool) – (Optional) Requesting all JSON files associate with a specific patient are to be deleted. This will also delete all devices and patient object entry.
[deleteDevice] (uuid) – (Optional) Requesting all JSON files associate with a specific device are to be deleted. This will also delete one device but not patient object.
[deleteSession] (list) – (Optional) Requesting all JSON files in the list to be deleted.

Returns

Response Code 200 if success or 400 if error. Response Body may contain “newPatient” object if a new Patient object is created because the patient information is new.

class APIs.Upload.ExtractSessionEMR(**kwargs)

Extract EMR from Session JSON File

POST: /api/extractSessionEMR

Parameters

id (uuid) – Patient Unique Identifier as provided from QueryPatientList route.
sessionId (uuid) – Session Unique Identifier as provided from QuerySessionOverview route.

Returns

Response Code 200 if success or 400 if error.

class APIs.Upload.ExternalRecordingUpload(**kwargs)

Upload External Recordings.

Note

This is the only route in the server that uses MultiPart/Form Parser instead of JSON object.

This is the primary route that allow users to upload files that are not Medtronic JSON Session file. External recording should be pre-parsed into CSV file before upload.

POST: /api/uploadSessionFiles

Parameters

file (io) – File object whose content can be read into raw bytes array.
[deviceId] (uuid) – Device Unique Identifier if the uploader is not clinician/admin. this is to ensure deidentified JSON file will be properly organized to their own folder. If deviceId is not provided, the server will attempt to use deidentificationLookupTable to deidentify batch files.

Returns

Response Code 200 if success or 400 if error. Response Body may contain “newPatient” object if a new Patient object is created because the patient information is new.

Survey Module

class APIs.Surveys.AddNewSurvey(**kwargs)

class APIs.Surveys.RequestSurveyAccessCode(**kwargs)

class APIs.Surveys.QuerySurveyResults(**kwargs)

class APIs.Surveys.QueryAvailableSurveys(**kwargs)

class APIs.Surveys.QueryAvailableRedcapSchedule(**kwargs)

class APIs.Surveys.QuerySurveyContent(**kwargs)

class APIs.Surveys.UpdateSurveyContent(**kwargs)

class APIs.Surveys.ArchiveSurvey(**kwargs)

class APIs.Surveys.SubmitSurveyResults(**kwargs)

class APIs.Surveys.RedcapVerification(**kwargs)

class APIs.Surveys.SetupSurveyScheduler(**kwargs)

class APIs.Surveys.SurveySchedulerStatus(**kwargs)