Build a Natural Language to SQL API in Python

Most data questions start in plain English. "Which customers spent the most?" "How many orders are pending?" "What products generated revenue last month?" Someone can turn those questions into SQL, but that usually means waiting on a developer, analyst, or dashboard update. This Python example shows how to build a small natural language to SQL API with Telnyx AI Inference.

Code: https://github.com/team-telnyx/telnyx-code-examples/tree/main/sql-natural-language-python

What it does

The Flask app exposes:

• POST /query
• POST /query/sample
• POST /validate
• GET /queries
• GET /queries/<id>
• GET /health

POST /query accepts a natural-language question, SQL dialect, and schema DDL. It returns structured JSON with the generated SQL, explanation, tables used, and metadata.

POST /query/sample uses a bundled SQLite sample dataset, so you can ask a question and see real rows come back without connecting a production database.

POST /validate dry-runs a SQL string against the sample dataset.

Why validation matters

Natural language to SQL needs guardrails. This example asks the model for read-only SQL and then checks the generated query before execution. The validation layer rejects multiple statements, comments, and write-oriented SQL keywords. That keeps the example focused on the useful workflow:

• ask a question
• include schema context
• generate a query
• validate the query
• return structured results

The model does the language translation. The app still owns the safety checks.

Run it

Clone the examples repo:

git clone https://github.com/team-telnyx/telnyx-code-examples.git
cd telnyx-code-examples/sql-natural-language-python

Create your .env file:

cp .env.example .env

Add your Telnyx API key:

TELNYX_API_KEY=your_telnyx_api_key
AI_MODEL=moonshotai/Kimi-K2.6
HOST=127.0.0.1

Install and start:

pip install -r requirements.txt
python app.py

Ask a question against the sample dataset:

curl -X POST http://localhost:5000/query/sample \
  -H "Content-Type: application/json" \
  -d '{"question": "Show me the top 3 customers by total order revenue"}' | python3 -m json.tool

Validate a query:

curl -X POST http://localhost:5000/validate \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT * FROM orders WHERE total > 100"}' | python3 -m json.tool

Where this could go

This is a small API, but it maps to real internal tooling:

• analytics assistants
• support dashboards
• sales operations tools
• data warehouse query helpers
• product usage exploration
• internal admin tools

The useful part is the boundary. The app does not blindly trust generated SQL. It asks for structured output, validates the query, and returns JSON that another system can inspect or display.

Resources

• Code: https://github.com/team-telnyx/telnyx-code-examples/tree/main/sql-natural-language-python
• Telnyx AI skills and toolkits: https://github.com/team-telnyx/ai
• Telnyx AI Inference docs: https://developers.telnyx.com/docs/inference
• Chat Completions API: https://developers.telnyx.com/api/inference/chat-completions
• Telnyx Portal: https://portal.telnyx.com/