Exam Manager

Introduction

The Exam Manager API is designed to manage the complete lifecycle of exams, 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/exam/health/readiness

Readiness

Get status / health endpoint.

Status Codes:

• 200 OK – Successful Response

POST /api/v1/exam/new

Create Exam

Create a new exam.

Parameters

payload

Exam pydantic input model.

Returns

Exam pydantic output moddel.

Raises

HTTPException

404: Creation unsuccessful

status 201:

Successful Response

status 422:

Validation Error

POST /api/v1/exam/

Create Exam From Template

Create a new exam from template.

Parameters

payload

The potentially modified exam to create.

template_id

ID of the template, the exam is created from

Returns

Exam pydantic output model.

Raises

HTTPException

404: Creation unsuccessful

query string template_id:

(Required)

status 201:

Successful Response

status 422:

Validation Error

GET /api/v1/exam/{exam_id}

Get Exam

Get exam endpoint.

Parameters

exam_id

Id of requested exam entry

Returns

Exam pydantic output model.

Raises

HTTPException

404: Not found

param {‘string’, ‘uuid’} exam_id:

status 200:

Successful Response

status 422:

Validation Error

DELETE /api/v1/exam/{exam_id}

Exam Delete

Delete an exam by id. Cascade deletes the associated workflow and tasks.

Parameters

exam_id

Id of the exam to be deleted

Raises

HTTPException

404: Not found

param {‘string’, ‘uuid’} exam_id:

status 204:

Successful Response

status 422:

Validation Error

PUT /api/v1/exam/{exam_id}

Update Exam

Update an existing exam.

Parameters

exam_id

Id of the exam to be updated

payload

Exam pydantic input model

Returns

Exam pydantic output model

Raises

HTTPException

404: Not found

param {‘string’, ‘uuid’} exam_id:

status 200:

Successful Response

status 422:

Validation Error

GET /api/v1/exam/all/{patient_id}

Get All Patient Exams

Get all exams of a certain patient.

Parameters

patient_id

Id of parent

Returns

List of exam pydantic output models

param string patient_id:

status 200:

Successful Response

status 422:

Validation Error

GET /api/v1/exam/templates/all

Get All Exam Templates

Get all exam templates.

Returns

List of exam pydantic output models

status 200:

Successful Response

POST /api/v1/exam/workflow/new

Create Workflow

Create new workflow.

Parameters

payload

Workflow pydantic input model

Returns

Workflow pydantic output model

Raises

HTTPException

404: Creation unsuccessful

status 201:

Successful Response

status 422:

Validation Error

POST /api/v1/exam/workflow

Create Workflow From Template

Create new workflow from template.

Parameters

exam_id

Id of the exam, the workflow is related to

template_id

ID of the template, the workflow is created from

new_workflow_is_template

set the is_template property of the new workflow and its tasks

Returns

Workflow pydantic output model

Raises

HTTPException

404: Creation unsuccessful

query string exam_id:

(Required)

query string template_id:

(Required)

query boolean new_workflow_is_template:

(Required)

status 201:

Successful Response

status 422:

Validation Error

GET /api/v1/exam/workflow/{workflow_id}

Get Workflow

Get a workflow.

Parameters

workflow_id

Id of the workflow to be returned

Returns

Workflow pydantic output model

Raises

HTTPException

404: Not found

param {‘string’, ‘uuid’} workflow_id:

status 200:

Successful Response

status 422:

Validation Error

DELETE /api/v1/exam/workflow/{workflow_id}

Delete Workflow

Delete a workflow. Cascade delete the associated tasks.

Parameters

workflow_id

Id of the workflow to be deleted

Raises

HTTPException

404: Not found

param {‘string’, ‘uuid’} workflow_id:

status 204:

Successful Response

status 422:

Validation Error

PUT /api/v1/exam/workflow/{workflow_id}

Update Workflow

Update an existing workflow.

Parameters

workflow_id

Id of the workflow to be updated

payload

Workflow pydantic indput model

Returns

Workflow pydantic output model

Raises

HTTPException

404: Not found

param {‘string’, ‘uuid’} workflow_id:

status 200:

Successful Response

status 422:

Validation Error

GET /api/v1/exam/workflow/all/{exam_id}

Get All Exam Workflows

Get all existing workflows of a certain exam.

Parameters

exam_id

Id of parent exam

Returns

List of workflow pydantic output model

param {‘string’, ‘uuid’} exam_id:

status 200:

Successful Response

status 422:

Validation Error

GET /api/v1/exam/workflow/templates/all

Get All Workflow Templates

Get all workflow templates.

Returns

List of workflow pydantic output model

status 200:

Successful Response

POST /api/v1/exam/task/new

Create Task

Create a new task.

Parameters

payload

Task pydantic input model

Returns

Task pydantic output model

Raises

HTTPException

404: Creation unsuccessful

status 201:

Successful Response

status 422:

Validation Error

POST /api/v1/exam/task

Create Task From Template

