Session API endpoint

Table of contents

  1. Fields
  2. List view
  3. Add
  4. Detail
  5. Change
  6. Delete

Fields

FieldDescription
idUUID identificator formatted as a string
namestring [required] [max length: 100; must be unique]
descriptionstring
projectslist of related project IDs formatted as strings [required; at least one]
date_timeISO 8601 date-time string (e.g. "2023-03-22T15:30:00Z")
epochslist of related epoch IDs formatted as strings [read-only]
datastoragelist of related data storage IDs formatted as strings (create/update accepts a list; use the Session → Data Storage endpoint to manage ordering)
extra_fieldsJSON object of additional key/value metadata. See structure below
download_linkslist of JSON objects with repository and url keys. See structure below
dataacquisitionlist of related data acquisition IDs formatted as strings [read-only]
behaviorslist of related behaviors IDs formatted as strings [read-only]
manipulationslist of related manipulations IDs formatted as strings [read-only]
name_used_in_storagestring [read-only] [max length: 200]
tagslist of strings

Use the Session → Data Storage endpoint (/api/private/stem/sessiondatastorage/) to add, remove, or reorder data storage associations. Session responses return datastorage IDs in the through-table order saved via this endpoint. You can include a datastorage list in Session POST/PATCH payloads (with the required permissions); use the dedicated endpoint when you need to control ordering explicitly.

name_used_in_storage is returned for display purposes but is not writable through the Session API.

extra_fields is a JSON object where each key/value pair captures additional metadata. Keys must start with a letter and can only contain letters, numbers, and underscores. Values can be strings or numeric values.

{
    "extra_property": "setting1",
    "another_property": 22
}

download_links is a list of JSON objects with two elements, repository and url, like the following example:

[
    {"repository": "DANDI", "url": "https://dandiarchive.org/dandiset/123456?pos=1"},
    {"repository": "GitHub", "url": "https://github.com/my_user/my_code"}
]
  • Allowed repository values: CRCNS, DANDI, Figshare, GitHub, Globus, Mendeley, Zenodo, Webshare, or Other.
  • Each url must already include a supported scheme (http://, https://, or ftp://). Requests missing a scheme are rejected.

List view

Example request (list, Python API)

resp = client.load_model("session")

Example response (list)

{
    "sessions": [
        {
            "id": "1a827c68-19b4-4cec-8ae5-e13c8f1de900",
            "name": "session1",
            "description": "",
            "epochs": [],
            "projects": ["c4b8a90b-2963-4d13-aa07-b6f497252dde"],
            "date_time": null,
            "datastorage": [],
            "extra_fields": {},
            "download_links": [],
            "dataacquisition": [],
            "behaviors": [],
            "manipulations": ["20387176-5f3c-433a-8bf9-34a0f2c431f7"],
            "tags": [],
        },
        {
            "id": "d8e72f9d-eb25-4280-a241-3317d5914055",
            "name": "session2",
            "description": "",
            "epochs": [],
            "projects": ["c4b8a90b-2963-4d13-aa07-b6f497252dde"],
            "date_time": null,
            "datastorage": [],
            "extra_fields": {},
            "download_links": [],
            "dataacquisition": ["1c77ae53-6f83-4398-bfe5-6eb95ff00610"],
            "behaviors": [],
            "manipulations": [],
            "tags": [],
        }
    ]
}

Add

  • Allowed portals: private
  • Request method: POST
  • URL: https://www.brainstem.org/api/private/stem/session
  • Data: JSON dictionary containing at least the required fields. Callers must have change_project permission for each project and change_datastorage for each data storage referenced.
  • Responses: 201 OK; 400 Bad request; 403 Not allowed; 404 Not found

Example request (create, Python API)

resp = client.save_model(
    "session",
    data={
        "name": "NewSession",
        "description": "some text",
        "projects": ["c4b8a90b-2963-4d13-aa07-b6f497252dde"],
    },
)

Example response (create)

{
    "session": {
        "id": "13bdd793-86d4-428e-9708-167bbc26f6d2",
        "name": "NewSession",
        "description": "some text",
        "epochs": [],
        "projects": ["c4b8a90b-2963-4d13-aa07-b6f497252dde"],
        "date_time": null,
        "datastorage": [],
        "extra_fields": {},
        "download_links": [],
        "dataacquisition": [],
        "behaviors": [],
        "manipulations": [],
        "tags": [],
    }
}

Detail

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

Example request (detail, Python API)

resp = client.load_model("session", id="13bdd793-86d4-428e-9708-167bbc26f6d2")

Example response (detail)

{
    "session": {
        "id": "13bdd793-86d4-428e-9708-167bbc26f6d2",
        "name": "NewSession",
        "description": "some text",
        "epochs": [],
        "projects": ["c4b8a90b-2963-4d13-aa07-b6f497252dde"],
        "date_time": null,
        "datastorage": [],
        "extra_fields": {
            "extra_property": "setting1",
            "another_property": 22
        },
        "download_links": [
            {"repository": "DANDI", "url": "https://dandiarchive.org/dandiset/123456?pos=1"},
            {"repository": "GitHub", "url": "https://github.com/my_user/my_code"}
        ],
        "dataacquisition": [],
        "behaviors": [],
        "manipulations": [],
        "tags": [],
    }
}

Change

  • Allowed portals: private
  • Request method: PATCH
  • URL: https://www.brainstem.org/api/private/stem/session/<id>/
  • Data: dictionary containing the fields to be updated. Callers must have change_project permission for each project and change_datastorage for each data storage referenced.
  • Responses: 200 OK; 400 Bad request; 403 Not allowed; 404 Not found

Example request (update, Python API)

resp = client.save_model(
    "session",
    id="13bdd793-86d4-428e-9708-167bbc26f6d2",
    data={"description": "new text"},
)

Example response (update)

{
    "session": {
        "id": "13bdd793-86d4-428e-9708-167bbc26f6d2",
        "name": "NewSession",
        "description": "new text",
        "epochs": [],
        "projects": ["c4b8a90b-2963-4d13-aa07-b6f497252dde"],
        "date_time": null,
        "datastorage": [],
        "extra_fields": {},
        "download_links": [],
        "dataacquisition": [],
        "behaviors": [],
        "manipulations": [],
        "tags": [],
    }
}

Delete

  • Allowed portals: private
  • Request method: DELETE
  • URL: https://www.brainstem.org/api/private/stem/session/<id>/
  • Data: None
  • Responses: 204 OK; 403 Not allowed; 404 Not found

Example request (delete, Python API)

resp = client.delete_model("session", id="13bdd793-86d4-428e-9708-167bbc26f6d2")