API Overview
Base URL: https://api.syndb.xyz/v1
Interactive OpenAPI documentation: api.syndb.xyz/docs
OpenAPI spec: GET /openapi.json
This page is a curated route map for the current public surface. The generated OpenAPI document is the authoritative exhaustive reference.
The repository commits the same document as openapi.json (paths relative to
/v1, info.version fixed to v1); a test fails when it drifts from the
router. crates/generated/syndb-api-client is a typed Rust client generated
from a subset of it by openapi-generator; just openapi regenerates both. The
client backs syndb api and the api_* tools of the syndb mcp ops server:
syndb api | Route | MCP tool |
|---|---|---|
corpus | GET /neurodata/corpus | api_corpus_status |
datasets | GET /neurodata/datasets | api_datasets |
dataset ID | GET /neurodata/datasets/{id} | api_dataset (view: metadata) |
table-versions ID | GET /neurodata/datasets/{id}/table-versions | api_dataset (view: table_versions) |
derived-products ID | GET /neurodata/datasets/{id}/derived-products | api_dataset (view: derived_products) |
summary ID... | GET /analytics/summary | api_dataset (view: summary) |
graph-summary ID | GET /analytics/graph/{id}/summary | api_dataset (view: graph_summary) |
search QUERY | GET /search/fulltext | api_search |
capabilities | GET /app/capabilities | api_capabilities |
Each prints the response as JSON after decoding it into the generated model,
so a response that breaks the documented schema is an error. They read
--server-url / SYNDB_SERVER_URL (production by default; syndb --server-url URL mcp ops forwards it to the tools). summary and
graph-summary call academic-only routes and use the CLI’s usual login flow
(explicit SYNDB_AUTH_TOKEN, refreshed stored login, ETL service login, then
syndb auth login); the rest send no token. To cover another
operation, add its operationId to CLIENT_OPERATIONS in
crates/services/api/tests/openapi_spec.rs and run just openapi.
Generated client policy
crates/generated/syndb-api-client is never hand-edited. Cargo.toml,
openapi.json and .openapi-generator-ignore are hand-maintained inputs;
src/ and .openapi-generator/ come from openapi-generator. The crate allows
all clippy lints ([lints.clippy] all = "allow") because generated code is not
reviewable style; these guards stand in for that review:
crates/services/api/tests/openapi_spec.rscompares the committedopenapi.jsonand client spec with the router, names the first stale path, and fails whenCLIENT_OPERATIONS, the generated functions or the query-only enums (BenchmarkType,ExportFormat,ExportSchema) drift. The spec writer rejects$refsiblings that change validation anddeepObjectquery parameters before writing anything, and widens nullable array items to untyped with a description so nulls decode honestly.crates/services/api/tests/int_test_generated_client.rsdecodes real handler responses into the generated models.scripts/openapi-generate.sh(run byjust openapi) pins the generator to the flake’s rootnixpkgsinput (rev0a3468a402c449992505b6a9fc5b06580141b750-> openapi-generator-cli 7.25.0, matching.openapi-generator/VERSION), generates into a temp dir, stages the complete crate next to the committed one and swaps it in with renames. A generator,cargo fmtorcargo checkfailure restores the previous crate and both specs, so a failed run leaves the checkout untouched.
Authentication
Pass a PASETO access token in the Authorization header:
Authorization: Bearer <access_token>
See Authentication for how to obtain tokens.
Content Types
- Requests:
application/json - Responses:
application/json(API), Apache Arrow IPC (job results), BibTeX/RIS (citations)
Error Format
{
"error": "Human-readable error message"
}
Standard HTTP status codes: 400 (bad request), 401 (unauthenticated), 403 (insufficient permissions), 404 (not found), 409 (conflict), 429 (rate limited).
Corpus status
GET /v1/neurodata/corpus is public and cached for five minutes. It states:
service_version: the API release serving the response;datasets: datasets in the ETL registry built into that release (registered), split by acquisition lifecycle (active,inactive) and by availability-gate state (by_state), next to the PostgreSQL metadata records and the public listing thatGET /v1/neurodata/datasetsreturns;tables: the registered(dataset, table)pairs by gate state;rows: rows held by available tables, by what one row is:neurons;connections(datasets imported as connection lists, such as neuPrint, FlyWire or connectome matrices: one row per connected pair with a source-dependent weight, usually its synapse count, so not a synapse count);synapses(individual synapse annotations); andcontacts(mesh contact patches, not annotated synapses). The ETL registry records the unit for each pipeline, and each named table carries its ownunit;named_datasets: per-table verdicts for registered datasets whose metadata is public. Datasets with non-public metadata are counted but not named.
A table is available only when its uploaded source state, released table
version and artifact manifest agree on row count and content hash, and the
ClickHouse serving table was verified and holds the same number of rows. Every
other state (unsupported, missing, pending, unreleased, mismatch) is
reported as its own category, and every count carries its unit and
definition. ClickHouse rows come from the latest corpus_inventory snapshot
(syndb data snapshot-corpus-inventory), never from a per-request scan:
as_of is when that snapshot counted them, and null means no snapshot is
readable, in which case no table can pass the gate. The operator ledger
syndb ops k8s etl availability applies the same gate to live ClickHouse counts.
syndb api corpus | jq '{service_version, as_of, registered: .datasets.registered.value, by_state: .datasets.by_state}'
Route Map
Public routes
GET /health— service health checkGET /v1/neurodata/corpus— corpus status; see Corpus statusPOST /v1/user/auth/registerPOST /v1/user/auth/loginPOST /v1/user/auth/register-servicePOST /v1/user/auth/refreshPOST /v1/user/auth/logoutGET /v1/search/fulltextGET /v1/federation/pingPOST /v1/federation/registerGET /v1/ontology/vocabulariesGET /v1/ontology/termsGET /v1/ontology/terms/{id}GET /v1/ontology/terms/{id}/childrenGET /v1/ontology/terms/{id}/ancestorsPOST /v1/ontology/terms/validate
Authenticated user routes
GET /v1/user/profilePATCH /v1/user/profilePOST /v1/user/profile/scientist-tagGET /v1/user/profile/{user_id}GET /v1/user/authenticate/cilogonGET /v1/user/authenticate/cilogon/authorize
Academic user routes
- Dataset metadata and assets:
POST /v1/neurodata/datasets,GET /v1/neurodata/datasets/owned,GET /v1/neurodata/datasets/modifiable,GET /v1/neurodata/datasets/incomplete,GET /v1/neurodata/datasets/{dataset_id},DELETE /v1/neurodata/datasets/{dataset_id},GET /v1/neurodata/datasets/{dataset_id}/provenance,GET /v1/neurodata/datasets/{dataset_id}/versions,GET /v1/neurodata/datasets/{dataset_id}/metadata.jsonld,GET /v1/neurodata/datasets/{dataset_id}/citation,GET /v1/neurodata/datasets/{dataset_id}/lineage,POST /v1/neurodata/datasets/{dataset_id}/lineage,POST /v1/neurodata/datasets/{dataset_id}/access/request,GET /v1/neurodata/datasets/{dataset_id}/access,GET /v1/neurodata/collections,POST /v1/neurodata/collections,GET /v1/neurodata/collections/{collection_id},DELETE /v1/neurodata/collections/{collection_id} - SyQL:
POST /v1/syql/plan,POST /v1/syql/explain,POST /v1/syql/exec - Saved queries:
GET /v1/queries,POST /v1/queries,POST /v1/queries/from-syql,GET /v1/queries/{id},PUT /v1/queries/{id},DELETE /v1/queries/{id},POST /v1/queries/{id}/run,POST /v1/queries/{id}/refresh - Jobs:
POST /v1/jobs,POST /v1/jobs/graph,GET /v1/jobs,GET /v1/jobs/{job_id},DELETE /v1/jobs/{job_id},GET /v1/jobs/{job_id}/result,POST /v1/jobs/{job_id}/rerun - Analytics:
GET /v1/analytics/summary,GET /v1/analytics/morphometrics,GET /v1/analytics/comparison,GET /v1/analytics/graph/{dataset_id}/summary,GET /v1/analytics/graph/{dataset_id}/reciprocity,GET /v1/analytics/graph/{dataset_id}/degree-distribution - Graph:
GET /v1/graph/{dataset_id}/metrics,POST /v1/graph/{dataset_id}/motifs,POST /v1/graph/{dataset_id}/motifs/compare-synapse-types,POST /v1/graph/{dataset_id}/shortest-path,POST /v1/graph/{dataset_id}/reachability,POST /v1/graph/{dataset_id}/reachability-curve,POST /v1/graph/{dataset_id}/full-analysis,GET /v1/graph/compare - Meta-analysis:
POST /v1/meta-analysis,GET /v1/meta-analysis/atlas/compare
SuperUser routes
- Federation administration:
GET /v1/federation/status,GET /v1/federation/schema,POST /v1/federation/schema/sync,GET /v1/federation/clusters,POST /v1/federation/clusters,DELETE /v1/federation/clusters/{cluster_id},POST /v1/federation/clusters/{cluster_id}/verify,POST /v1/federation/clusters/{cluster_id}/test/connectivity,POST /v1/federation/clusters/{cluster_id}/test/schema,POST /v1/federation/clusters/{cluster_id}/test/query,GET /v1/federation/benchmarks,POST /v1/federation/benchmarks,GET /v1/federation/benchmarks/aggregate - Ontology writes:
POST /v1/ontology/terms,PUT /v1/ontology/terms/{id},DELETE /v1/ontology/terms/{id},POST /v1/ontology/import/csv
Middleware Stack
Requests pass through these layers in order:
- Request ID — UUID v7, propagated via
X-Request-ID - Tracing — structured request/response logging
- Rate limiting — per-IP token bucket (see Rate Limiting)
- Timeout — 60s default, 408 on expiry
- CORS — permissive in dev mode, restricted to
api_domainin production - Compression — automatic response compression
- Body limit — 100 MB max request body
- API version —
api-version: v1response header
Health Check
curl https://api.syndb.xyz/health
{
"status": "healthy",
"components": {
"postgres": { "status": "ok", "latency_ms": 5 },
"clickhouse": { "status": "ok", "latency_ms": 12 },
"storage": { "status": "ok", "latency_ms": 8 },
"meilisearch": { "status": "ok" }
}
}
Status is degraded if any required component fails, or if Meilisearch is
configured but unreachable. Meilisearch is still optional — when it is unset,
the health payload reports meilisearch.status = "not_configured" without
degrading the overall status.