Subject API endpoint

Table of contents

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

Fields

Field	Description
id	UUID identificator formatted as a string
name	string [required for POST; optional for PATCH] [max length: 100; must be unique]
description	string
projects	list of related project IDs formatted as strings [required; at least one]
licenses	list of related license IDs formatted as strings
strain	strain ID formatted as a string [required]
sex	string with "F", "M", or "U" [required for POST; optional for PATCH] [max length: 1]
genetic_line	string [max length: 100]
genotype	string [max length: 200]
subject_identifier	string [max length: 100]
supplier	supplier ID formatted as a string
breeding	breeding ID formatted as a string
birth_date	string containing date (e.g. "2023-03-22")
death_date	string containing date (e.g. "2023-03-22")
status	subject lifecycle status string (e.g. "active")
extra_fields	JSON object of additional key/value metadata. See structure below
procedures	list of related procedures IDs formatted as strings [read-only]
subjectlogs	list of related subject log IDs formatted as strings [read-only]
name_used_in_storage	string [max length: 200]
tags	list of strings
links	object containing related endpoint suffixes [read-only]

extra_fields is a JSON object where each key/value pair captures additional metadata for the subject. 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
}

List view

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

Use example (using Python API)

resp = client.load_model('subject')

Response example

{
    "subjects": [
        {
            "id": "00000000-0000-0000-0000-000000000000",
            "name": "subject1",
            "description": "",
            "projects": ["00000000-0000-0000-0000-000000000000"],
            "strain": "00000000-0000-0000-0000-000000000000",
            "sex": "M",
            "genetic_line": "",
            "genotype": "",
            "subject_identifier": "",
            "licenses": [],
            "supplier": null,
            "birth_date": "2023-03-22",
            "death_date": null,
            "status": "active",
            "extra_fields": {},
            "procedures": ["00000000-0000-0000-0000-000000000000"],
            "subjectlogs": [],
            "tags": [],
            "links": {
                "procedures": "procedures/",
                "subjectlogs": "subjectlogs/"
            },
            "name_used_in_storage": null,
        },
        {
            "id": "00000000-0000-0000-0000-000000000000",
            "name": "subject2",
            "description": "",
            "projects": ["00000000-0000-0000-0000-000000000000"],
            "strain": "00000000-0000-0000-0000-000000000000",
            "sex": "M",
            "genetic_line": "",
            "genotype": "",
            "subject_identifier": "",
            "licenses": [],
            "supplier": null,
            "birth_date": null,
            "death_date": null,
            "status": "active",
            "extra_fields": {},
            "procedures": [
                "00000000-0000-0000-0000-000000000000",
                "00000000-0000-0000-0000-000000000000",
                "00000000-0000-0000-0000-000000000000",
                "00000000-0000-0000-0000-000000000000",
                "00000000-0000-0000-0000-000000000000",
                "00000000-0000-0000-0000-000000000000",
                "00000000-0000-0000-0000-000000000000",
                "00000000-0000-0000-0000-000000000000"
            ],
            "subjectlogs": ["00000000-0000-0000-0000-000000000000"],
            "tags": ["cooling"],
            "links": {
                "procedures": "procedures/",
                "subjectlogs": "subjectlogs/"
            },
            "name_used_in_storage": "subject2_local",
        }
    ]
}

Public list responses also include a meta object (pagination/filter metadata).

Add

• Allowed portals: private
• Request method: POST
• URL: https://www.brainstem.org/api/private/stem/subject
• Data: JSON dictionary containing at least the required fields.
• Responses: 201 OK; 400 Bad request; 403 Not allowed; 404 Not found

Use example (using Python API)

resp = client.save_model(
    "subject",
    data={
        "name": "NewSubject",
        "description": "some text",
        "strain": "00000000-0000-0000-0000-000000000000",
        "sex": "U",
        "projects": ["00000000-0000-0000-0000-000000000000"],
        "subject_identifier": "WF-123",
        "supplier": "00000000-0000-0000-0000-000000000000",
    },
)

Response example

{
    "subject": {
        "id": "00000000-0000-0000-0000-000000000000",
        "name": "NewSubject",
        "description": "some text",
        "projects": ["00000000-0000-0000-0000-000000000000"],
        "strain": "00000000-0000-0000-0000-000000000000",
        "sex": "U",
        "genetic_line": "",
        "genotype": "",
        "subject_identifier": "WF-123",
        "licenses": [],
        "supplier": "00000000-0000-0000-0000-000000000000",
        "birth_date": null,
        "death_date": null,
        "status": "active",
        "extra_fields": null,
        "procedures": [],
        "subjectlogs": [],
        "tags": [],
        "links": {
            "procedures": "procedures/",
            "subjectlogs": "subjectlogs/"
        },
        "name_used_in_storage": null,
    }
}

Detail

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

Use example (using Python API)

resp = client.load_model('subject', id='00000000-0000-0000-0000-000000000000')

Response example

{
    "subject": {
        "id": "00000000-0000-0000-0000-000000000000",
        "name": "NewSubject",
        "description": "some text",
        "projects": ["00000000-0000-0000-0000-000000000000"],
        "strain": "00000000-0000-0000-0000-000000000000",
        "sex": "U",
        "genetic_line": "",
        "genotype": "",
        "subject_identifier": "WF-123",
        "licenses": [],
        "supplier": "00000000-0000-0000-0000-000000000000",
        "birth_date": null,
        "death_date": null,
        "extra_fields": {
            "extra_property": "setting1",
            "another_property": 22
        },
        "procedures": [],
        "subjectlogs": [],
        "tags": [],
        "links": {
            "procedures": "procedures/",
            "subjectlogs": "subjectlogs/"
        },
        "name_used_in_storage": null,
    }
}

Change

• Allowed portals: private
• Request method: PATCH
• URL: https://www.brainstem.org/api/private/stem/subject/<id>/
• Data: dictionary containing the fields to be updated
• Responses: 200 OK; 400 Bad request; 403 Not allowed; 404 Not found

Use example (using Python API)

resp = client.save_model(
    "subject",
    id="00000000-0000-0000-0000-000000000000",
    data={"description": "new text"}
)

Response example

{
    "subject": {
        "id": "00000000-0000-0000-0000-000000000000",
        "name": "NewSubject",
        "description": "new text",
        "projects": ["00000000-0000-0000-0000-000000000000"],
        "strain": "00000000-0000-0000-0000-000000000000",
        "sex": "U",
        "genetic_line": "",
        "genotype": "",
        "subject_identifier": "WF-123",
        "licenses": [],
        "supplier": "00000000-0000-0000-0000-000000000000",
        "birth_date": null,
        "death_date": null,
        "extra_fields": null,
        "procedures": [],
        "subjectlogs": [],
        "tags": [],
        "links": {
            "procedures": "procedures/",
            "subjectlogs": "subjectlogs/"
        },
        "name_used_in_storage": null,
    }
}

Delete

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

Use example (using Python API)

resp = client.delete_model("subject", id="00000000-0000-0000-0000-000000000000")