API endpoints

Production base URL: https://api.brainmaps.xyz. API routes below include /api/ and a trailing slash. Use JSON unless the endpoint accepts a file; use multipart form data for an avatar or reference image.

Authenticate with:

Authorization: Token YOUR_TOKEN

Both login tokens and personal access tokens use Token, not Bearer. A valid signed-in account can read platform scientific data; write operations retain approval, ownership and atlas-governance checks. See access policy.

Authentication and profile

Signup accepts email, username, password, password_confirm, and optional first_name/last_name. The profile’s id and email are read-only; bio and location are not current profile fields.

Catalogue

These resource collections support GET and POST; detail routes expose GET, PUT, PATCH and DELETE subject to permissions. Do not infer write access from read access.

For unambiguous atlas lookup use:

GET /api/atlases/by-species/{species_slug}/{identifier}/

Add a species

Replace category_id with an existing category ID:

curl --fail https://api.brainmaps.xyz/api/species/ \
  -H "Authorization: Token $BRAINMAPS_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"name":"example species","scientific_name":"Example species","category_id":1}'

category_id is a write-only relationship field. category, category_name and the generated slug are read-only. Omitting the category uses the uncategorized category. Reusing an existing species is preferable to creating a duplicate.

Brain actions

See brain requests and fields. Viewer-state generation does not convert data or compute registration.

File uploads

/api/file-uploads/ stores upload records; detail lookup uses a UUID. Signed-in users can read uploads across the platform. Upload mutation and metadata confirmation enforce contribution/ownership rules.

Single-file flow:

1. Start with name, file_size_bytes, optional content_type and metadata.
2. PUT the file bytes to the returned upload_url, including its required_headers. This storage request does not use the API token header.
3. Complete the returned file_upload_id; optionally supply file_size_bytes for verification.
4. Inspect and confirm metadata, for example:

{
  "voxel_size_um": [2, 2, 5],
  "orientation": "ras"
}

Sizes are X,Y,Z in micrometres. Supply your actual acquisition values. A worker must process queued conversion before the result is viewer-ready. See uploading.

Layers, releases and registration

Detail IDs for these resources are UUIDs. Authenticated scientific-data reads are not limited to the uploader. Saved viewer states are different: ordinary users see public states and their own private states; staff can inspect all states.

Atlas actions include /api/atlases/{slug}/administrators/ (GET/POST/DELETE), brain-eligibility/, build/ and rollback/ (POST). Releases expose POST actions publish/ and mark-built/. These actions enforce atlas governance; staff status alone does not make someone an atlas administrator.

Atlas build jobs expose list/detail GET routes and POST claim/, heartbeat/, progress/, complete/, fail/ and cancel/ actions. The worker commands implement these lifecycle contracts; use them instead of manually inventing state transitions.

Processing and account resources

Generic jobs support collection POST claim/ and detail POST heartbeat/, complete/, fail/, retry/ and cancel/; consult the worker contract before integrating. See compute jobs for supported job kinds and ownership.

Operational endpoints outside /api/ include GET /health/, GET /metrics/ and Django /admin/.

Errors and integration expectations

Validation errors may use field names, detail or error; do not assume one response shape for every endpoint. Authentication/permission failures can return 403. Handle non-success HTTP status codes before reading a success payload.

Use returned IDs and URLs rather than constructing storage paths. Do not assume all list endpoints have the same pagination envelope, or that deleting metadata also deletes every underlying object.