api-referenceEndpoints

API Endpoints

Authentication

Login

POST /api/auth/login/

Login with email and password to receive an authentication token.

Request Body:

{
  "email": "researcher@example.com",
  "password": "your-password"
}

Response:

{
  "token": "your-auth-token",
  "user": {
    "id": 1,
    "email": "researcher@example.com",
    "first_name": "John",
    "last_name": "Doe"
  }
}

Logout

POST /api/auth/logout/

Revoke the current session token.

Get Current User

GET /api/auth/me/

Get details of the currently authenticated user.

Categories

List Categories

GET /api/categories/

Get all available categories.

Response:

[
  {
    "id": 1,
    "name": "Cephalopods",
    "description": "Octopuses, squids, and cuttlefish"
  },
  {
    "id": 2,
    "name": "Birds",
    "description": "Avian species"
  }
]

Get Category

GET /api/categories/{name}/

Get details of a specific category.

Species

List Species

GET /api/species/

Get all available species.

Query Parameters:

  • category: Filter by category name
  • scientific_name: Filter by scientific name

Get Species

GET /api/species/{name}/

Get details of a specific species.

Brains

List Brains

GET /api/brains/

Get all available brain scans.

Query Parameters:

  • species: Filter by species scientific name
  • verified: Filter by verification status
  • uploader: Filter by uploader ID

Get Brain

GET /api/brains/by_readable_id/?readable_id={readable_id}

Get details of a specific brain by its readable ID.

Create Brain

POST /api/brains/

Upload a new brain scan.

Request Body (multipart/form-data):

name: "Sample Brain"
species: "Mus musculus"
description: "Description of the brain scan"
file: [binary file data]

Update Brain

PATCH /api/brains/{id}/

Update brain metadata.

Delete Brain

DELETE /api/brains/{id}/

Delete a brain scan.

File Uploads

List Uploads

GET /api/file-uploads/

List all file uploads for the current user.

Create Upload

POST /api/file-uploads/

Start a new file upload.

Request Body (multipart/form-data):

file: [binary file data]

Error Responses

400 Bad Request

{
  "error": "Invalid request parameters",
  "detail": "Specific error message"
}

401 Unauthorized

{
  "error": "Authentication required",
  "detail": "Please log in to access this resource"
}

403 Forbidden

{
  "error": "Permission denied",
  "detail": "You don't have permission to perform this action"
}

404 Not Found

{
  "error": "Resource not found",
  "detail": "The requested resource does not exist"
}

Rate Limiting

  • Rate limits are applied per user and per IP address
  • Default limit: 100 requests per minute
  • Authenticated users get higher limits

Rate Limit Headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

Pagination

List endpoints support pagination:

Request:

GET /api/brains/?page=2&page_size=10

Response:

{
  "count": 100,
  "next": "http://api.example.com/brains/?page=3",
  "previous": "http://api.example.com/brains/?page=1",
  "results": [
    // Array of items
  ]
}

Filtering

Many endpoints support filtering:

GET /api/brains/?species=mus-musculus&verified=true
GET /api/species/?category=rodents

Searching

Full-text search is available:

GET /api/brains/?search=cortex
GET /api/species/?search=mouse

Versioning

The API is versioned through the URL:

https://api.brainmaps.science/v1/brains/

CORS

Cross-Origin Resource Sharing is enabled for web clients:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization
BrainsModels
BrainMaps Documentation