api-referenceEndpoints

API Endpoints

Authentication

Register

POST /api/auth/register/

Create a new user account.

Request Body:

{
  "email": "researcher@example.com",
  "username": "researcher",
  "password": "your-password",
  "password_confirm": "your-password",
  "first_name": "John",
  "last_name": "Doe"
}

Validation:

  • Email must be unique
  • Username must be unique
  • Password must be at least 8 characters
  • Password and password_confirm must match

Response:

{
  "id": 1,
  "username": "researcher",
  "email": "researcher@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "avatar": null
}

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,
    "username": "researcher",
    "email": "researcher@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "avatar": null,
    "bio": "Researcher in neuroscience",
    "location": "San Francisco",
    "is_staff": false
  }
}

Change Password

POST /api/auth/password/change/

Change the authenticated user’s password.

Request Body:

{
  "old_password": "current-password",
  "new_password": "new-password"
}

Get Current User

GET /api/auth/me/

Get details of the currently authenticated user.

Response:

{
  "id": 1,
  "username": "researcher",
  "email": "researcher@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "avatar": null,
  "bio": "Researcher in neuroscience",
  "location": "San Francisco"
}

User Profile

Get Profile

GET /api/profile/

Get the authenticated user’s full profile.

Response:

{
  "id": 1,
  "email": "researcher@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "avatar": "https://example.com/avatars/1.jpg",
  "bio": "Researcher in neuroscience",
  "location": "San Francisco",
  "group": {
    "id": 1,
    "name": "Research Lab"
  }
}

Update Profile

PATCH /api/profile/

Update the authenticated user’s profile.

Request Body (multipart/form-data):

first_name: "John"
last_name: "Doe"
bio: "Updated bio"
location: "New Location"
avatar: [image file]

Personal Access Tokens

List Tokens

GET /api/tokens/

List all personal access tokens for the authenticated user.

Response:

[
  {
    "id": "uuid",
    "name": "API Access",
    "created_at": "2023-12-28T12:00:00Z",
    "last_used_at": "2023-12-28T13:00:00Z",
    "expires_at": "2024-12-28T12:00:00Z",
    "is_revoked": false
  }
]

Create Token

POST /api/tokens/

Create a new personal access token.

Request Body:

{
  "name": "API Access",
  "expires_at": "2024-12-28T12:00:00Z"
}

Response:

{
  "id": "uuid",
  "name": "API Access",
  "token": "generated-token-value",
  "created_at": "2023-12-28T12:00:00Z",
  "expires_at": "2024-12-28T12:00:00Z"
}

Revoke Token

DELETE /api/tokens/{id}/

Revoke a personal access token.

Categories

List Categories

GET /api/categories/

Get all available categories.

Response:

[
  {
    "id": 1,
    "name": "cephalopods",
    "description": "Octopuses, squids, and cuttlefish",
    "image": null,
    "image_url": null,
    "image_source": "https://example.com/images/cephalopods.jpg",
    "brains_count": 10,
    "atlases_count": 2
  }
]

Notes:

  • Category names are automatically converted to lowercase
  • Either upload an image or provide an image_url, not both
  • image_source is automatically determined from image or image_url

Get Category

GET /api/categories/{name}/

Get details of a specific category.

Response:

{
  "id": 1,
  "name": "cephalopods",
  "description": "Octopuses, squids, and cuttlefish",
  "image_source": "https://example.com/images/cephalopods.jpg",
  "brains_count": 10,
  "atlases_count": 2
}

Create Category

POST /api/categories/

Create a new category.

Request Body (multipart/form-data):

name: "category-name"
description: "Category description"
image: [image file]
image_url: "https://example.com/image.jpg"

Species

List Species

GET /api/species/

Get all available species.

Query Parameters:

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

Response:

[
  {
    "id": 1,
    "name": "common octopus",
    "scientific_name": "Octopus Vulgaris",
    "description": "Species description",
    "category": {
      "id": 1,
      "name": "cephalopods"
    },
    "category_name": "cephalopods",
    "brains": [...],
    "atlases": [...]
  }
]

Notes:

  • Species names are automatically converted to lowercase
  • Scientific names are automatically formatted (first word capitalized, rest lowercase)
  • Each species must belong to a category

Get Species

GET /api/species/{scientific_name}/

Get details of a specific species.

Atlases

List Atlases

GET /api/atlases/

Get all available brain atlases.

Response:

[
  {
    "id": 1,
    "name": "Octopus Vulgaris",
    "description": "Standard atlas",
    "species": {
      "id": 1,
      "name": "common octopus",
      "scientific_name": "Octopus Vulgaris",
      "category": {
        "id": 1,
        "name": "cephalopods"
      }
    },
    "is_official": true,
    "verified": true,
    "version": "1.0.0",
    "color": "#FF5733",
    "brains_count": 5
  }
]

