Protocol Manager#

Introduction#

The Protocol Manager API is designed to manage the complete lifecycle of protocols, procedures, jobs, and records within the healthcare system. This comprehensive API allows users to perform essential operations on these entities and offers the following key endpoints:

Web API#

GET /api/v1/protocol/health/readiness#

Readiness

Get status / health endpoint.

Status Codes:

  • 200 OK – Successful Response

POST /api/v1/protocol/new#

Create Protocol

Create a new protocol.

Status Codes:
POST /api/v1/protocol/#

Create Protocol From Template

Create a new protocol from template.

Query Parameters:

  • template_id (string) – (Required)

Status Codes:
GET /api/v1/protocol/{exam_id}#

Get Protocol

Get protocol endpoint.

Parameters:

  • exam_id ({'uuid', 'string'})

Status Codes:
DELETE /api/v1/protocol/{exam_id}#

Protocol Delete

Delete a protocol by id. Cascade deletes the associated tasks.

Parameters:

  • exam_id ({'uuid', 'string'})

Status Codes:
PUT /api/v1/protocol/{exam_id}#

Update Protocol

Update an existing protocol.

Parameters:

  • exam_id ({'uuid', 'string'})

Status Codes:
GET /api/v1/protocol/all/{patient_id}#

Get All Patient Protocols

Get all protocols of a certain patient.

Parameters:

  • patient_id (string)

Status Codes:
GET /api/v1/protocol/templates/all#

Get All Protocol Templates

Get all protocol templates.

Status Codes:

  • 200 OK – Successful Response

POST /api/v1/protocol/task/new#

Create Task

Create a new acquisition task.

Status Codes:
POST /api/v1/protocol/task#

Create Task From Template

Create a new acquisition task from a template.

Query Parameters:

  • protocol_id (string) – (Required)

  • template_id (string) – (Required)

  • new_task_is_template (boolean) – (Required)

Status Codes:
GET /api/v1/protocol/task/{task_id}#

Get Task

Get an existing task.

Parameters:

  • task_id ({'uuid', 'string'})

Status Codes:
DELETE /api/v1/protocol/task/{task_id}#

Delete Task

Delete a task.

Parameters:

  • task_id ({'uuid', 'string'})

Status Codes:
PUT /api/v1/protocol/task/{task_id}#

Update Task

Update an existing task.

Parameters:

  • task_id ({'uuid', 'string'})

Status Codes:
GET /api/v1/protocol/task/all/{protocol_id}#

Get All Protocol Tasks

Get all tasks of a protocol.

Parameters:

  • protocol_id ({'uuid', 'string'})

Status Codes:
GET /api/v1/protocol/task/templates/all#

Get All Task Templates

Get all task templates.

Status Codes:

  • 200 OK – Successful Response

PUT /api/v1/protocol/task/reorder#

Reorder Tasks

Reorder tasks by updating their position.

Status Codes:
PUT /api/v1/protocol/task/{task_id}/status#

Update Task Status

Update only the status of a task (called by Dagster sensors).

Parameters:

  • task_id ({'uuid', 'string'})

Query Parameters:

  • status (string) – (Required)

Status Codes:
POST /api/v1/protocol/result/dicom/{task_id}#

Create Dicom Result

Create a DICOM result entry after a successful Dagster reconstruction run.

Parameters:

  • task_id ({'uuid', 'string'})

Status Codes:
POST /api/v1/protocol/result#

Create Blank Result

Create a blank task result.

Query Parameters:

  • task_id ({'uuid', 'string'}) – (Required)

Status Codes:
GET /api/v1/protocol/result/{result_id}#

Get Result

Get an existing result.

Parameters:

  • result_id ({'uuid', 'string'})

Status Codes:
DELETE /api/v1/protocol/result/{result_id}#

Delete Result

Delete a result.

Parameters:

  • result_id ({'uuid', 'string'})

Status Codes:
PUT /api/v1/protocol/result/{result_id}#

Set Result

Update an existing result.

Parameters:

  • result_id ({'uuid', 'string'})

Status Codes:
GET /api/v1/protocol/result/all/{task_id}#

Get All Task Results

Get all existing results of a certain task.

Parameters:

  • task_id ({'uuid', 'string'})

Status Codes:
GET /api/v1/protocol/dcm/{protocol_id}/{task_id}/{result_id}/{filename}#

Get DICOM result

Serve a DICOM instance.

Parameters:

  • protocol_id (string)

  • task_id (string)

  • result_id (string)

  • filename (string)

Status Codes:
POST /api/v1/protocol/xnat/upload/{protocol_id}/{task_id}/{result_id}/{filename}#

Upload DICOM result to XNAT

Upload a DICOM file to XNAT test database.

Parameters:

  • protocol_id (string)

  • task_id (string)

  • result_id (string)

  • filename (string)

Status Codes:
GET /api/v1/protocol/mrd/{protocol_id}/{task_id}/{result_id}/meta#

Get ISMRMRD metadata (indexed acquisitions)

Get MRD meta info.

Parameters:

  • protocol_id (string)

  • task_id (string)

  • result_id (string)

Status Codes:
GET /api/v1/protocol/mrd/{protocol_id}/{task_id}/{result_id}/data#

Get MRD (binary, interleaved float32 complex)

Get MRD as binary stream.

