Data model
This is a guide to the current relationships and API identifiers, rather than a second copy of Django’s model definitions.
Catalogue and source data
| Model | Identifier | Role and relationships |
|---|---|---|
| Category | Integer ID; API lookup by name | Curated group containing species |
| Species | Integer ID and stable slug; API lookup by common name | Common/scientific names, description, image and category |
| Atlas | Integer ID; legacy API lookup by slug | Species-specific atlas, stable identifier, creator and delegated administrators |
| Brain | Integer ID, UUID and readable ID | Specimen belonging to a species, with an optional atlas association |
| FileUpload | UUID | Stored file/dataset URL, upload metadata, processing status and optional brain/atlas association |
| Layer | UUID | A spatial data source linked to a brain or atlas |
Species can have multiple atlases. Atlas pages use species slug plus atlas identifier to distinguish them. Brain category follows its species. Reference images are catalogue illustrations; they are not the scan volumes.
Categories and species do not currently have model created_at/updated_at fields. Do not depend on those fields in their API responses.
Spatial layers and viewer state
A Layer records kind, data_format, url, voxel_size_um, axis_order, coordinate_space, optional source_registration, and flexible metadata.
The URL points to stored data; metadata alone does not establish that a volume exists. Physical units and axis order must agree with the actual array. A mesh representation, image intensity volume and voxel segmentation are distinct assets.
A NeuroglancerState stores a viewer state and its visibility/ownership. Private saved states remain private to their owner (with staff access), even though signed-in users can read the platform’s underlying scientific datasets.
Atlas releases and variants
| Model | Role |
|---|---|
| AtlasRelease | Versioned release of atlas assets, linked to an atlas and optional parent release |
| AtlasVariant | A release’s annotation/resolution variant and its template, segmentation, mesh and viewer references |
| AtlasBuildJob | Build lifecycle, worker lease, progress, inputs and result |
All three use UUIDs. Releases have the coarse states draft, built, active, deprecated and failed. Queued/running phases belong to build jobs, not the release status.
A published variant is a snapshot. An imported mesh-only variant does not imply the presence of a reference image or volumetric labels. Check its asset references and provenance before using it as a registration target or attempting an export.
Registration and processing
| Model | Role |
|---|---|
| RegistrationRun | Source brain, target release and optional exact variant, backend, parameters, progress and metrics |
| RegistrationArtifact | A run’s output URL and type, such as a transform or registered volume |
| IngestJob / IngestArtifact | Ingestion handoff, source information, progress and produced artifact references |
| Job | Generic queued conversion/export work with claim/progress/result information |
These identifiers are UUIDs. Creating a record does not itself execute processing. Local CLI commands or workers perform computation and report results. See registration and compute jobs.
Accounts and governance
Users have independent active, approved, staff and superuser flags. An active signed-in user can read scientific data and add species; approval unlocks contributions. Superuser status controls category changes and edits to existing species. Atlas creation/delegated administration defines atlas governance separately from staff status.
Personal access tokens use UUIDs, belong to a user, and record revocation/expiry. Jobs, ingest records, private viewer states and credentials retain their resource-specific scopes; shared dataset access is not unrestricted access to account or operational records.
For request fields and route lookup rules, use endpoints, brains and tokens.