Material usage API endpoint

One material used in a procedure, such as a drug, a virus or a probe, with its amount and its source.

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/materialusage/ (needs a token; one record: append <id>/)
• Public portal: https://www.brainstem.org/api/public/modules/materialusage/ (read-only, public projects, no token)
• Response keys: materialusage (detail, create, update), materialusages (list)
• Permissions: inherited through procedure.subject.projects or specimen_procedure.specimen_set.projects or experimental_interface.subject.projects or experimental_interface.specimen_set.projects (from project)
• Schema payload: type selects a MaterialUsage type; send its fields in details_json (responses return them as details). details_schema_version is set by the server; do not send it.
• Deleting: clears the link on experimentalinterface records

Form-only inputs (sent on create or update, not returned in responses):

• source [required]. Choices: inventory, catalog, manual. Choose a consumable stock, a consumable, or enter the identity manually.

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]
procedure	procedure id; nullable
specimen_procedure	specimenprocedure id; nullable
experimental_interface	experimentalinterface id; nullable. The interface this material is part of. An interface records what it is made of the same way a procedure records what it used.
consumable_stock	consumablestock id; nullable
consumable	consumable id; nullable
manual_source	JSON object [write-only]
type	one of the MaterialUsage types [required]
stage	modules.procedurestage id; nullable. The ordered stage of the parent procedure this material took part in, when the parent type declares stages.
order	number [required]
details	JSON object [read-only]
target_specimens	list of strings [write-only]
notes	string; max 500 characters
details_schema_version	string [set by the server]
source_provenance	computed [read-only]
source_tier	computed [read-only]
source_tier_display	computed [read-only]
source_identity	computed [read-only]
summary	computed [read-only]
copied_from_procedure	computed [read-only]
created_at	datetime [read-only]; nullable
updated_at	datetime [read-only]
user	user id [read-only]

List

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

Use example (Python API tool)

resp = client.load('materialusage', load_all=True)
records = resp['materialusages']

Use example (MATLAB API tool)

resp = client.load('materialusage', 'load_all', true);
records = resp.materialusages;

Response example

{
    "materialusages": [
        {
            "id": "<id>",
            "procedure": "<procedure-id>",
            "specimen_procedure": "<specimenprocedure-id>",
            "experimental_interface": "<experimentalinterface-id>",
            "consumable_stock": "<consumablestock-id>",
            "consumable": "<consumable-id>",
            "type": "SiliconProbe",
            "stage": "<procedurestage-id>",
            "order": 1,
            "details": {
                "...": "see the schema of the selected type"
            },
            "notes": "",
            "details_schema_version": "set by the server",
            "source_provenance": null,
            "source_tier": null,
            "source_tier_display": null,
            "source_identity": null,
            "summary": null,
            "copied_from_procedure": null,
            "created_at": "2024-03-22T10:30:00Z",
            "updated_at": "2024-03-22T10:30:00Z",
            "user": "<user-id>"
        }
    ],
    "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/materialusage/
• 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('materialusage', data={"type": "ActiveAgent", "order": 1, "details_json": {"...": "the fields of the selected MaterialUsage type"}, "source": "inventory", "procedure": "<procedure-id>", "consumable_stock": "<consumablestock-id>"})
record = resp.json()['materialusage']

Use example (MATLAB API tool)

created = client.save(struct('type', 'ActiveAgent', 'order', 1, 'details_json', struct(), 'source', 'inventory', 'procedure', '<procedure-id>', 'consumable_stock', '<consumablestock-id>'), 'materialusage');  % struct() stands for the fields of the selected type
record = created.materialusage;

Detail

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

Use example (Python API tool)

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

Use example (MATLAB API tool)

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

Response example

{
    "materialusage": {
        "id": "<id>",
        "procedure": "<procedure-id>",
        "specimen_procedure": "<specimenprocedure-id>",
        "experimental_interface": "<experimentalinterface-id>",
        "consumable_stock": "<consumablestock-id>",
        "consumable": "<consumable-id>",
        "type": "SiliconProbe",
        "stage": "<procedurestage-id>",
        "order": 1,
        "details": {
            "...": "see the schema of the selected type"
        },
        "notes": "",
        "details_schema_version": "set by the server",
        "source_provenance": null,
        "source_tier": null,
        "source_tier_display": null,
        "source_identity": null,
        "summary": null,
        "copied_from_procedure": null,
        "created_at": "2024-03-22T10:30:00Z",
        "updated_at": "2024-03-22T10:30:00Z",
        "user": "<user-id>"
    }
}

Change

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

Use example (MATLAB API tool)

client.save(struct('id', '<id>', 'order', 1), 'materialusage', 'method', 'patch');

Delete

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

Use example (Python API tool)

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

Use example (MATLAB API tool)

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

Data model

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