Build a Natural Language to SQL API in Python

Telnyx released a Python example that builds a natural language to SQL API using Telnyx AI Inference. The Flask app accepts plain-English questions, generates SQL via an AI model, and includes validation to reject unsafe queries. It also provides a sample SQLite dataset for testing without a production database.

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 https://github.com/team-telnyx/telnyx-code-examples/tree/main/sql-natural-language-python 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. 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: The model does the language translation. The app still owns the safety checks. 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 This is a small API, but it maps to real internal tooling: 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. Code: https://github.com/team-telnyx/telnyx-code-examples/tree/main/sql-natural-language-python 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 https://github.com/team-telnyx/ai Telnyx AI Inference docs: https://developers.telnyx.com/docs/inference https://developers.telnyx.com/docs/inference Chat Completions API: https://developers.telnyx.com/api/inference/chat-completions https://developers.telnyx.com/api/inference/chat-completions Telnyx Portal: https://portal.telnyx.com/ https://portal.telnyx.com/