License API endpoint

A regulatory authorization the lab works under, such as an animal research approval.

Table of contents

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

Endpoints

  • Private portal: https://www.brainstem.org/api/private/personal_attributes/license/ (needs a token; one record: append <id>/)
  • Public portal: https://www.brainstem.org/api/public/personal_attributes/license/ (read-only, public projects, no token)
  • Response keys: license (detail, create, update), licenses (list)
  • Permissions: object permissions on the record itself (member / manager / owner roles)
  • Deleting: also deletes the linked licensegroupmembershipinvitation, licensemembershipinvitation 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]
namestring [required]; max 255 characters. Name/title of the license (e.g., “PPL: Septo-hippocampal dynamics 2025-2028”)
typeone of animal_research_authorization, human_research_authorization, biosafety_gmo_authorization, wildlife_fieldwork_permit, controlled_substance_license, chemical_use_authorization, import_export_permit [required]. Type of authorization or license
statusone of draft, pending, active, suspended, expired, revoked [required]. Current status of the license
descriptionstring; nullable. Detailed description of the license scope and purpose
countrystring; nullable. Country where the license was issued (ISO country code)
regulatory_authorityregulatoryauthority id; nullable. Regulatory authority that issued the license (select from standardized list or add new authority in Taxonomies)
license_numberstring; max 128 characters. Official license number on the approval document
license_documentstring; max 100 characters. Upload the official license document as a PDF (10 MB maximum)
valid_fromdate; nullable. Date when the license becomes valid
valid_untildate; nullable. Date when the license expires
license_holderslist of user ids. Named license holders (e.g., PIs, authorized personnel)
behavioralassayslist of behavioralassay ids [read-only]; nullable; nestable
subjectslist of subject ids [read-only]; nullable; nestable
procedureslist of procedure ids [read-only]; nullable; nestable
is_publicboolean. Designates if the license information is publicly available
created_atdatetime [read-only]; nullable
updated_atdatetime [read-only]
userscomputed [read-only]
groupscomputed [read-only]

List

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

Use example (Python API tool)

resp = client.load('license', load_all=True)
records = resp['licenses']

Use example (MATLAB API tool)

resp = client.load('license', 'load_all', true);
records = resp.licenses;

Response example

{
    "licenses": [
        {
            "id": "<id>",
            "name": "License 1",
            "type": "animal_research_authorization",
            "status": "active",
            "description": "",
            "country": "",
            "regulatory_authority": "<regulatoryauthority-id>",
            "license_number": "",
            "license_document": "",
            "valid_from": "2024-03-22",
            "valid_until": "2024-03-22",
            "license_holders": [
                "<user-id>"
            ],
            "behavioralassays": [
                "<behavioralassay-id>"
            ],
            "subjects": [
                "<subject-id>"
            ],
            "procedures": [
                "<procedure-id>"
            ],
            "is_public": true,
            "created_at": "2024-03-22T10:30:00Z",
            "updated_at": "2024-03-22T10:30:00Z",
            "users": null,
            "groups": null
        }
    ],
    "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/personal_attributes/license/
  • 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('license', data={"name": "License 1", "type": "animal_research_authorization", "status": "active"})
record = resp.json()['license']

Use example (MATLAB API tool)

created = client.save(struct('name', 'License 1', 'type', 'animal_research_authorization', 'status', 'active'), 'license');
record = created.license;

Detail

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

Use example (Python API tool)

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

Use example (MATLAB API tool)

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

Response example

{
    "license": {
        "id": "<id>",
        "name": "License 1",
        "type": "animal_research_authorization",
        "status": "active",
        "description": "",
        "country": "",
        "regulatory_authority": "<regulatoryauthority-id>",
        "license_number": "",
        "license_document": "",
        "valid_from": "2024-03-22",
        "valid_until": "2024-03-22",
        "license_holders": [
            "<user-id>"
        ],
        "behavioralassays": [
            "<behavioralassay-id>"
        ],
        "subjects": [
            "<subject-id>"
        ],
        "procedures": [
            "<procedure-id>"
        ],
        "is_public": true,
        "created_at": "2024-03-22T10:30:00Z",
        "updated_at": "2024-03-22T10:30:00Z",
        "users": null,
        "groups": null
    }
}

Change

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

Use example (MATLAB API tool)

client.save(struct('id', '<id>', 'name', 'License 1 (renamed)'), 'license', 'method', 'patch');

Delete

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

Use example (Python API tool)

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

Use example (MATLAB API tool)

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

Custom actions

ActionRequest
leavePOST /api/private/personal_attributes/license/<id>/leave/

Data model

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