Every request needs either a JWT (from /auth/login) or an API key (X-API-Key header). API keys with prefix ak_ or aidb_ are accepted; the prefix tells the server which key store to look up.
POST/v1/auth/login
Returns a JWT. If MFA is enabled the response includes mfa_required and you exchange via /v1/auth/mfa/verify.
Run parameterised SQL. Placeholders are PostgreSQL-style: $1, $2, $3 in the SQL string, parameters as a positional array. Returns columns metadata + rows.
Send a plain-English question, get back an executed query with rows. Schema-aware: the planner injects your live table catalog into the LLM prompt. Falls back to a deterministic pattern matcher when no LLM provider is configured.
POST/v1/nl2sql/query
curl -s -X POST http://localhost:8080/v1/nl2sql/query \
-H "X-API-Key: $AIDB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"question": "Show me top 5 products by revenue last quarter",
"execute": true
}'
4. Document collections
Schema-flexible JSON document stores with built-in vector + full-text indexing. Drop a JSON blob, add a vector field, do similarity search inline.
POST/v1/collections
Create a collection with typed fields and indexes.
Standalone vector store backed by HNSW. For pure-vector workloads (semantic search over embeddings, recommendation, RAG retrieval) without the document overhead.
Run Cypher queries against the property graph. Mix structural patterns, vector hops via SIMILAR_TO, and LLM-graded scoring with llm_score() in a single MATCH.
POST/v1/graph/match
Execute a Cypher query. Parameters use $name placeholders.
LLM-driven knowledge-graph extraction — send unstructured text, get back nodes and edges.
curl -s -X POST http://localhost:8080/v1/graph/extract \
-H "X-API-Key: $AIDB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"text": "In Q3 our CFO Susan Wong joined the call with CEO Tom Chen and confirmed Acme Corp acquired RegionTech for $40M.",
"graph": "earnings_calls"
}'
POST/v1/graph/algorithms
Run PageRank, Louvain (community detection), Label Propagation, or Triangle Count via CALL.
Drop a file into a watched folder and SynapCores automatically chunks + embeds + OCRs + transcribes. Manage collections via REST and stream live progress over WebSocket.
POST/v1/filesystem-collections
Create a watched folder. Returns a collection id and the inferred ingest plan.
WebSocket — live ingest events. Auth via short-lived ticket from POST /v1/ws/ticket.
// 1. exchange JWT/API key for a ticket
const { token } = await fetch('http://localhost:8080/v1/ws/ticket', {
method: 'POST',
headers: { 'X-API-Key': key },
}).then((r) => r.json());
// 2. open the websocket with the ticket on the URL
const ws = new WebSocket(
`ws://localhost:8080/ws/filesystem-collections/${id}/progress?token=${token}`,
);
ws.onmessage = (e) => console.log(JSON.parse(e.data));
11. Multimodal
Cross-modal similarity, search, and embeddings — text↔image↔audio. Configurable to OpenAI GPT-4o, Anthropic Claude, or local Ollama LLaVA via /v1/system/vision.
POST/v1/multimodal/search
Cross-modal search — query in any modality, results in any modality.
curl -s -X POST http://localhost:8080/v1/multimodal/search \
-H "X-API-Key: $AIDB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": {"text": "a red sports car at sunset"},
"modalities": ["image"],
"limit": 10
}'
POST/v1/multimodal/embed
Get an embedding for a text/image/audio/video input.
ACID transactions over REST. Begin → execute → commit/rollback, with optional named savepoints.
POST/v1/transactions
Begin a transaction, get back a transaction id.
# 1. begin
TX=$(curl -s -X POST http://localhost:8080/v1/transactions \
-H "X-API-Key: $AIDB_API_KEY" | jq -r .id)
# 2. execute one or more statements in the tx
curl -s -X POST http://localhost:8080/v1/transactions/$TX/execute \
-H "X-API-Key: $AIDB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"sql":"UPDATE accounts SET balance = balance - $1 WHERE id = $2","parameters":[100,"acc_1"]}'
# 3. commit
curl -s -X POST http://localhost:8080/v1/transactions/$TX/commit \
-H "X-API-Key: $AIDB_API_KEY"
14. WebSocket
The WebSocket endpoint at /ws handles streaming SQL execution, AI chat streaming, and live subscriptions. Auth uses a short-lived ticket exchange — never put a long-lived JWT or API key directly on the WS URL. Get a ticket from POST /v1/ws/ticket, then connect with ?token=<ticket>.
Status codes follow standard REST: 2xx success, 4xx user error, 5xx server error. 401 = bad/expired auth, 403 = authenticated but not authorized, 404 = not found, 409 = conflict (duplicate key), 429 = rate-limited.
Pagination: limit + offset on list endpoints. Cursor-based pagination on hot paths returns next_cursor in the body.
Rate limits: per-tenant default 60 RPS, burst 120. Response headers include X-RateLimit-Remaining and X-RateLimit-Reset.
Idempotency: send Idempotency-Key header on POST/PUT to make retries safe.
Versioning: every endpoint is namespaced under /v1. Breaking changes ship under /v2 with a deprecation window.
Prefer a typed driver?
Native SDKs are in active development. Node.js / Python / Rust catch up to the full v1.5.0-ce surface in v0.2.0 — request early access from the contact form.