Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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 apiRouteMCP tool
corpusGET /neurodata/corpusapi_corpus_status
datasetsGET /neurodata/datasetsapi_datasets
dataset IDGET /neurodata/datasets/{id}api_dataset (view: metadata)
table-versions IDGET /neurodata/datasets/{id}/table-versionsapi_dataset (view: table_versions)
derived-products IDGET /neurodata/datasets/{id}/derived-productsapi_dataset (view: derived_products)
summary ID...GET /analytics/summaryapi_dataset (view: summary)
graph-summary IDGET /analytics/graph/{id}/summaryapi_dataset (view: graph_summary)
search QUERYGET /search/fulltextapi_search
capabilitiesGET /app/capabilitiesapi_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.rs compares the committed openapi.json and client spec with the router, names the first stale path, and fails when CLIENT_OPERATIONS, the generated functions or the query-only enums (BenchmarkType, ExportFormat, ExportSchema) drift. The spec writer rejects $ref siblings that change validation and deepObject query 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.rs decodes real handler responses into the generated models.
  • scripts/openapi-generate.sh (run by just openapi) pins the generator to the flake’s root nixpkgs input (rev 0a3468a402c449992505b6a9fc5b06580141b750 -> 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 fmt or cargo check failure 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 that GET /v1/neurodata/datasets returns;
  • 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); and contacts (mesh contact patches, not annotated synapses). The ETL registry records the unit for each pipeline, and each named table carries its own unit;
  • 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 check
  • GET /v1/neurodata/corpus — corpus status; see Corpus status
  • POST /v1/user/auth/register
  • POST /v1/user/auth/login
  • POST /v1/user/auth/register-service
  • POST /v1/user/auth/refresh
  • POST /v1/user/auth/logout
  • GET /v1/search/fulltext
  • GET /v1/federation/ping
  • POST /v1/federation/register
  • GET /v1/ontology/vocabularies
  • GET /v1/ontology/terms
  • GET /v1/ontology/terms/{id}
  • GET /v1/ontology/terms/{id}/children
  • GET /v1/ontology/terms/{id}/ancestors
  • POST /v1/ontology/terms/validate

Authenticated user routes

  • GET /v1/user/profile
  • PATCH /v1/user/profile
  • POST /v1/user/profile/scientist-tag
  • GET /v1/user/profile/{user_id}
  • GET /v1/user/authenticate/cilogon
  • GET /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:

  1. Request ID — UUID v7, propagated via X-Request-ID
  2. Tracing — structured request/response logging
  3. Rate limiting — per-IP token bucket (see Rate Limiting)
  4. Timeout — 60s default, 408 on expiry
  5. CORS — permissive in dev mode, restricted to api_domain in production
  6. Compression — automatic response compression
  7. Body limit — 100 MB max request body
  8. API version — api-version: v1 response 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.