Session API endpoint

One experimental session, described by the behaviors, data acquisition and manipulations that took place in it.

Table of contents

  1. Endpoints
  2. Fields
  3. List
  4. Add
  5. Detail
  6. Change
  7. Delete
  8. Custom actions
  9. JSON field schemas
    1. Additional details
    2. Public repositories
  10. Data model
  11. Usage notes

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 (from project)
  • Uniqueness: name unique across BrainSTEM
  • Deleting: also deletes the linked behavior, dataacquisition, epoch, manipulation 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]
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.
namestring [required]; max 100 characters
descriptionstring; nullable
epochslist of epoch ids [read-only]; nullable; nestable
projectslist of project ids [required]; nestable
date_timedatetime; nullable
session_typeone of subject, specimen [required]. Subject sessions record in-vivo experiments on live animals. Specimen sessions record ex-vivo work on tissue preparations.
subjectslist of subject ids; nestable. Live animal subjects involved in this session. Required for subject-type sessions.
specimen_setslist of specimenset ids; nestable. Ex-vivo tissue preparations involved in this session. Required for specimen-type sessions.
datastoragelist of datastorage ids; nestable
extra_fieldsJSON object
download_linksJSON object
dataacquisitionlist of dataacquisition ids [read-only]; nullable; nestable
behaviorslist of behavior ids [read-only]; nullable; nestable
manipulationslist of manipulation ids [read-only]; nullable; nestable
tagslist of strings; filter with filter{tags.name}=<name>
name_used_in_storagestring; max 200 characters; nullable

List

  • Allowed portals: private, public
  • Request method: GET
  • URL: https://www.brainstem.org/api/private/stem/session/
  • Responses: 200 OK; 401 Not authenticated; 403 Not 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: 201 Created; 400 Bad request (validation errors per field); 403 Not 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: 200 OK; 403 Not allowed; 404 Not 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: 200 OK; 400 Bad request; 403 Not allowed; 404 Not 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: 204 Deleted; 400 Still referenced by other records; 403 Not allowed; 404 Not found

Use example (Python API tool)

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

Use example (MATLAB API tool)

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

Custom actions

ActionRequest
exportGET, POST /api/private/stem/session/<id>/export/
export_jobsGET /api/private/stem/session/<id>/export-jobs/
export_jobGET /api/private/stem/session/<id>/export-jobs/<job_id>/
export_job_downloadGET /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.

PropertyDescription
keytext
valueobject

Illustrative payload:

[
    {
        "key": "text",
        "value": {}
    }
]

Public repositories

  • type code Repository · version 1.0.0 · schema

List public repositories where the data is stored.

PropertyDescription
repositorychoice [required]; one of CRCNS, DANDI, Figshare, GitHub, Globus, Mendeley, Zenodo, Webshare, Other; default "DANDI"
urltext [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 (subject or specimen) is set on create and cannot be changed afterwards. A subject session lists subjects, a specimen session lists specimen_sets.
  • The order of datastorage is kept. To reorder the data storages of an existing session, or to add and remove one, use the Session data storage endpoint, whose order field sets the position.
  • extra_fields is a JSON object whose keys start with a letter and contain only letters, digits and underscores; values are strings or numbers.
  • Each download_links entry is {"repository": <code>, "url": <url>}. The URL must include its scheme (http://, https:// or ftp://); repository codes are listed under Public repositories.