Subject log API endpoint

Records followed over time for one subject, such as weight, food and water, or housing.

Table of contents

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

Endpoints

• Private portal: https://www.brainstem.org/api/private/modules/subjectlog/ (needs a token; one record: append <id>/)
• Public portal: https://www.brainstem.org/api/public/modules/subjectlog/ (read-only, public projects, no token)
• Response keys: subject_log (detail, create, update), subject_logs (list)
• Permissions: inherited through subject → projects (from project)
• Entry schemas: type selects a SubjectLog type; each log entry is validated against it.

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]
type	one of the SubjectLog types [required]
description	string; max 500 characters; nullable
subject	subject id [required]; nestable
protocol	protocol id; nullable; nestable
user	user id [read-only]
entries	computed [read-only]

List

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

Use example (Python API tool)

resp = client.load('subjectlog', load_all=True)
records = resp['subject_logs']

Use example (MATLAB API tool)

resp = client.load('subjectlog', 'load_all', true);
records = resp.subject_logs;

Response example

{
    "subject_logs": [
        {
            "id": "<id>",
            "type": "FoodConsumption",
            "description": "",
            "subject": "<subject-id>",
            "protocol": "<protocol-id>",
            "user": "<user-id>",
            "entries": 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/subjectlog/
• 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('subjectlog', data={"type": "FoodConsumption", "subject": "<subject-id>"})
record = resp.json()['subject_log']

Use example (MATLAB API tool)

created = client.save(struct('type', 'FoodConsumption', 'subject', '<subject-id>'), 'subjectlog');
record = created.subject_log;

Detail

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

Use example (Python API tool)

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

Use example (MATLAB API tool)

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

Response example

{
    "subject_log": {
        "id": "<id>",
        "type": "FoodConsumption",
        "description": "",
        "subject": "<subject-id>",
        "protocol": "<protocol-id>",
        "user": "<user-id>",
        "entries": null
    }
}

Change

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

Use example (MATLAB API tool)

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

Delete

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

Use example (Python API tool)

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

Use example (MATLAB API tool)

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

Custom actions

Action	Request
add_entry	PATCH /api/private/modules/subjectlog/<id>/add_entry/
change_entry	PATCH /api/private/modules/subjectlog/<id>/change_entry/
remove_entry	PATCH /api/private/modules/subjectlog/<id>/remove_entry/

Log entries are edited through the actions: add_entry appends an entry validated against the log type’s schema, change_entry replaces one entry and remove_entry deletes it.

Data model

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

Usage notes

• entries holds the log’s entries, each an object such as {"date_time": "2026-03-14T10:06:58Z", "details": {...}, "notes": null, "performedBy": <user id>}. details follows the schema of the log’s type. Duration-based logs (housing, deprivation, habituation, handling and training) record a start and an end time instead of a single time. Add, change and remove entries with the add_entry, change_entry and remove_entry custom actions.