# Build a Natural Language to SQL API in Python

> Source: <https://dev.to/sonam_50a41a4ced7e6b4f3fa/build-a-natural-language-to-sql-api-in-python-3a7p>
> Published: 2026-07-15 23:21:04+00:00

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/)