/ API Reference

REST API — everything you need

All endpoints are prefixed with /api/v1 and return JSON. The full endpoint reference — every field, schema, and error code — lives in the GitHub docs.

View full API reference on GitHub

Quick start

Base URL http://your-host:8000/api/v1

Authentication Authorization: Bearer <access_token>

Required on all endpoints except /auth/*

Errors {"detail": "Human-readable error message"}

Resource groups

Resource	Key endpoints	Description
`Auth`	`POST /auth/login, /auth/register, /auth/refresh`	JWT-based login, first-boot admin setup, and token rotation
`Connections`	`CRUD /connections/{id}`	Save and manage data source connections with encrypted credentials
`Schema`	`GET/POST /connections/{id}/schema`	Introspect and cache your database schema
`Semantic Model`	`GET/PUT /connections/{id}/semantic`	Business-layer metadata — display names, join hints, value mappings
`Chat`	`POST /chat`	Streaming NL→SQL pipeline over Server-Sent Events
`Sessions`	`GET /chat/sessions/{id}/history`	Conversation history per session, ordered chronologically
`Cache`	`GET /chat/cache/stats, DELETE /chat/cache/{id}`	Semantic query cache management and statistics
`Examples`	`GET/POST /chat/examples/{id}`	Verified question→SQL pairs used for few-shot prompting
`Providers`	`CRUD /providers/{type}`	LLM provider configs: Claude, Groq, Ollama, OpenAI-compatible
`Settings`	`GET/PUT /settings`	App-wide settings — cache TTL, row limits, log level

Chat endpoint

The core of the API. Runs the full NL→SQL pipeline and returns a streaming Server-Sent Events response. The final done event carries the complete ChatResponse.

POST /api/v1/chat

Request body

{
  "connection_id": "uuid",
  "session_id": null,
  "message": "How many customers signed up this month?",
  "provider": "uuid-of-provider-config",
  "options": {
    "show_query": true,
    "max_rows": 100,
    "explain_results": false
  }
}

Final SSE done event payload

{
  "session_id": "uuid",
  "message_id": "uuid",
  "query": "SELECT COUNT(*) FROM customers WHERE ...",
  "query_dialect": "PostgreSQL",
  "explanation": "Counts customers who signed up this month...",
  "results": {
    "columns": ["count"],
    "rows": [[1248]],
    "row_count": 1,
    "execution_time_ms": 12.4
  },
  "status": "executed",
  "cache_hit": false,
  "error": null
}

Status values: executedcachedpending_approvalquery_onlyerror

Execution modes

Set per connection via PUT /api/v1/connections/{id}/execution-mode.

Mode	Behaviour
`auto_execute`	Query is validated and run immediately — results returned in the same SSE stream
`review_first`	Query is held in pending_approval status until approved via POST /chat/execute/{message_id}
`generate_only`	SQL is generated and returned — never executed. Useful for DBA-review workflows

Full endpoint reference

Every endpoint, field description, request/response schema, and error code is documented in the GitHub repository. The Swagger UI is also available at http://your-host:8000/docs on any running instance.

View full API reference on GitHub