REST + WebSocket reference for SynapCores Community Edition. Works with any HTTP client in any language — cURL, Node, Python, PHP samples per endpoint.
Before you start
All endpoints below are under /v1. Replace localhost:8080 with your own host:port.
Auth: both JWT and API key go in Authorization: Bearer …. The gateway picks the right validator from the token prefix (aidb_sk_… / ak_… for keys, JWTs are base64-segments). The legacy X-API-Key header is no longer accepted.
Response envelope: all success responses are wrapped as { data: …, meta: { request_id, timestamp } }. Raw HTTP clients must unwrap body.data; SDKs do this automatically.
Native SDKs for Node.js / TypeScript, Python, PHP / Laravel, Go, and Java / Spring Boot — see Install a native SDK just below. For every other language, the REST samples on this page are plain HTTP calls — no SDK required.
Node.js / TypeScript, Python, PHP, Go, and Java all ship a typed SDK that wraps the full Community Edition gateway surface — auth, SQL, graph, vectors, AI chat, AutoML, recipes, and more. Pick your language below; any other stack uses the REST samples that follow. Laravel users get a thin companion package on top of the PHP SDK (facade, artisan commands, Eloquent vector cast, queueable agent jobs); Spring Boot users get an auto-configured SynapCores bean plus an optional Actuator health indicator on top of the Java SDK.
// npm install @synapcores/sdk
import { SynapCores } from '@synapcores/sdk';
const client = new SynapCores({
host: 'localhost',
port: 8080,
apiKey: process.env.AIDB_API_KEY, // aidb_sk_… or ak_…
});
const result = await client.executeQuery({ sql: 'SELECT 1 AS ok' });
console.log(result);
Both SDKs follow the gateway surface — when the engine adds a route, the next SDK release wraps it. Pin a major version in your dependency manifest if you want lockstep upgrades. A Rust SDK and a machine-readable OpenAPI 3 spec are on the roadmap.
1. Authentication
Every request needs either a JWT (from /auth/login) or an API key — BOTH go in the Authorization header as "Bearer <token-or-key>". API keys with prefix ak_ or aidb_ are accepted; the prefix tells the server which key store to look up. (Legacy X-API-Key header was retired in the v1.6.5.2-ce wire-format alignment — current servers reject it.)
POST/v1/auth/login
Returns a JWT. If MFA is enabled the response includes mfa_required and you exchange via /v1/auth/mfa/verify.
Both auth schemes shown. Pick one — JWT for interactive sessions, API key for service-to-service.
# JWT (interactive sessions)
curl -s http://localhost:8080/v1/users/me -H "Authorization: Bearer $TOKEN"
# API key (preferred for backend services — same header)
curl -s http://localhost:8080/v1/users/me -H "Authorization: Bearer aidb_sk_..."
2. SQL execution
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 "Authorization: Bearer $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 "Authorization: Bearer $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.
Multi-turn conversational interface with server-side persistent memory. Bundled local LLM (Llama-3.2-1B GGUF) is the default for chat; configurable to OpenAI / Anthropic / Ollama / Cohere / HuggingFace. Note: the bundled 1B model is too small to drive AGENT_RUN tool calls reliably — for agentic workloads configure a tool-capable provider (qwen2.5-coder:7b via Ollama, gpt-4o-mini, claude-3.5-sonnet, etc).
POST/v1/ai/sessions
Create a chat session, get back a session_id you reuse for all messages.
NLP helpers — same request envelope, different endpoint per task.
# sentiment
curl -s -X POST http://localhost:8080/v1/ai/sentiment \
-H "Authorization: Bearer $AIDB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text":"the support was slow and the product never worked"}'
# summarize
curl -s -X POST http://localhost:8080/v1/ai/summarize \
-H "Authorization: Bearer $AIDB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text":"...long article...","max_length":120}'
9. Recipes
180+ hand-curated recipes ship with every CE binary; more live on the homepage at /recipes/ and can be imported by URL. List, fetch, execute, and bind your own parameters via REST. Recipes can themselves call EMBED, GENERATE, AGENT_RUN, and Cypher — they bundle schema + seed + workflow into one importable unit.
Import a recipe from a remote URL (synapcores.com/recipes/... or any reachable raw-markdown link). The recipe is parsed, validated, certified against the local engine version, and persisted so subsequent /execute calls find it. Useful for picking up community recipes without rebuilding the binary.
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 "Authorization: Bearer $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.
13. Inline SQL AI primitives — EMBED, GENERATE, AGENT_RUN
These are SQL functions you call inside any /v1/query/execute statement — no extra endpoint. EMBED returns a vector, COSINE_SIMILARITY scores it, GENERATE runs a one-shot LLM completion, and AGENT_RUN runs a full ReAct agent loop (tool calls, memory, multi-turn reasoning) as a single SQL value. Each ships with a minimum-version stamp below.
POST/v1/query/execute · EMBED + COSINE_SIMILARITY · Available v1.5.0-ce+
Generate a vector and search by meaning, inline in regular SQL. No separate /v1/vectors call. EMBED uses the engine's configured embedding model (MiniLM by default, 384-dim).
curl -s -X POST http://localhost:8080/v1/query/execute \
-H "Authorization: Bearer $AIDB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"sql": "SELECT title, COSINE_SIMILARITY(embedding, EMBED($1)) AS sim FROM docs ORDER BY sim DESC LIMIT 5",
"parameters": ["how long for refunds?"]
}'
POST/v1/query/execute · GENERATE · Available v1.6.0-ce+
Inline LLM completion as a SQL value. Useful for per-row classification, summarization, or response composition without round-tripping to /v1/ai/chat.
curl -s -X POST http://localhost:8080/v1/query/execute \
-H "Authorization: Bearer $AIDB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"sql": "SELECT ticket_id, GENERATE('"'"'Classify the urgency of this ticket as high, medium, or low: '"'"' || body) AS urgency FROM tickets WHERE created_at > NOW() - INTERVAL '"'"'1 day'"'"'"
}'
POST/v1/query/execute · AGENT_RUN · Available v1.7.0-ce+
Full ReAct agent loop callable as a SQL value. The agent runs server-side with access to the same database, calls tools (execute_query, rag_search, etc.), and returns a synthesized answer with citations. Wall-clock 5-60s — use a 120s HTTP timeout client-side. Requires a tool-capable LLM in [query.ai_service] — qwen2.5-coder:7b via Ollama, gpt-4o-mini, claude-3.5-sonnet, etc. The bundled native model is too small for tool calls.
curl -s -X POST http://localhost:8080/v1/query/execute \
-H "Authorization: Bearer $AIDB_API_KEY" \
-H "Content-Type: application/json" \
--max-time 120 \
-d '{
"sql": "SELECT AGENT_RUN($1, $2) AS recommendation",
"parameters": [
"aidb-assistant",
"Look at claim CX-9001. Use execute_query to check prior claims for fraud patterns and rag_search on policy_docs for applicable clauses. Output: recommended action with citations."
]
}'
14. MCP — Model Context Protocol
WebSocket JSON-RPC surface that exposes SynapCores as a tool server to any LLM agent — Claude Code, Cursor, OpenClaw, or your own ReAct loop. The LLM sees query / execute / list_tables / describe_table / rag_search / cypher / sql_manual as native function calls and invokes them on its own. Auth via the same Bearer token (no ticket exchange needed for MCP). Available v1.6.6.9-ce+.
WS/mcp?token=<jwt-or-api-key>
Connect, send JSON-RPC over the socket. Tool list, schemas, and arguments follow the MCP spec. Stdio variant available via the synapcores-mcp-bridge npm package for clients that don't speak WebSocket.
# Smoke test the MCP endpoint exists (returns 426 Upgrade Required on a non-WS GET)
curl -i "http://localhost:8080/mcp?token=$AIDB_API_KEY"
15. Transactions
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 "Authorization: Bearer $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 "Authorization: Bearer $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 "Authorization: Bearer $AIDB_API_KEY"
16. 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>.
Success envelope: every 2xx body is { "data": …, "meta": { "request_id", "timestamp" } }. Raw HTTP clients must unwrap body.data; SDKs do this for you.
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.
Row caps on /v1/query/execute(Available v1.7.0.1-ce+): pass "max_rows": N in the request to raise the cap, or set SQL_MAX_ROW_COUNT in the container env (default 1000). When a result was capped the response body carries data.truncated: true — clients should detect it, warn the user, and bump the cap. Phase 2 cursor pagination ships in v1.7.0.2-ce.
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. Individual features that aren't in every CE version are marked inline as "Available vX.Y.Z+".