Regulatory authority API endpoint

The shared list of organizations that issue research licenses.

Table of contents

1. Endpoints
2. Fields
3. List
4. Add
5. Detail
6. Change
7. Delete
8. Data model

Endpoints

• Private portal: https://www.brainstem.org/api/private/taxonomies/regulatoryauthority/ (needs a token; one record: append <id>/)
• Public portal: https://www.brainstem.org/api/public/taxonomies/regulatoryauthority/ (read-only, public projects, no token)
• Response keys: regulatoryauthority (detail, create, update), regulatoryauthorities (list)
• Permissions: see the permissions page
• Uniqueness: name unique across BrainSTEM
• Deleting: refused (400) while license 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 255 characters. Official name of the regulatory authority (e.g., “Home Office”, “Institutional Animal Care and Use Committee”)
abbreviation	string; max 32 characters. Common abbreviation (e.g., “IACUC”, “AWERB”, “IRB”, “CCAC”)
country	computed. Country where this authority operates (ISO country code)
authority_type	one of national, institutional, regional, international. Type of regulatory authority
website	string; max 200 characters. Official website URL
description	string. Description of the authority, its jurisdiction, and regulatory scope
is_active	boolean. Whether this authority is currently operational
comments	string
created_at	datetime [read-only]; nullable
updated_at	datetime [read-only]

List

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

Use example (Python API tool)

resp = client.load('regulatoryauthority', load_all=True)
records = resp['regulatoryauthorities']

Use example (MATLAB API tool)

resp = client.load('regulatoryauthority', 'load_all', true);
records = resp.regulatoryauthorities;

Response example

{
    "regulatoryauthorities": [
        {
            "id": "<id>",
            "name": "Regulatory authority 1",
            "abbreviation": "",
            "country": null,
            "authority_type": "national",
            "website": "",
            "description": "",
            "is_active": true,
            "comments": "",
            "created_at": "2024-03-22T10:30:00Z",
            "updated_at": "2024-03-22T10:30:00Z"
        }
    ],
    "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/regulatoryauthority/
• 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('regulatoryauthority', data={"name": "Regulatory authority 1"})
record = resp.json()['regulatoryauthority']

Use example (MATLAB API tool)

created = client.save(struct('name', 'Regulatory authority 1'), 'regulatoryauthority');
record = created.regulatoryauthority;

Detail

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

Use example (Python API tool)

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

Use example (MATLAB API tool)

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

Response example

{
    "regulatoryauthority": {
        "id": "<id>",
        "name": "Regulatory authority 1",
        "abbreviation": "",
        "country": null,
        "authority_type": "national",
        "website": "",
        "description": "",
        "is_active": true,
        "comments": "",
        "created_at": "2024-03-22T10:30:00Z",
        "updated_at": "2024-03-22T10:30:00Z"
    }
}

Change

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

Use example (MATLAB API tool)

client.save(struct('id', '<id>', 'name', 'Regulatory authority 1 (renamed)'), 'regulatoryauthority', 'method', 'patch');

Delete

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

Use example (Python API tool)

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

Use example (MATLAB API tool)

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

Data model

The fields are described for the web forms on the Regulatory authority data model page.