Get Atlas

GET /api/atlases/{slug}/

Get details of a specific atlas.

Create Atlas

POST /api/atlases/

Create a new atlas.

Request Body:

{
  "species": 1,
  "description": "Atlas description",
  "is_official": false,
  "version": "1.0.0",
  "publication_url": "https://example.com/publication"
}

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
  • atlas: Filter by atlas ID

Response:

[
  {
    "id": 1,
    "readable_id": "cool-brain",
    "name": "Sample Brain",
    "description": "Brain description",
    "date_uploaded": "2023-12-28T12:00:00Z",
    "verified": false,
    "color": "#FF5733",
    "atlas": {
      "id": 1,
      "name": "Atlas Name",
      "slug": "atlas-slug",
      "description": "Atlas description"
    },
    "species": {
      "id": 1,
      "name": "Species Name",
      "scientific_name": "Scientific Name",
      "category": {
        "id": 1,
        "name": "Category Name"
      }
    },
    "uploader": {
      "id": 1,
      "username": "uploader",
      "email": "uploader@example.com"
    },
    "uuid": "brain-uuid",
    "is_reference": false,
    "file_size_mb": 100.5
  }
]

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"
description: "Brain description"
atlas: 1
file: [binary file data]
is_reference: false
extra_link: "https://example.com/additional-info"
color: "#FF5733"

Notes:

  • Species is automatically set from the atlas’s species
  • Category is automatically set from the species’s category
  • A unique readable_id is automatically generated
  • File upload triggers automatic processing

Update Brain

PATCH /api/brains/{readable_id}/

Update brain metadata.

Request Body:

{
  "name": "Updated Brain Name",
  "description": "Updated description",
  "atlas": 2,
  "is_reference": true,
  "extra_link": "https://example.com/new-link",
  "color": "#00FF00"
}

Delete Brain

DELETE /api/brains/{readable_id}/

Delete a brain scan and all associated file uploads.

File Uploads

List Uploads

GET /api/file-uploads/

List all file uploads for the current user.

Response:

[
  {
    "id": "uuid",
    "name": "brain-scan.nii.gz",
    "date_uploaded": "2023-12-28T12:00:00Z",
    "uploader": {
      "id": 1,
      "username": "researcher",
      "email": "researcher@example.com"
    },
    "status": "completed",
    "processing_started": "2023-12-28T12:00:01Z",
    "processing_completed": "2023-12-28T12:05:00Z",
    "file_size_mb": 100.5,
    "file_size_kb": 102912.0,
    "associated_brain": {
      "id": 1,
      "name": "Brain Name",
      "readable_id": "cool-brain"
    },
    "filename": "brain-scan.nii.gz",
    "mime_type": "application/x-nifti"
  }
]

Create Upload

POST /api/file-uploads/

Start a new file upload.

Request Body (multipart/form-data):

file: [binary file data]

Supported Formats:

  • .nii - NIfTI format
  • .nii.gz - Compressed NIfTI
  • .zarr - Zarr format
  • .tif - TIFF format
  • .tiff - TIFF format

Processing States:

  • uploaded - Initial state
  • processing - File is being processed
  • completed - Processing successful
  • failed - Processing failed

Response:

{
  "id": "uuid",
  "name": "brain-scan.nii.gz",
  "status": "uploaded",
  "file_size_mb": 100.5,
  "file_size_kb": 102912.0,
  "s3_url": "https://s3.amazonaws.com/bucket/path/to/file",
  "metadata": {}
}

System Endpoints

Health Check

GET /health/

Check system health status.

Response:

{
  "status": "healthy"
}

Headers:

Content-Type: application/json

Metrics

GET /metrics/

Get Prometheus-formatted metrics.

Response Headers:

Content-Type: text/plain; version=0.0.4; charset=utf-8

Available Metrics:

  • http_requests_total - Counter of HTTP requests
  • http_request_duration_seconds - Histogram of request durations

Authentication Headers

All authenticated endpoints require:

Authorization: Token your-auth-token

Or for personal access tokens:

Authorization: Bearer your-access-token

Rate Limiting

Rate limits are enforced per endpoint:

Headers:

X-RateLimit-Limit: {limit}
X-RateLimit-Remaining: {remaining}
X-RateLimit-Reset: {reset_timestamp}

When exceeded:

{
  "error": "Rate limit exceeded",
  "detail": "Please try again later",
  "retry_after": 60
}

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

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