Procedure API endpoint

Something done to a subject, such as a surgery, an implant or an injection, with fields that depend on its type.

Table of contents

  1. Endpoints
  2. Fields
  3. List
  4. Add
  5. Detail
  6. Change
  7. Delete
  8. Custom actions
  9. Data model

Endpoints

  • Private portal: https://www.brainstem.org/api/private/modules/procedure/ (needs a token; one record: append <id>/)
  • Public portal: https://www.brainstem.org/api/public/modules/procedure/ (read-only, public projects, no token)
  • Response keys: procedure (detail, create, update), procedures (list)
  • Permissions: inherited through subject → projects (from project)
  • Schema payload: type selects a Procedure type; send its fields in details. type_schema_version is set by the server; do not send it.
  • Schema payload: coordinates_system selects a Coordinates type; send its fields in coordinates_details. coordinates_schema_version is set by the server; do not send it.
  • Deleting: also deletes the linked materialusage, procedurelog records

Fields

[required] fields must be sent on create; [read-only] fields are returned but cannot be set. A nestable relation can be traversed in filters (filter{field.other}) and sideloaded with include[]=field.*; other relations can only be compared with ids (filter{field}=<id>). See the query syntax.

FieldDescription
idUUID string [read-only]
typeone of the Procedure types [required]
statusone of planned, performed, cancelled [required]. Planned: prepared but nothing has happened yet. Performed: this record describes what was done. Cancelled: planned and then dropped; kept for the record.
notesstring; max 500 characters; nullable
subjectsubject id [required]; nestable
procedure_episodeprocedureepisode id; nullable. Perioperative episode this procedure belongs to.
performed_byuser id; nullable. Person who physically performed this procedure (may differ from the record creator).
date_timedatetime; nullable
licenseslist of license ids. Licenses authorizing this specific procedure
protocolprotocol id; nullable
equipmentlist of equipment ids
detailsJSON object
target_regionslist of anatomicalregion ids; nestable
coordinates_systemone of the Coordinates types [required]
coordinates_detailsJSON object
updated_atdatetime [read-only]
created_atdatetime [read-only]; nullable
type_schema_versionstring [set by the server]. Schema version for type_json field
coordinates_schema_versionstring [set by the server]. Schema version for coordinates_json field
anatomical_referenceanatomicalreference id; nullable
coordinate_transformcoordinatetransform id; nullable
materialscomputed [read-only]
stagescomputed [read-only]

List

  • Allowed portals: private, public
  • Request method: GET
  • URL: https://www.brainstem.org/api/private/modules/procedure/
  • Responses: 200 OK; 401 Not authenticated; 403 Not allowed

Use example (Python API tool)

resp = client.load('procedure', load_all=True)
records = resp['procedures']

Use example (MATLAB API tool)

resp = client.load('procedure', 'load_all', true);
records = resp.procedures;

Response example

{
    "procedures": [
        {
            "id": "<id>",
            "type": "Analgesic",
            "status": "performed",
            "notes": "",
            "subject": "<subject-id>",
            "procedure_episode": "<procedureepisode-id>",
            "performed_by": "<user-id>",
            "date_time": "2024-03-22T10:30:00Z",
            "licenses": [
                "<license-id>"
            ],
            "protocol": "<protocol-id>",
            "equipment": [
                "<equipment-id>"
            ],
            "details": {
                "...": "see the schema of the selected type"
            },
            "target_regions": [
                "<anatomicalregion-id>"
            ],
            "coordinates_system": "",
            "coordinates_details": {
                "...": "see the schema of the selected type"
            },
            "updated_at": "2024-03-22T10:30:00Z",
            "created_at": "2024-03-22T10:30:00Z",
            "type_schema_version": "set by the server",
            "coordinates_schema_version": "set by the server",
            "anatomical_reference": "<anatomicalreference-id>",
            "coordinate_transform": "<coordinatetransform-id>",
            "materials": null,
            "stages": null
        }
    ],
    "meta": {
        "page": 1,
        "per_page": 100,
        "total_results": 1,
        "total_pages": 1
    }
}

Add

  • Allowed portals: private
  • Request method: POST
  • URL: https://www.brainstem.org/api/private/modules/procedure/
  • Data: JSON object with at least the required fields
  • Responses: 201 Created; 400 Bad request (validation errors per field); 403 Not allowed

