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.

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

Public routes

• GET /health — service health check
• 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, POST /v1/syql/cancel
• 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.