Developer docs

One endpoint. Natural language in, SQL out.

TTSQL is a single API call. Send a prompt and a project_id, get back SQL for the database connected to that project, ready for your application to review.

See the endpoint API overview

curl -X POST https://ttsql.com/api/v1 \
  -H "x-api-key: $TTSQL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Count all customers",
    "project_id": 1
  }'

Tutorial

From prompt to SQL in three steps.

To generate SQL, create a project in the dashboard so TTSQL knows your schema, generate an API key, then call /api/v1 with your prompt. The API returns reviewable SQL; execution remains an explicit action in the authenticated query workspace.

01 Create a project and connect its database/schema in the dashboard.
02 Generate an API key on the API Keys page.
03 POST a prompt to /api/v1 and read query from the response.

Guide 01

Make your first text-to-SQL request

Send a prompt and the project_id whose schema TTSQL should use. The response includes generated, reviewable SQL; the API does not execute it implicitly.

Generate SQL curl

curl -X POST https://ttsql.com/api/v1 \
  -H "x-api-key: $TTSQL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Count all customers",
    "project_id": 1
  }'

Errors, limits, and execution

Read the HTTP status before using a response. A successful generation returns a nonempty query and executed: false. The legacy execute flag does not execute SQL.

400: Missing or invalid prompt, invalid project ID, or rejected query. Correct the request or its project context before retrying.
401: Invalid API key. Check the server environment and key access.
404: Project not found or not accessible to this key.
429: Rate or plan limit reached. Respect Retry-After when present; check usage and avoid immediate repeated requests.
500: Server-side generation failure. Use bounded retries and surface the failure to the user.

Keep API keys on the server. Configure a timeout appropriate to generation, validate the response, and apply authorization and database permissions separately before executing any SQL. Account and request limits are visible in the workspace.

Endpoint reference

The whole API: one product endpoint, plus health and metrics.

TTSQL exposes a single text-to-SQL endpoint at POST /api/v1. Auth is via the x-api-key header. The two remaining routes are for ops: a liveness probe and Prometheus metrics.

Query

Text-to-SQL generation

The single endpoint applications call when users ask questions about data.

POST /api/v1 API key

Generate SQL from a prompt

Send a natural-language prompt and a project_id. TTSQL returns reviewable SQL without implicitly executing it against the connected database.

Request curl

curl -X POST https://ttsql.com/api/v1 \
  -H "x-api-key: $TTSQL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Count all customers",
    "project_id": 1
  }'

Response json

{
  "status": "success",
  "query": "SELECT COUNT(*) AS customer_count FROM customers",
  "executed": false,
  "execution": {"status": "not_requested"},
  "metadata": {
    "project_id": 1,
    "api_key_id": 42,
    "timestamp": "2026-05-25T14:30:00Z"
  }
}

Ops

Health & metrics

For monitors, status pages, and deploy checks.

GET /api/v1/health Public

Liveness probe

Returns 200 when the database health check succeeds, or 503 when degraded. Includes a timestamp and the application version as an Erlang character-code array (0.1.0 in this example).

Request curl

curl https://ttsql.com/api/v1/health

Response json

{
  "status": "ok",
  "timestamp": "2026-09-05T09:00:00Z",
  "version": [48, 46, 49, 46, 48]
}

GET /api/metrics Public

Export Prometheus metrics

Returns Prometheus exposition text for configured metrics. The example shows the fallback comment when the metrics reporter is unavailable.

Request curl

curl https://ttsql.com/api/metrics

Response text

# Prometheus metrics unavailable

Bring your next question to TTSQL.

Start with one PostgreSQL project and 20 free requests a day. Explore your data, build a report, or integrate the API.

Start free Contact sales