Brains API

The Brains API provides endpoints for managing brain imaging data in the BrainMaps system.

Endpoints

List All Brains

GET /api/brains/

Retrieves a paginated list of all brain entries.

Query Parameters

Parameter	Type	Description
page	number	Page number for pagination
search	string	Search term to filter brains by name or ID
category	string	Filter brains by category
atlas	string	Filter brains by atlas

Response

{
    "count": 100,
    "next": "http://api.example.com/api/brains/?page=2",
    "previous": null,
    "results": [
        {
            "id": 1,
            "name": "Sample Brain",
            "date_uploaded": "2023-12-22T10:30:00Z",
            "image": "http://api.example.com/media/brains/sample.tiff",
            "website": "https://example.com",
            "verified": true,
            "category": 1,
            "uploader": 1,
            "atlas": 1,
            "uuid": "a7102307-dae3-4ad6-96b7-92c90a1bfca6",
            "zarr_file": "",
            "is_reference": false,
            "extra_link": "",
            "readable_id": "groovy-sparrow",
            "s3_url": "https://example.s3.amazonaws.com/brain.tif"
        }
    ]
}

Get Single Brain

GET /api/brains/{id}/

Retrieves details for a specific brain entry.

URL Parameters

Parameter	Type	Description
id	number	The ID of the brain

Response

{
    "id": 1,
    "name": "Sample Brain",
    "date_uploaded": "2023-12-22T10:30:00Z",
    "image": "http://api.example.com/media/brains/sample.tiff",
    "website": "https://example.com",
    "verified": true,
    "category": 1,
    "uploader": 1,
    "atlas": 1,
    "uuid": "a7102307-dae3-4ad6-96b7-92c90a1bfca6",
    "zarr_file": "",
    "is_reference": false,
    "extra_link": "",
    "readable_id": "groovy-sparrow",
    "s3_url": "https://example.s3.amazonaws.com/brain.tif"
}

Create Brain

POST /api/brains/

Creates a new brain entry.

Request Body

Field	Type	Description	Required
name	string	Name of the brain	Yes
image	file	Brain image file (TIFF format)	Yes
category	number	ID of the category	Yes
atlas	number	ID of the associated atlas	No
website	string	Related website URL	No
is_reference	boolean	Whether this is a reference brain	No
extra_link	string	Additional reference link	No

Response

Returns the created brain object with status code 201.

Update Brain

PUT /api/brains/{id}/
PATCH /api/brains/{id}/

Updates an existing brain entry. Use PUT for full updates and PATCH for partial updates.

URL Parameters

Parameter	Type	Description
id	number	The ID of the brain

Request Body

Same fields as Create Brain endpoint. All fields are optional for PATCH requests.

Response

Returns the updated brain object.

Delete Brain

DELETE /api/brains/{id}/

Deletes a specific brain entry.

URL Parameters

Parameter	Type	Description
id	number	The ID of the brain

Response

Returns 204 No Content on success.

Get Brain by Atlas Slug

GET /api/brains/by_atlas_slug/?slug={atlas_slug}

Retrieves a brain associated with a specific atlas slug.

Query Parameters

Parameter	Type	Description
slug	string	The slug of the atlas to match

Response

Returns a single brain object or 404 if not found.

Error Responses

Status Code	Description
400	Bad Request - Invalid parameters
401	Unauthorized - Authentication required
403	Forbidden - Insufficient permissions
404	Not Found - Resource doesn’t exist
500	Internal Server Error

Examples

Python Example

import requests
 
# List all brains
response = requests.get('http://api.example.com/api/brains/')
brains = response.json()
 
# Get a specific brain
brain_id = 1
response = requests.get(f'http://api.example.com/api/brains/{brain_id}/')
brain = response.json()
 
# Create a new brain
files = {'image': open('brain_image.tiff', 'rb')}
data = {
    'name': 'New Brain Sample',
    'category': 1,
    'atlas': 1
}
response = requests.post('http://api.example.com/api/brains/', files=files, data=data)
new_brain = response.json()

cURL Example

# List all brains
curl -X GET http://api.example.com/api/brains/
 
# Get a specific brain
curl -X GET http://api.example.com/api/brains/1/
 
# Create a new brain
curl -X POST http://api.example.com/api/brains/ \
  -F "name=New Brain Sample" \
  -F "category=1" \
  -F "image=@brain_image.tiff"

Endpoints