Brain API

A brain is a specimen catalogue record. The scan bytes live in uploads or externally hosted datasets; spatial layers describe how the viewer reads them.

List and retrieve

curl --fail 'https://api.brainmaps.xyz/api/brains/?species=1&search=specimen' \
  -H "Authorization: Token $BRAINMAPS_API_KEY"
 
curl --fail https://api.brainmaps.xyz/api/brains/123/ \
  -H "Authorization: Token $BRAINMAPS_API_KEY"

Replace numeric IDs with values returned by your installation. species filters by numeric ID. search matches name, readable ID and UUID. A category query parameter currently does not filter the results.

Alternative lookups:

GET /api/brains/by_readable_id/?readable_id=VALUE
GET /api/brains/by_atlas_slug/?slug=ATLAS_SLUG

These are query parameters, not additional path segments. URL-encode their values.

Create from an existing upload

Use an upload belonging to the authenticated contributor:

curl --fail https://api.brainmaps.xyz/api/brains/ \
  -H "Authorization: Token $BRAINMAPS_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"name":"Specimen 001","species_id":1,"file_upload":"00000000-0000-0000-0000-000000000000","description":"Acquisition notes"}'

Replace the example UUID and species ID. Optional fields include atlas_id, color and license. Choose the licence applicable to your dataset. Creating the record does not automatically convert raw data or register it to an atlas.

Field	Meaning
`name`, `description`	Specimen identity and notes
`species_id`	Species relationship for writes
`atlas_id`	Optional atlas association; not a coordinate transform
`file_upload`	Write-only UUID of an existing upload to associate
`color`	Default display colour
`license`	Dataset licence, currently `CC0-1.0` or `CC-BY-4.0`
`image`, `image_url`	Optional reference picture, not the raw scan

The API can also create metadata-only records. The CLI’s create command is stricter and requires exactly one of --file or --from-upload.

Response fields

Responses include the numeric id, uuid, generated readable_id, species/category/atlas and uploader information, available file_uploads and layers, and inferred_metadata. image_source is the resolved reference-image URL. Check the actual dataset/layer URLs before opening a viewer.

A brain’s verified flag records curation; it is not a private/public access switch for signed-in users.

Update and delete

Detail routes support PATCH/PUT/DELETE subject to the API’s write permissions. Category is derived from species. Use valid existing IDs when changing relationships. Deleting a brain record must not be used as proof that raw uploads or external storage objects have been deleted.

The CLI currently has no brain update/delete command.

Viewer state

GET /api/brains/{id}/neuroglancer_state/
POST /api/brains/{id}/save_state/

State generation returns state, viewer_url and coordinate-space information. It assembles existing assets; it does not produce missing meshes, pyramids, segmentation or registration transforms. External viewer URLs must also be able to authenticate to the referenced data sources. The BrainMaps embedded viewer handles its protected-data viewer session.

See viewer controls and registration.

CLI Reference Endpoints