Procedure episode API endpoint

Groups the procedures and welfare logs of one perioperative event, for compliance records.

Table of contents

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

Endpoints

• Private portal: https://www.brainstem.org/api/private/modules/procedureepisode/ (needs a token; one record: append <id>/)
• Public portal: https://www.brainstem.org/api/public/modules/procedureepisode/ (read-only, public projects, no token)
• Response keys: procedure_episode (detail, create, update), procedure_episodes (list)
• Permissions: inherited through subject → projects (from project)
• Deleting: clears the link on procedure 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.

Field	Description
id	UUID string [read-only]
intervention_class	one of anesthesia_only, surgical, non_surgical, euthanasia_tissue_collection, clinical_treatment, other [required]
name	string [required]; max 200 characters
start_date_time	datetime [required]
end_date_time	datetime; nullable
status	one of planned, draft, active, post_op, complete [required]
subject	subject id [required]. The subject this episode is performed on.
protocol	protocol id; nullable
licenses	list of license ids. Regulatory licences covering this episode.
severity	choice (see the list below); nullable. Classified severity. The regulatory or institutional scheme is encoded in the selected value.
recovery_outcome	one of unknown, recovered, ongoing_recovery, non_recovery, planned_terminal, humane_endpoint, unexpected_death, aborted, cancelled [required]. Observed recovery, terminal, endpoint, or cancellation outcome.
description	string; nullable. Narrative covering complications, outcomes, amendments, and other notes.
user	user id [read-only]
personnel	list of episodepersonnel ids [read-only]; nullable; nestable
created_at	datetime [read-only]; nullable
updated_at	datetime [read-only]

• severity choices: eu_2010_63_non_recovery, eu_2010_63_mild, eu_2010_63_moderate, eu_2010_63_severe, uk_aspa_sub_threshold, uk_aspa_non_recovery, uk_aspa_mild, uk_aspa_moderate, uk_aspa_severe, us_iacuc_usda_no_pain_distress, us_iacuc_usda_pain_distress_relieved, us_iacuc_usda_pain_distress_unrelieved, ca_ccac_category_a, ca_ccac_category_b, ca_ccac_category_c, ca_ccac_category_d, ca_ccac_category_e, local_institutional_sub_threshold, local_institutional_non_recovery, local_institutional_mild, local_institutional_moderate, local_institutional_severe, not_applicable

List

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

Use example (Python API tool)

resp = client.load('procedureepisode', load_all=True)
records = resp['procedure_episodes']

Use example (MATLAB API tool)

resp = client.load('procedureepisode', 'load_all', true);
records = resp.procedure_episodes;

Response example

{
    "procedure_episodes": [
        {
            "id": "<id>",
            "intervention_class": "anesthesia_only",
            "name": "Procedure episode 1",
            "start_date_time": "2024-03-22T10:30:00Z",
            "end_date_time": "2024-03-22T10:30:00Z",
            "status": "active",
            "subject": "<subject-id>",
            "protocol": "<protocol-id>",
            "licenses": [
                "<license-id>"
            ],
            "severity": "eu_2010_63_non_recovery",
            "recovery_outcome": "unknown",
            "description": "",
            "user": "<user-id>",
            "personnel": [
                "<episodepersonnel-id>"
            ],
            "created_at": "2024-03-22T10:30:00Z",
            "updated_at": "2024-03-22T10:30:00Z"
        }
    ],
    "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/procedureepisode/
• 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('procedureepisode', data={"intervention_class": "anesthesia_only", "name": "Procedure episode 1", "start_date_time": "2024-03-22T10:30:00Z", "status": "active", "subject": "<subject-id>", "recovery_outcome": "unknown"})
record = resp.json()['procedure_episode']

Use example (MATLAB API tool)

created = client.save(struct('intervention_class', 'anesthesia_only', 'name', 'Procedure episode 1', 'start_date_time', '2024-03-22T10:30:00Z', 'status', 'active', 'subject', '<subject-id>', 'recovery_outcome', 'unknown'), 'procedureepisode');
record = created.procedure_episode;

Detail

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

Use example (Python API tool)

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

Use example (MATLAB API tool)

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

Response example

{
    "procedure_episode": {
        "id": "<id>",
        "intervention_class": "anesthesia_only",
        "name": "Procedure episode 1",
        "start_date_time": "2024-03-22T10:30:00Z",
        "end_date_time": "2024-03-22T10:30:00Z",
        "status": "active",
        "subject": "<subject-id>",
        "protocol": "<protocol-id>",
        "licenses": [
            "<license-id>"
        ],
        "severity": "eu_2010_63_non_recovery",
        "recovery_outcome": "unknown",
        "description": "",
        "user": "<user-id>",
        "personnel": [
            "<episodepersonnel-id>"
        ],
        "created_at": "2024-03-22T10:30:00Z",
        "updated_at": "2024-03-22T10:30:00Z"
    }
}

Change

• Allowed portals: private
• Request method: PATCH
• URL: https://www.brainstem.org/api/private/modules/procedureepisode/<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('procedureepisode', id='<id>', data={"name": "Procedure episode 1 (renamed)"})

Use example (MATLAB API tool)

client.save(struct('id', '<id>', 'name', 'Procedure episode 1 (renamed)'), 'procedureepisode', 'method', 'patch');

Delete

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

Use example (Python API tool)

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

Use example (MATLAB API tool)

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

Data model

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