ADA API Overview
ada-api is the gateway between ada-core and ada-ui. It translates IPC events into WebSocket broadcasts, persists conversations and workspaces, and exposes a REST API for all UI actions.
What ada-api owns
Conversations
Chat threads with messages and run associations
Workspaces
Project isolation with settings and stats
Sessions
JWT auth tokens (revocable via /api/auth/session DELETE)
run_links
Bridge table linking ada-core run IDs to conversations
What ada-api does NOT own
Runs, trajectories, phases, agents, configs, routing priors — all owned by ada-core. ada-api only stores metadata references (run IDs, status) via run_links.
Stack
Runtime: Node.js 22 LTS
Framework: Fastify 4.x
WebSocket: @fastify/websocket 8.x
ORM: Drizzle ORM 0.30.x
Database: SQLite (better-sqlite3 9.x) — WAL mode
Auth: JWT via jose 5.x
IPC: net.Socket (Unix domain or TCP)
Tests: Vitest 1.x + supertest 7.xQuick Start
# Start ada-api (part of ada server start)
ada server start
# Or standalone
cd ada-api && npm start
# Base URL
http://localhost:3001
# Get a JWT token
curl -X POST http://localhost:3001/api/auth/token \
-H "Content-Type: application/json" \
-d '{"password": "your-secret"}'
# → { "token": "eyJ...", "expiresIn": 3600 }Endpoint Groups
| Group | Base Path | Auth |
|---|---|---|
| Auth | /api/auth/* | No (token endpoint) |
| Health | /api/health/* | No |
| Workspaces | /api/workspaces/* | Bearer JWT |
| Conversations | /api/workspaces/:id/conversations | Bearer JWT |
| Messages | /api/conversations/:id/messages | Bearer JWT |
| Runs | /api/runs/* | Bearer JWT |
| Settings | /api/settings | Bearer JWT |
| Stats | /api/stats/* | Bearer JWT |
| WebSocket | /ws?ticket=<uuid> | One-time ticket |