API Overview

Base URL: https://api.syndb.xyz/v1

Interactive OpenAPI documentation: api.syndb.xyz/docs

OpenAPI spec: GET /openapi.json

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).

Route Map

No Authentication Required

Method	Path	Description
GET	`/health`	Service health check (Postgres, ClickHouse, S3, Meilisearch)
POST	`/v1/user/auth/login`	Login
POST	`/v1/user/auth/register`	Register
POST	`/v1/user/auth/register-service`	Register service account (`X-Service-Secret`)
POST	`/v1/user/auth/refresh`	Refresh token
POST	`/v1/user/auth/logout`	Logout
GET	`/v1/user/profile/{user_id}`	Public profile lookup
GET	`/v1/search`	Full-text dataset search
GET	`/v1/federation/ping`	Federation health
POST	`/v1/federation/register`	Cluster self-registration (federation password)

Authenticated User (AuthUser)

Method	Path	Description
GET	`/v1/user/profile`	Current user profile
PATCH	`/v1/user/profile`	Update profile
POST	`/v1/user/profile/scientist-tag`	Generate scientist tag
GET	`/v1/user/authenticate/cilogon`	Academic metadata

Academic / Verified User (AcademicUser)

Method	Path	Description
POST	`/v1/neurodata/datasets`	Register dataset
GET	`/v1/neurodata/datasets/owned`	User’s datasets
POST	`/v1/neurodata/download-urls`	Pre-signed S3 download URLs
POST	`/v1/syql/plan`	Parse and validate SyQL
POST	`/v1/syql/exec`	Execute SyQL query
POST	`/v1/syql/explain`	Explain query plan
POST	`/v1/syql/cancel`	Cancel running query
GET	`/v1/queries`	List saved queries
POST	`/v1/queries`	Save query
POST	`/v1/queries/{id}/run`	Execute saved query
POST	`/v1/jobs`	Submit query job
POST	`/v1/jobs/graph`	Submit graph analysis job
GET	`/v1/jobs`	List jobs
GET	`/v1/jobs/{id}/result`	Download job result
GET	`/v1/analytics/{id}/summary`	Dataset summary stats
GET	`/v1/analytics/{id}/neuron-morphometrics`	Morphometric statistics
GET	`/v1/analytics/{id}/graph-summary`	Graph-level statistics
GET	`/v1/analytics/{id}/reciprocity`	Synapse reciprocity
GET	`/v1/analytics/{id}/degree-distribution`	Degree distribution
GET	`/v1/analytics/zscore-comparison`	Z-score comparison
GET	`/v1/graph/{id}/metrics`	Graph metrics
POST	`/v1/graph/{id}/motifs`	Triadic census
POST	`/v1/graph/{id}/shortest-path`	Shortest path
POST	`/v1/graph/{id}/reachability`	Reachability analysis
POST	`/v1/graph/{id}/full-analysis`	Full graph analysis
POST	`/v1/graph/compare`	Cross-dataset comparison
POST	`/v1/meta-analysis/analyze`	Cross-dataset meta-analysis
POST	`/v1/meta-analysis/atlas-compare`	Atlas comparison

SuperUser

Method	Path	Description
GET	`/v1/federation/status`	Federation overview
GET	`/v1/federation/clusters`	List clusters
POST	`/v1/federation/clusters`	Register cluster
DELETE	`/v1/federation/clusters/{id}`	Deactivate cluster
POST	`/v1/federation/schema/sync`	Sync schema to clusters
POST	`/v1/ontology/terms`	Create ontology term
PUT	`/v1/ontology/terms/{id}`	Update term
POST	`/v1/ontology/import-csv`	Bulk import terms

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_domain in production
Compression — automatic response compression
Body limit — 100 MB max request body
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 component fails. Meilisearch is optional — its absence does not degrade the overall status.

Keyboard shortcuts

Synapse DB