Skip to content

Endpoints

Base URL

Environment URL
Local Development http://127.0.0.1:8000
Production (Fly.io) https://dbn-analytics-poc.fly.dev

Interactive Docs

Swagger UI: /api/docs · ReDoc: /api/redoc · Root: MkDocs documentation site

POST /api/v1/chat/generate-sql

Converts a natural language question into a SQL query string without executing it.

Use this endpoint when you want to:

  • Preview the generated SQL before running it
  • Debug or validate AI output
  • Build a query editor experience

Request

POST /api/v1/chat/generate-sql HTTP/1.1
Content-Type: application/json

{
  "question": "Which sector has the highest average predicted default probability?"
}

Response 200 OK

{
  "sql": "SELECT Sector, AVG(pred_default_prob) AS avg_risk\nFROM msmeloans\nGROUP BY Sector\nORDER BY avg_risk DESC\nLIMIT 5;"
}

POST /api/v1/chat/run-sql

Executes a raw SQL statement against the SQLite database and returns the result as a list of JSON objects.

Read-Only Recommended

This endpoint executes arbitrary SQL. Ensure that your deployment environment restricts write access to the database.

Request

POST /api/v1/chat/run-sql HTTP/1.1
Content-Type: application/json

{
  "sql": "SELECT Sector, AVG(AmountGranted) AS avg_loan FROM msmeloans GROUP BY Sector ORDER BY avg_loan DESC;"
}

Response 200 OK

{
  "data": [
    { "Sector": "Agriculture", "avg_loan": 5750000.0 },
    { "Sector": "Trade and Commerce", "avg_loan": 3200000.0 }
  ]
}

POST /api/v1/chat/ask ⭐

The primary RAG endpoint. Given a natural language question, this endpoint:

  1. Generates SQL (via Vanna + OpenAI)
  2. Executes the SQL (via SQLite)
  3. Optionally generates Plotly chart code

Request

POST /api/v1/chat/ask HTTP/1.1
Content-Type: application/json

{
  "question": "What is the average loan amount by sector?"
}

Response 200 OK

{
  "sql": "SELECT Sector, AVG(AmountGranted) AS avg_loan\nFROM msmeloans\nGROUP BY Sector\nORDER BY avg_loan DESC;",
  "data": [
    { "Sector": "Agriculture", "avg_loan": 5750000.0 },
    { "Sector": "Manufacturing", "avg_loan": 2800000.0 }
  ],
  "plotly_code": "import plotly.express as px\nfig = px.bar(df, x='Sector', y='avg_loan', title='Average Loan Amount by Sector')\nfig.show()"
}

Plotly code

plotly_code will be null if the dataset is empty or chart generation fails. The data and sql fields are always present on a 200 response.

Health Endpoints

Endpoint Method Description
/api GET Returns API name, version, and link map
/health GET Returns {"status": "ok"} for load balancer probes

OpenAPI Schema

The full machine-readable schema is available at: