Session API endpoint
One experimental session, described by the behaviors, data acquisition and manipulations that took place in it.
Table of contents
Endpoints
- Private portal:
https://www.brainstem.org/api/private/stem/session/(needs a token; one record: append<id>/) - Public portal:
https://www.brainstem.org/api/public/stem/session/(read-only, public projects, no token) - Response keys:
session(detail, create, update),sessions(list) - Permissions: inherited through
projects(fromproject) - Uniqueness:
nameunique across BrainSTEM - Deleting: also deletes the linked
behavior,dataacquisition,epoch,manipulationrecords
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] |
status | one 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. |
name | string [required]; max 100 characters |
description | string; nullable |
epochs | list of epoch ids [read-only]; nullable; nestable |
projects | list of project ids [required]; nestable |
date_time | datetime; nullable |
session_type | one of subject, specimen [required]. Subject sessions record in-vivo experiments on live animals. Specimen sessions record ex-vivo work on tissue preparations. |
subjects | list of subject ids; nestable. Live animal subjects involved in this session. Required for subject-type sessions. |
specimen_sets | list of specimenset ids; nestable. Ex-vivo tissue preparations involved in this session. Required for specimen-type sessions. |
datastorage | list of datastorage ids; nestable |
extra_fields | JSON object |
download_links | JSON object |
dataacquisition | list of dataacquisition ids [read-only]; nullable; nestable |
behaviors | list of behavior ids [read-only]; nullable; nestable |
manipulations | list of manipulation ids [read-only]; nullable; nestable |
tags | list of strings; filter with filter{tags.name}=<name> |
name_used_in_storage | string; max 200 characters; nullable |
List
- Allowed portals: private, public
- Request method: GET
- URL:
https://www.brainstem.org/api/private/stem/session/ - Responses:
200OK;401Not authenticated;403Not allowed
Use example (Python API tool)
resp = client.load('session', load_all=True)
records = resp['sessions']
Use example (MATLAB API tool)
resp = client.load('session', 'load_all', true);
records = resp.sessions;
Response example
{
"sessions": [
{
"id": "<id>",
"status": "performed",
"name": "Session 1",
"description": "",
"epochs": [
"<epoch-id>"
],
"projects": [
"<project-id>"
],
"date_time": "2024-03-22T10:30:00Z",
"session_type": "subject",
"subjects": [
"<subject-id>"
],
"specimen_sets": [
"<specimenset-id>"
],
"datastorage": [
"<datastorage-id>"
],
"extra_fields": {},
"download_links": {},
"dataacquisition": [
"<dataacquisition-id>"
],
"behaviors": [
"<behavior-id>"
],
"manipulations": [
"<manipulation-id>"
],
"tags": [],
"name_used_in_storage": ""
}
],
"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/stem/session/ - Data: JSON object with at least the required fields
- Responses:
201Created;400Bad request (validation errors per field);403Not allowed
Use example (Python API tool)
resp = client.save('session', data={"status": "performed", "name": "Session 1", "projects": ["<project-id>"], "session_type": "subject", "subjects": ["<subject-id>"]})
record = resp.json()['session']
Use example (MATLAB API tool)
created = client.save(struct('status', 'performed', 'name', 'Session 1', 'projects', {{'<project-id>'}}, 'session_type', 'subject', 'subjects', {{'<subject-id>'}}), 'session');
record = created.session;
Detail
- Allowed portals: private, public
- Request method: GET
- URL:
https://www.brainstem.org/api/private/stem/session/<id>/ - Responses:
200OK;403Not allowed;404Not found
Use example (Python API tool)
resp = client.load('session', id='<id>')
record = resp.json()['session']
Use example (MATLAB API tool)
out = client.load('session', 'id', '<id>');
record = out.session;
Response example
{
"session": {
"id": "<id>",
"status": "performed",
"name": "Session 1",
"description": "",
"epochs": [
"<epoch-id>"
],
"projects": [
"<project-id>"
],
"date_time": "2024-03-22T10:30:00Z",
"session_type": "subject",
"subjects": [
"<subject-id>"
],
"specimen_sets": [
"<specimenset-id>"
],
"datastorage": [
"<datastorage-id>"
],
"extra_fields": {},
"download_links": {},
"dataacquisition": [
"<dataacquisition-id>"
],
"behaviors": [
"<behavior-id>"
],
"manipulations": [
"<manipulation-id>"
],
"tags": [],
"name_used_in_storage": ""
}
}
Change
- Allowed portals: private
- Request method: PATCH
- URL:
https://www.brainstem.org/api/private/stem/session/<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:
200OK;400Bad request;403Not allowed;404Not found
Use example (Python API tool)
resp = client.save('session', id='<id>', data={"name": "Session 1 (renamed)"})
Use example (MATLAB API tool)
client.save(struct('id', '<id>', 'name', 'Session 1 (renamed)'), 'session', 'method', 'patch');
Delete
- Allowed portals: private
- Request method: DELETE
- URL:
https://www.brainstem.org/api/private/stem/session/<id>/ - Responses:
204Deleted;400Still referenced by other records;403Not allowed;404Not found
Use example (Python API tool)
resp = client.delete('session', id='<id>')
Use example (MATLAB API tool)
client.delete('<id>', 'session');
Custom actions
| Action | Request |
|---|---|
export | GET, POST /api/private/stem/session/<id>/export/ |
export_jobs | GET /api/private/stem/session/<id>/export-jobs/ |
export_job | GET /api/private/stem/session/<id>/export-jobs/<job_id>/ |
export_job_download | GET /api/private/stem/session/<id>/export-jobs/<job_id>/download/ |
export returns the session with everything it touches as versioned JSON (see Exports); POST starts a background export job.
JSON field schemas
Schemas for the additional fields and repository links of a session. The REST API returns these JSON fields as stored and validates writes against the schemas below. Every version is published at https://www.brainstem.org/schemas/Session/<Type>/<version>.json and never changes; see Public schemas.
Additional details
- type code
Array· version 1.0.0 · schema
Any extra parameters you want to add to your session. Saved as key-value pairs. Values can be strings or numbers.
| Property | Description |
|---|---|
key | text |
value | object |
Illustrative payload:
[
{
"key": "text",
"value": {}
}
]
Public repositories
- type code
Repository· version 1.0.0 · schema
List public repositories where the data is stored.
| Property | Description |
|---|---|
repository | choice [required]; one of CRCNS, DANDI, Figshare, GitHub, Globus, Mendeley, Zenodo, Webshare, Other; default "DANDI" |
url | text [required]; format url |
Illustrative payload:
[
{
"repository": "CRCNS",
"url": "text"
}
]
Data model
The fields are described for the web forms on the Session data model page.
Usage notes
session_type(subjectorspecimen) is set on create and cannot be changed afterwards. A subject session listssubjects, a specimen session listsspecimen_sets.- The order of
datastorageis kept. To reorder the data storages of an existing session, or to add and remove one, use the Session data storage endpoint, whoseorderfield sets the position. extra_fieldsis a JSON object whose keys start with a letter and contain only letters, digits and underscores; values are strings or numbers.- Each
download_linksentry is{"repository": <code>, "url": <url>}. The URL must include its scheme (http://,https://orftp://); repository codes are listed under Public repositories.