Use example (Python API tool)

resp = client.save('procedure', data={"type": "Anesthesia", "status": "performed", "subject": "<subject-id>", "details": {"...": "see the schema of the selected type"}, "coordinates_system": "Stereotaxic_BregmaBrainSurface", "coordinates_details": {"...": "the fields of the selected Coordinates type"}})
record = resp.json()['procedure']

Use example (MATLAB API tool)

created = client.save(struct('type', 'Anesthesia', 'status', 'performed', 'subject', '<subject-id>', 'details', struct(), 'coordinates_system', 'Stereotaxic_BregmaBrainSurface', 'coordinates_details', struct()), 'procedure');  % struct() stands for the fields of the selected type
record = created.procedure;

Detail

  • Allowed portals: private, public
  • Request method: GET
  • URL: https://www.brainstem.org/api/private/modules/procedure/<id>/
  • Responses: 200 OK; 403 Not allowed; 404 Not found

Use example (Python API tool)

resp = client.load('procedure', id='<id>')
record = resp.json()['procedure']

Use example (MATLAB API tool)

out = client.load('procedure', 'id', '<id>');
record = out.procedure;

Response example

{
    "procedure": {
        "id": "<id>",
        "type": "Analgesic",
        "status": "performed",
        "notes": "",
        "subject": "<subject-id>",
        "procedure_episode": "<procedureepisode-id>",
        "performed_by": "<user-id>",
        "date_time": "2024-03-22T10:30:00Z",
        "licenses": [
            "<license-id>"
        ],
        "protocol": "<protocol-id>",
        "equipment": [
            "<equipment-id>"
        ],
        "details": {
            "...": "see the schema of the selected type"
        },
        "target_regions": [
            "<anatomicalregion-id>"
        ],
        "coordinates_system": "",
        "coordinates_details": {
            "...": "see the schema of the selected type"
        },
        "updated_at": "2024-03-22T10:30:00Z",
        "created_at": "2024-03-22T10:30:00Z",
        "type_schema_version": "set by the server",
        "coordinates_schema_version": "set by the server",
        "anatomical_reference": "<anatomicalreference-id>",
        "coordinate_transform": "<coordinatetransform-id>",
        "materials": null,
        "stages": null
    }
}

Change

  • Allowed portals: private
  • Request method: PATCH
  • URL: https://www.brainstem.org/api/private/modules/procedure/<id>/
  • Data: JSON object with the fields to change. Lists (projects, tags, …) and JSON payloads (details, coordinates) are replaced as a whole: read the record first and send the full list or object.
  • Responses: 200 OK; 400 Bad request; 403 Not allowed; 404 Not found

Use example (Python API tool)

resp = client.save('procedure', id='<id>', data={"notes": "new value"})

Use example (MATLAB API tool)

client.save(struct('id', '<id>', 'notes', 'new value'), 'procedure', 'method', 'patch');

Delete

  • Allowed portals: private
  • Request method: DELETE
  • URL: https://www.brainstem.org/api/private/modules/procedure/<id>/
  • Responses: 204 Deleted; 400 Still referenced by other records; 403 Not allowed; 404 Not found

Use example (Python API tool)

resp = client.delete('procedure', id='<id>')

Use example (MATLAB API tool)

client.delete('<id>', 'procedure');

Custom actions

ActionRequest
apply_material_templatePOST /api/private/modules/procedure/<id>/apply-material-template/
coordinate_context_optionsGET /api/private/modules/procedure/coordinate-context-options/
coordinate_previewPOST /api/private/modules/procedure/coordinate-preview/
saved_coordinate_previewGET /api/private/modules/procedure/<id>/coordinate-preview/
material_optionsGET /api/private/modules/procedure/material-options/
materialsGET, PUT /api/private/modules/procedure/<id>/materials/

materials returns the ordered material usage rows of the procedure; PUT replaces them as a whole (a stale list is refused with 409). apply-material-template copies the rows of a material usage template onto the procedure. material-options lists the material roles and allowed sources of a procedure type (?type=<Type>). coordinate-preview renders the saved or posted coordinates in the atlas of the subject’s species.

Data model

The fields are described for the web forms on the Procedure data model page.