Parameters:

  • protocol_id (string)

  • task_id (string)

  • result_id (string)

Query Parameters:

  • ids (string) – IDs: ‘0,1,10-20,40-50:2’ (Required)

  • coil_idx (integer) – Coil index

  • stride (integer) – Decimate samples by stride

Status Codes:
GET /api/v1/protocol/mrd/{protocol_id}/{task_id}/{result_id}/download#

Download MRD file

Download the full MRD file.

Parameters:

  • protocol_id (string)

  • task_id (string)

  • result_id (string)

Status Codes:
GET /api/v1/protocol/sequence/{sequence_id}#

Get Mri Sequence By Id

Retrieve an MRI sequence by its ID.

Parameters#

sequence_idstr

The ID of the MRI sequence to retrieve.

databaseAsyncIOMotorDatabase

The MongoDB database handle.

Returns#

MRISequence

The retrieved MRI sequence.

param string sequence_id:

status 200:

Successful Response

status 422:

Validation Error

PUT /api/v1/protocol/sequence/{sequence_id}#

Update Mri Sequence Endpoint

Update an MRI sequence with new data.

Parameters#

sequence_idstr

The ID of the MRI sequence to update.

mri_sequenceMRISequence

The updated MRI sequence data.

databaseAsyncIOMotorDatabase

The MongoDB database handle.

Returns#

MRISequence

The updated MRI sequence.

param string sequence_id:

status 200:

Successful Response

status 422:

Validation Error

DELETE /api/v1/protocol/sequence/{sequence_id}#

Delete Mri Sequence Endpoint

Delete an MRI sequence by its ID.

Parameters#

sequence_idstr

The ID of the MRI sequence to delete.

databaseAsyncIOMotorDatabase

The MongoDB database handle.

Returns#

None

param string sequence_id:

status 202:

Successful Response

status 422:

Validation Error

POST /api/v1/protocol/sequence#

Create Mri Sequence

Upload an MRI sequence file and store it with the provided metadata.

Parameters#

mri_sequenceMRISequenceCreate

The MRI sequence metadata.

seq_fileUploadFile

The MRI sequence file to store.

xml_fileUploadFile

The ISMRMRD header xml file to store.

databaseAsyncIOMotorDatabase

The MongoDB database handle.

Returns#

MRISequence

The stored MRI sequence with the uploaded file.

status 201:

Successful Response

status 422:

Validation Error

GET /api/v1/protocol/sequences/all#

Get All Mri Sequences

Retrieve a list of all MRI sequences from the database.

Parameters#

databaseAsyncIOMotorDatabase

The MongoDB database handle.

Returns#

List[MRISequence]

The list of MRI sequences.

status 200:

Successful Response

GET /api/v1/protocol/sequence/{sequence_id}/file#

Get Mri Sequence File By Id

Retrieve an MRI sequence file by its ID.

Parameters#

sequence_idstr

The ID of the MRI sequence to retrieve.

background_tasksBackgroundTasks

The background tasks to run.

namestr

The name of the file to download.

databaseAsyncIOMotorDatabase

The MongoDB database handle.

Returns#

FileResponse

The retrieved MRI sequence file.

param string sequence_id:

query string name:

status 200:

Successful Response

status 422:

Validation Error

GET /api/v1/protocol/sequence/{sequence_id}/header#

Get Mri Sequence Header File By Id

Retrieve an MRI sequence header (ISMRMRD header) file by its ID.

Parameters#

sequence_idstr

The ID of the MRI sequence to retrieve.

background_tasksBackgroundTasks

The background tasks to run.

namestr

The name of the file to download.

databaseAsyncIOMotorDatabase

The MongoDB database handle.

Returns#

FileResponse

The retrieved MRI sequence file.

param string sequence_id:

query string name:

status 200:

Successful Response

status 422:

Validation Error

License#

Protocol Manager, including all its source code and associated documentation (collectively, the “Software”), is dual-licensed under the GNU General Public License version 3 (GPLv3) and the ScanHub commercial license.

Open Source License#

If you want to use the Software under the terms of the GPLv3, you may do so for free. Under the GPLv3, you are allowed to modify and distribute the Software, but any derivative works that you distribute must also be licensed under the GPLv3. For the precise terms and conditions, please refer to the text of the GPLv3, which is included with the Software and can also be found at: http://www.gnu.org/licenses/gpl-3.0.html

Commercial License#

If you wish to use the Software without the restrictions of the GPLv3, such as for the purpose of developing proprietary software that includes the Software without the obligation to disclose your source code, you may purchase a commercial license from BRAIN-LINK UG (haftungsbeschränkt).

The commercial license grants you, the licensee, the rights to use, modify, and distribute the Software without the requirement of providing the source code of your proprietary software to the end users. The commercial license also includes access to premium support and services.

For more information on the commercial license, including pricing, please contact us at info@brain-link.de.

Choice of License#

You may choose to use the Software under either the GPLv3 or the commercial license. If you choose to use the Software under the GPLv3, you must comply with all of the terms of the GPLv3. If you choose to use the Software under the commercial license, you must comply with all of the terms of the commercial license.

Disclaimer#

This is not a legal document. The exact terms of the GPLv3 and the commercial license are specified in their respective legal texts. This document is merely intended to provide a general overview of the dual licensing scheme.