Skip to content

API Reference

Overview

The REST API is built with FastAPI and served via Granian (ASGI). All endpoints require authentication via Authorization: Bearer <token> header unless noted.

Domain Routers

Ingestion (/v1/ingestion/*)

Method Endpoint Description
POST /v1/ingestion/jobs Create ingestion job (PubMed, bioRxiv, PMC, PDF upload)
GET /v1/ingestion/jobs List all ingestion jobs
GET /v1/ingestion/jobs/{job_id} Get job status and progress
DELETE /v1/ingestion/jobs/{job_id} Cancel a running job

PDF upload via multipart form data (10MB limit per file, max 50 per batch).

Query (/v1/sessions/*, /v1/evidence, /v1/communities/*)

Method Endpoint Description
POST /v1/sessions Create a query session
GET /v1/sessions/{id} Get session details
DELETE /v1/sessions/{id} Delete a session
POST /v1/sessions/{id}/query Execute a query (supports SSE streaming)
POST /v1/sessions/{id}/expand-knn KNN graph expansion
GET /v1/evidence/{protein}/{disease} Get evidence for an association
GET /v1/communities/{id} Get community summary

Workspace (/v1/cells/*, /v1/my-files/*, /v1/auto-discovery/*)

Method Endpoint Description
POST /v1/cells Create a cell
GET /v1/cells/{id} Get cell details
POST /v1/cells/{id}/execute Execute a cell
POST /v1/cells/{id}/branch Branch from a cell
POST /v1/my-files/upload Upload files for analysis
GET /v1/auto-discovery Auto-discover dataset patterns

Platform (/health, /v1/metrics/*, /v1/dashboard/*)

Method Endpoint Description
GET /health, /healthz Health check (includes Redis status)
GET /v1/metrics Comprehensive query intelligence metrics
GET /v1/metrics/multi-hop Multi-hop success/timeout rates
GET /v1/metrics/community Community summary usage
GET /v1/metrics/classification Query mode classification stats
GET /v1/metrics/disambiguation Entity disambiguation recall
GET /v1/metrics/latency Query latency percentiles (p50/p95/p99)
GET /v1/metrics/incremental-updates Pipeline update metrics
GET /v1/dashboard/overview Unified dashboard (ratings, perf, costs, feedback)
GET /v1/dashboard/agent-comparison Side-by-side agent comparison
GET /v1/cache/stats Precomputed cache statistics
POST /v1/cache/invalidate Invalidate cache for a database

Query Request Schema

{
  "question": "What proteins are associated with heart disease?",
  "mode": "hybrid",           // optional: local, global, hybrid, naive
  "search_depth": "balanced", // optional: fast, balanced, deep
  "hop_depth": 2,             // optional: 1-3 (default: 1)
  "stream": true,             // optional: enable SSE streaming
  "use_refrag": true          // optional: enable REFRAG compression
}

SSE Streaming Events

When stream: true:

event: retrieval_started
data: {"session_id": "...", "question": "...", "mode": "global"}

event: retrieval_complete
data: {"source_count": 12, "retrieval_time_ms": 340.5}

event: synthesis_started
data: {"session_id": "..."}

event: token
data: {"text": "Several", "index": 0}

event: complete
data: {"sources": [...], "cost": {...}, "answer": "..."}

Security

  • Authentication: Bearer token via API_AUTH_TOKEN env var
  • Rate Limiting: slowapi — 60/minute for query endpoints, 120/minute default
  • Input Sanitization: Cypher injection detection, PII scanning (presidio-analyzer)
  • Security Headers: X-Content-Type-Options, X-Frame-Options, CSP