Create a new task from template.

Parameters

workflow_id

ID of the workflow, the task is related to

template_id

ID of the template, the task is created from

new_task_is_template

set the is_template property on the new task

Returns

Task pydantic output model

Raises

HTTPException

404: Creation unsuccessful

query string workflow_id:

(Required)

query string template_id:

(Required)

query boolean new_task_is_template:

(Required)

status 201:

Successful Response

status 422:

Validation Error

GET /api/v1/exam/task/{task_id}

Get Task

Get an existing task.

Parameters

task_id

Id of the task to be returned

Returns

Task pydantic output model

Raises

HTTPException

404: Not found

param {‘string’, ‘uuid’} task_id:

status 200:

Successful Response

status 422:

Validation Error

DELETE /api/v1/exam/task/{task_id}

Delete Task

Delete a task.

Parameters

task_id

Id of the task to be deleted

Raises

HTTPException

404: Not found

param {‘string’, ‘uuid’} task_id:

status 204:

Successful Response

status 422:

Validation Error

PUT /api/v1/exam/task/{task_id}

Update Task

Update an existing task.

Parameters

task_id

Id of the workflow to be updated

payload

Task pydantic base model

Returns

Task pydantic output model

Raises

HTTPException

404: Not found

param {‘string’, ‘uuid’} task_id:

status 200:

Successful Response

status 422:

Validation Error

GET /api/v1/exam/task/all/{workflow_id}

Get All Workflow Tasks

Get all existing tasks of a certain workflow.

Parameters

workflow_id

Id of parental workflow

Returns

List of task pydantic output model

param {‘string’, ‘uuid’} workflow_id:

status 200:

Successful Response

status 422:

Validation Error

GET /api/v1/exam/task/templates/all

Get All Task Templates

Get all existing task templates.

Returns

List of task pydantic output model

status 200:

Successful Response

POST /api/v1/exam/result

Create Blank Result

Create a task result.

Parameters

payload

Result pydantic input model

Returns

Result pydantic output model

Raises

HTTPException

404: Creation unsuccessful

query {‘string’, ‘uuid’} task_id:

(Required)

status 201:

Successful Response

status 422:

Validation Error

GET /api/v1/exam/result/{result_id}

Get Result

Get an existing result.

Parameters

result_id

Id of the result to be returned

Returns

Result pydantic output model

Raises

HTTPException

404: Not found

param {‘string’, ‘uuid’} result_id:

status 200:

Successful Response

status 422:

Validation Error

DELETE /api/v1/exam/result/{result_id}

Delete Result

Delete a task.

Parameters

task_id

Id of the task to be deleted

Raises

HTTPException

404: Not found

param {‘string’, ‘uuid’} result_id:

status 204:

Successful Response

status 422:

Validation Error

PUT /api/v1/exam/result/{result_id}

Set Result

Update an existing result.

Parameters

result_id

Id of the result to be updated

payload

Result pydantic base model/dict If this is the pydantic ResultBase model, only fields in the base model can be updated.

Returns

Task pydantic output model

Raises

HTTPException

404: Not found

param {‘string’, ‘uuid’} result_id:

status 200:

Successful Response

status 422:

Validation Error

GET /api/v1/exam/result/all/{task_id}

Get All Task Results

Get all existing results of a certain task.

Parameters

task_id

Id of parental task

Returns

List of task pydantic output model

param {‘string’, ‘uuid’} task_id:

status 200:

Successful Response

status 422:

Validation Error

GET /api/v1/exam/dcm/{workflow_id}/{task_id}/{result_id}/{filename}

Get DICOM result

Serve a DICOM instance.

• If it’s already a DICOM Part-10 file → return FileResponse (supports HTTP Range).

• Else → convert to Part-10 in memory and return StreamingResponse.

Headers:

• ‘application/dicom’ content type

• inline disposition (avoid forced download)

• ‘Cache-Control: no-transform’ to prevent proxies from gzipping (which breaks Range offsets)

Parameters:

• workflow_id (string)

• task_id (string)

• result_id (string)

• filename (string)

Status Codes:

• 200 OK – Successful Response

• 422 Unprocessable Entity – Validation Error

GET /api/v1/exam/mrd/{workflow_id}/{task_id}/{result_id}/meta

Get ISMRMRD metadata (indexed acquisitions)

Get MRD meta info.

Parameters:

• workflow_id (string)

• task_id (string)

• result_id (string)

Status Codes:

• 200 OK – Successful Response

• 422 Unprocessable Entity – Validation Error

GET /api/v1/exam/mrd/{workflow_id}/{task_id}/{result_id}/data

Get MRD (binary, interleaved float32 complex)

Get MRD as binary stream.

Parameters:

• workflow_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:

• 200 OK – Binary packet stream with a tiny header + payload(s).

• 422 Unprocessable Entity – Validation Error

GET /api/v1/exam/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/exam/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/exam/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/exam/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/exam/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/exam/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/exam/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

Exam 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.