ADA API › REST Reference

REST Reference

All endpoints use http://localhost:3001 as base URL. Authentication is Bearer JWT except health and auth endpoints.

Error Format

{
  "error": {
    "code":    "CONVERSATION_NOT_FOUND",
    "message": "Conversation abc123 introuvable",
    "status":  404
  }
}

Auth

POST /api/auth/token          # get JWT (rate-limit: 10 req/15min)
POST /api/auth/refresh        # refresh expiring token
DELETE /api/auth/session      # logout (revoke token)
GET  /api/auth/me             # current session info

Health

GET /api/health               # global status {ok, version, uptime}
GET /api/health/core          # IPC connection detail
GET /api/health/db            # SQLite WAL stats

Workspaces

GET    /api/workspaces           # list workspaces
POST   /api/workspaces           # create workspace
GET    /api/workspaces/:id       # get workspace
PATCH  /api/workspaces/:id       # update (name, description, color)
DELETE /api/workspaces/:id       # delete
GET    /api/workspaces/:id/stats # usage stats (runs, cost, tokens)

Conversations & Messages

GET    /api/workspaces/:wid/conversations   # list conversations
POST   /api/workspaces/:wid/conversations   # create conversation
GET    /api/conversations/:id              # get conversation
PATCH  /api/conversations/:id              # update (title, pinned, archived)
DELETE /api/conversations/:id              # delete

GET    /api/conversations/:id/messages     # cursor-paginated messages
POST   /api/conversations/:id/messages     # send message

# Cursor pagination
GET /api/conversations/:id/messages?limit=50&direction=before&cursor=<id>

Runs

POST   /api/runs                # spawn run → 202 {runId}
GET    /api/runs/:id            # run state + phases
DELETE /api/runs/:id            # cancel (SIGTERM)
POST   /api/runs/:id/retry      # restart from failed phase

# Spawn a run
curl -X POST http://localhost:3001/api/runs \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "implement user invitation", "profile": "fullstack", "conversationId": "conv-xxx" }'

Settings & Stats

GET   /api/settings                    # global instance settings
PATCH /api/settings                    # hot-reload (log_level, ws_heartbeat_interval)

GET   /api/stats/observe?window=7d     # usage stats (window: 7d|30d|session)
# → { pipelines: [...], daily: [...], topAgents: [...] }