NeuroML · API contract, design stage
Developers
The NeuroML API is intended to make connectome records usable outside this website: a versioned REST contract with stable identifiers and explicit evidence states. This page is the contract skeleton. Every endpoint below is a plan with a declared status, not a running service.
Nothing on this page responds yet. /api/v1/* returns 404 until an endpoint is implemented, tested and marked live here. No keys are issued, no SDK is published and no OpenAPI document is final.
Endpoint plan
| Method | Path | Purpose | Status |
|---|---|---|---|
| Datasets and coverage | |||
| GET | /api/v1/datasets | Registered datasets with release version, licence, scope and citation. | Planned |
| GET | /api/v1/organisms | Organisms the platform holds records for, with per-organism scope. | Planned |
| GET | /api/v1/connectomes | Available connectome releases and their annotation status. | Planned |
| GET | /api/v1/mouse/datasets | Mouse sources only, including the access route each requires. | Planned |
| GET | /api/v1/mouse/coverage | Record counts per dataset and region, served from the registry rather than estimated. | Planned |
| Neuroanatomy | |||
| GET | /api/v1/brain-regions | Region identifiers, names and atlas provenance. | Planned |
| GET | /api/v1/cell-types | Cell-type taxonomy entries with the assignment method recorded. | Planned |
| GET | /api/v1/neurons/{id} | One neuron: identifiers, provenance, morphology, annotations, missing fields, evidence state. | Planned |
| GET | /api/v1/connections | Measured connections with synapse counts and annotation status; filterable by neuron, region and dataset. | Planned |
| GET | /api/v1/fly/neurons | Fruit-fly neuron records from the versioned connectome release. | Planned |
| Predictions and models | |||
| POST | /api/v1/predictions/activity | Neural-activity forecast from a registered model version. | Planned |
| POST | /api/v1/predictions/connectivity | Ranked candidate connections, returned as hypotheses with calibration data. | Planned |
| GET | /api/v1/models | Model registry: purpose, training dataset versions, evaluation results, limitations. | Planned |
| GET | /api/v1/experiments | Experiment records with held-out metrics and reproduction instructions. | Planned |
| GET | /api/v1/jobs/{id} | Long-running job state: status, checkpoint, retries, produced artefacts. | Planned |
| Literature and journal | |||
| GET | /api/v1/literature/search | Scholarly search across providers, with publication and retrieval dates kept separate. | Planned |
| GET | /api/v1/journal | Public research reports, each pointing at the evidence behind it. | Planned |
An endpoint appears here only to declare intent. It will be marked Live when it is implemented, covered by an integration test and verified against a real dataset record — not before.
Rules the contract must keep
- Versioned and additive. Breaking changes get a new major version;
/api/v1will not be silently redefined. - Stable identifiers. Records carry their source identifier alongside any internal one, so an external system can trace a neuron back to its dataset.
- Provenance on every record. Dataset, release version, coordinate system and access route travel with the data.
- Observed and predicted layers stay separate. Predictions are returned in their own fields with the model version attached; they are never merged into verified connections.
- Honest gaps. A missing property is returned as unknown or unavailable. The API will not interpolate a value to make a record look complete.
- No secrets in clients. Read-only public records need no key. Any protected route requires a server-side key, with rate limits, request validation and audit logging.
- Reproducibility. Every prediction response names the model version, the input dataset versions and the evaluation that bounds its accuracy.
- Licence respect. Records are served only where the source licence and terms allow redistribution; otherwise the response points to the source and says so.
What a request will look like
Illustrative only. This call does not succeed today.
GET https://orrbiologicals.com/api/v1/neurons/{id}
Accept: application/json
{
"id": "…",
"source": { "dataset": "…", "release": "…", "source_id": "…" },
"region": { "id": "…", "name": "…", "atlas": "…" },
"evidence_state": "VERIFIED_OBSERVATION",
"missing": ["transcriptomic_annotation"],
"provenance": { "citation": "…", "access": "…" }
}
Field names are provisional until the first endpoint is implemented. The shape will not change silently: this page and the OpenAPI document will be updated in the same change.
What works today
One public research surface is live: the literature search and DOI lookup, which queries Crossref and OpenAlex in the browser and labels open-access status from each provider's own metadata. It is not part of the versioned API and needs no key. Dataset ingestion, the neuron registry and every prediction route are still in design.
Questions and access requests
Dataset access questions, integration proposals and corrections: service@orrbiologicals.com. If a future route needs an access token or a paid resource, that will be requested explicitly rather than worked around. See also the NeuroML platform layout and the scientific disclaimer.