Behavioral paradigm API endpoint

A standard behavioral task shared across labs, independent of how one lab runs it.

Table of contents

1. Endpoints
2. Fields
3. List
4. Add
5. Detail
6. Change
7. Delete
8. JSON field schemas
   1. External Identifiers
9. Data model

Endpoints

• Private portal: https://www.brainstem.org/api/private/taxonomies/behavioralparadigm/ (needs a token; one record: append <id>/)
• Public portal: https://www.brainstem.org/api/public/taxonomies/behavioralparadigm/ (read-only, public projects, no token)
• Response keys: behavioral_paradigm (detail, create, update), behavioral_paradigms (list)
• Permissions: see the permissions page
• Uniqueness: name unique across BrainSTEM
• Deleting: refused (400) while behavioralassay records point to 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]
name	string [required]; max 200 characters. Paradigm name (e.g., ‘Hidden Platform Learning’, ‘Spontaneous Alternation’)
category	behavioralcategory id; nullable. Primary behavioral category
description	string; max 3000 characters. Detailed description of the paradigm, typical protocol, and variations
species	list of species ids. Species for which this paradigm is applicable. Leave empty if universal.
original_publication	string; max 500 characters. Original publication citation (e.g., ‘Morris 1984’)
reference_url	string; max 200 characters. URL to reference documentation or publication
rrid	string; max 100 characters; nullable. Research Resource Identifier (RRID) for tracking standardized research resources
external_identifiers	JSON object; nullable. External identifiers and their source URLs from various databases (NCBI, JAX, DOI, etc.)
comments	string

List

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

Use example (Python API tool)

resp = client.load('behavioralparadigm', load_all=True)
records = resp['behavioral_paradigms']

Use example (MATLAB API tool)

resp = client.load('behavioralparadigm', 'load_all', true);
records = resp.behavioral_paradigms;

Response example

{
    "behavioral_paradigms": [
        {
            "id": "<id>",
            "name": "Behavioral paradigm 1",
            "category": "<behavioralcategory-id>",
            "description": "",
            "species": [
                "<species-id>"
            ],
            "original_publication": "",
            "reference_url": "",
            "rrid": "",
            "external_identifiers": {},
            "comments": ""
        }
    ],
    "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/taxonomies/behavioralparadigm/
• 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('behavioralparadigm', data={"name": "Behavioral paradigm 1"})
record = resp.json()['behavioral_paradigm']

Use example (MATLAB API tool)

created = client.save(struct('name', 'Behavioral paradigm 1'), 'behavioralparadigm');
record = created.behavioral_paradigm;

Detail

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

Use example (Python API tool)

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

Use example (MATLAB API tool)

out = client.load('behavioralparadigm', 'id', '<id>');
record = out.behavioral_paradigm;

Response example

{
    "behavioral_paradigm": {
        "id": "<id>",
        "name": "Behavioral paradigm 1",
        "category": "<behavioralcategory-id>",
        "description": "",
        "species": [
            "<species-id>"
        ],
        "original_publication": "",
        "reference_url": "",
        "rrid": "",
        "external_identifiers": {},
        "comments": ""
    }
}

Change

• Allowed portals: private
• Request method: PATCH
• URL: https://www.brainstem.org/api/private/taxonomies/behavioralparadigm/<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('behavioralparadigm', id='<id>', data={"name": "Behavioral paradigm 1 (renamed)"})

Use example (MATLAB API tool)

client.save(struct('id', '<id>', 'name', 'Behavioral paradigm 1 (renamed)'), 'behavioralparadigm', 'method', 'patch');

Delete

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

Use example (Python API tool)

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

Use example (MATLAB API tool)

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

JSON field schemas

Schema for the external identifiers of a behavioral paradigm. 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/BehavioralParadigm/<Type>/<version>.json and never changes; see Public schemas.

External Identifiers

• type code ExternalIdentifiers · version 1.0.0 · schema

Add external identifiers from databases like NIF, Wikipedia, PubMed, etc.

Property	Description
source	choice [required]; one of NIF, Wikipedia, PubMed, DOI, Wikidata, InterLex, Custom, Other; default "NIF"
id	Identifier: text [required]
url	URL (optional): text

Illustrative payload:

[
    {
        "source": "NIF",
        "id": "text",
        "url": "text"
    }
]

Data model

The fields are described for the web forms on the Behavioral paradigm data model page.