Developer docs

Build text-to-SQL into your product with a clean API.

Versioned endpoints, project-scoped context, governed query generation, and operational checks for production integrations.

View endpoints API overview

curl -X POST https://ttsql.com/api/v1/search \
  -H "Authorization: Bearer $TTSQL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "proj_live",
    "question": "Revenue by plan this month",
    "dialect": "postgres"
  }'

Tutorials

Start small, then add the guardrails your team needs.

The fastest path is to send one clear question, inspect the SQL and validation metadata, then decide whether to execute, format, optimize, or visualize the result. These examples use production-shaped requests so you can copy the pattern into a real integration.

01 Create a project and connect schema context.
02 Send a natural-language question to the search endpoint.
03 Review the generated SQL, warnings, and validation status.
04 Add policy checks, formatting, optimization, or charts as needed.

Guide 01

Make your first text-to-SQL request

Ask one business question and let TTSQL return SQL plus validation metadata. Start here when you want the shortest working integration.

Generate SQL curl

curl -X POST https://ttsql.com/api/v1/search \
  -H "Authorization: Bearer $TTSQL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "proj_live",
    "question": "Revenue by plan this month",
    "dialect": "postgres"
  }'

Guide 02

Validate SQL before anyone runs it

Use validation when you already have SQL and want TTSQL to catch syntax issues, risky patterns, or policy mismatches before execution.

Validate generated SQL curl

curl -X POST https://ttsql.com/api/v1/format/validate \
  -H "Authorization: Bearer $TTSQL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dialect": "postgres",
    "sql": "SELECT plan, SUM(amount) FROM invoices GROUP BY plan"
  }'

Guide 03

Turn a query result into a chart

After a query is generated or approved, send the result shape to the visualization endpoint and ask for the chart your user needs.

Create visualization curl

curl -X POST https://ttsql.com/api/v1/visualize/query \
  -H "Authorization: Bearer $TTSQL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query_id": "qry_revenue_by_plan",
    "chart": "bar",
    "x": "plan",
    "y": "revenue"
  }'

Endpoint guide

Every endpoint explained with request and response examples.

Use this reference when you are wiring TTSQL into an app. Each endpoint includes the job it is best for, the auth expectation, and a representative request/response pair.

Ops

Health & metrics

Use these endpoints in monitors, status pages, and deployment checks before sending user traffic.

GET /api/health/status Public

Check platform readiness

Use this for a lightweight uptime probe. It tells you whether the public API process is ready to accept traffic.

Request curl

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

Response json

{
  "status": "ok",
  "service": "ttsql",
  "version": "v1",
  "checks": {
    "api": "ready",
    "queue": "ready"
  }
}

GET /api/health/database Public

Check database connectivity

Use this during deploys or incident response to confirm TTSQL can reach its configured metadata store.

Request curl

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

Response json

{
  "status": "ok",
  "database": {
    "connected": true,
    "latency_ms": 18
  }
}

GET /api/health/ai-providers Public

Check model provider availability

Use this before routing text-to-SQL traffic. It reports whether the configured AI providers are reachable.

Request curl

curl https://ttsql.com/api/health/ai-providers

Response json

{
  "status": "ok",
  "providers": [
    {"name": "primary", "available": true},
    {"name": "fallback", "available": true}
  ]
}

GET /api/metrics Public

Export Prometheus metrics

Use this from Prometheus or another scraper to collect latency, error, and request counters.

Request curl

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

Response json

{
  "format": "prometheus",
  "scrape": "/api/metrics",
  "metrics": ["ttsql_requests_total", "ttsql_latency_ms"]
}

Query

Text-to-SQL generation

These are the endpoints most applications call when users ask questions about data.

POST /api/v1/search Rate limited

Generate SQL from a question

Use this when a user asks in plain English and you want SQL, confidence, and validation metadata back.

Request curl

curl -X POST https://ttsql.com/api/v1/search \
  -H "Authorization: Bearer $TTSQL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "proj_live",
    "question": "Revenue by plan this month",
    "dialect": "postgres"
  }'

Response json

{
  "query_id": "qry_01JZ7",
  "sql": "SELECT plan, SUM(amount) AS revenue FROM invoices GROUP BY plan",
  "validated": true,
  "confidence": 0.94
}

POST /api/v1/single Rate limited

Generate one focused query

Use this for simple application flows where you want one SQL statement and a compact explanation.

Request curl

curl -X POST https://ttsql.com/api/v1/single \
  -H "Authorization: Bearer $TTSQL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "proj_live",
    "question": "Top 10 customers by spend",
    "max_rows": 10
  }'

Response json

{
  "sql": "SELECT customer_id, SUM(total) AS spend FROM orders GROUP BY customer_id ORDER BY spend DESC LIMIT 10",
  "explanation": "Ranks customers by total order value.",
  "safe_to_run": true
}

POST /api/v1/fast/sql Rate limited

Generate SQL on the low-latency path

Use this for autocomplete-like experiences or internal tools where speed matters more than a long explanation.

Request curl

curl -X POST https://ttsql.com/api/v1/fast/sql \
  -H "Authorization: Bearer $TTSQL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schema_id": "sch_prod",
    "prompt": "daily signups by channel",
    "dialect": "postgres"
  }'

Response json

{
  "sql": "SELECT signup_date, channel, COUNT(*) FROM users GROUP BY signup_date, channel",
  "latency_ms": 420,
  "mode": "fast"
}

GET /api/v1/search/health Public

Check search generation health

Use this to monitor the text-to-SQL generation service separately from the rest of the API.

Request curl

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

Response json

{
  "status": "ok",
  "generation": "ready",
  "validators": "ready"
}

Visual

Visualize & export

Use these endpoints after a query is approved and you want to show the answer as a chart or export.

GET /api/v1/visualize/:id API key

Fetch a saved visualization

Use this when your UI needs to reload a chart that TTSQL already generated.

Request curl

curl https://ttsql.com/api/v1/visualize/viz_revenue_plan \
  -H "Authorization: Bearer $TTSQL_API_KEY"

Response json

{
  "id": "viz_revenue_plan",
  "chart": "bar",
  "status": "ready",
  "embed_url": "https://ttsql.com/embed/viz_revenue_plan"
}

POST /api/v1/visualize/query API key

Create a visualization from query output

Use this when you have a query result shape and want TTSQL to choose or build a clear chart.

Request curl

curl -X POST https://ttsql.com/api/v1/visualize/query \
  -H "Authorization: Bearer $TTSQL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query_id": "qry_01JZ7",
    "chart": "bar",
    "x": "plan",
    "y": "revenue"
  }'

Response json

{
  "id": "viz_01JZ8",
  "chart": "bar",
  "title": "Revenue by plan",
  "status": "ready"
}

POST /api/v1/visualize/export API key

Export a chart

Use this when a user needs a PNG, SVG, or embeddable chart payload outside the TTSQL workspace.

Request curl

curl -X POST https://ttsql.com/api/v1/visualize/export \
  -H "Authorization: Bearer $TTSQL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "visualization_id": "viz_01JZ8",
    "format": "png"
  }'

Response json

{
  "download_url": "https://ttsql.com/download/viz_01JZ8.png",
  "format": "png",
  "expires_in": 900
}

Format

Format & optimize

Use these endpoints when SQL already exists and you want it cleaner, safer, or faster.

POST /api/v1/format Rate limited

Format SQL for a dialect

Use this to make generated or user-written SQL readable before showing it in your product.

Request curl

curl -X POST https://ttsql.com/api/v1/format \
  -H "Authorization: Bearer $TTSQL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dialect": "postgres",
    "sql": "select * from invoices where paid_at is not null"
  }'

Response json

{
  "formatted_sql": "SELECT *\nFROM invoices\nWHERE paid_at IS NOT NULL;",
  "dialect": "postgres"
}

POST /api/v1/format/validate Rate limited

Validate SQL shape and safety

Use this before execution to catch syntax errors, unsupported dialect features, or policy concerns.

Request curl

curl -X POST https://ttsql.com/api/v1/format/validate \
  -H "Authorization: Bearer $TTSQL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dialect": "postgres",
    "sql": "SELECT plan, SUM(amount) FROM invoices GROUP BY plan"
  }'

Response json

{
  "valid": true,
  "warnings": [],
  "dialect": "postgres"
}

POST /api/v1/optimize Rate limited

Suggest query improvements

Use this when a query works but may be slow, expensive, or missing an obvious index-friendly pattern.

Request curl

curl -X POST https://ttsql.com/api/v1/optimize \
  -H "Authorization: Bearer $TTSQL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dialect": "postgres",
    "sql": "SELECT * FROM orders WHERE DATE(created_at) = CURRENT_DATE"
  }'

Response json

{
  "optimized_sql": "SELECT * FROM orders WHERE created_at >= CURRENT_DATE AND created_at < CURRENT_DATE + INTERVAL &#39;1 day&#39;",
  "notes": ["Avoid wrapping indexed created_at in DATE()."]
}

POST /api/v1/optimize/compare Rate limited

Compare optimization strategies

Use this when you want to show tradeoffs between readable SQL, index-friendly SQL, and warehouse cost.

Request curl

curl -X POST https://ttsql.com/api/v1/optimize/compare \
  -H "Authorization: Bearer $TTSQL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dialect": "postgres",
    "sql": "SELECT customer_id, COUNT(*) FROM orders GROUP BY customer_id",
    "strategies": ["readability", "performance"]
  }'

Response json

{
  "winner": "performance",
  "strategies": [
    {"name": "readability", "score": 0.82},
    {"name": "performance", "score": 0.91}
  ]
}

Policy

Security & governance

Use these endpoints when your app needs to explain, simulate, or enforce data-access rules.

GET /api/v1/policy/columns API key

List protected columns

Use this to show which columns are masked, blocked, or restricted for a project.

Request curl

curl https://ttsql.com/api/v1/policy/columns \
  -H "Authorization: Bearer $TTSQL_API_KEY"

Response json

{
  "project_id": "proj_live",
  "columns": [
    {"name": "customers.email", "policy": "mask"},
    {"name": "payments.card_number", "policy": "block"}
  ]
}

POST /api/v1/policy/simulate API key

Preview policy effects

Use this to explain how a query will change for a role before a user runs it.

Request curl

curl -X POST https://ttsql.com/api/v1/policy/simulate \
  -H "Authorization: Bearer $TTSQL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "analyst",
    "sql": "SELECT email, total FROM customers JOIN orders USING (customer_id)"
  }'

Response json

{
  "allowed": true,
  "rewritten_sql": "SELECT MASK(email), total FROM customers JOIN orders USING (customer_id)",
  "applied": ["mask customers.email"]
}

POST /api/v1/policy/evaluate API key

Evaluate a query against policy

Use this as a final gate when your product needs a pass/fail decision with audit-friendly reasons.

Request curl

curl -X POST https://ttsql.com/api/v1/policy/evaluate \
  -H "Authorization: Bearer $TTSQL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "support",
    "sql": "SELECT card_number FROM payments"
  }'

Response json

{
  "allowed": false,
  "reason": "payments.card_number is blocked for support",
  "policy_id": "pol_card_data"
}

GET /api/v1/rls/roles API key

List row-level security roles

Use this to populate role pickers and make sure generated SQL is evaluated with the same role your database uses.

Request curl

curl https://ttsql.com/api/v1/rls/roles \
  -H "Authorization: Bearer $TTSQL_API_KEY"

Response json

{
  "roles": [
    {"name": "analyst", "description": "Standard analytics access"},
    {"name": "support", "description": "Customer support access"}
  ]
}

Model

Semantic & federated layers

Use these endpoints when your schema has business vocabulary, curated metrics, or data across systems.

GET /api/v1/semantic/models API key

List semantic models

Use this to show available business models such as revenue, retention, or account health.

Request curl

curl https://ttsql.com/api/v1/semantic/models \
  -H "Authorization: Bearer $TTSQL_API_KEY"

Response json

{
  "models": [
    {"id": "sem_revenue", "name": "Revenue"},
    {"id": "sem_retention", "name": "Retention"}
  ]
}

POST /api/v1/semantic/query API key

Generate SQL with business context

Use this when users ask with company vocabulary like ARR, active account, churn, or qualified pipeline.

Request curl

curl -X POST https://ttsql.com/api/v1/semantic/query \
  -H "Authorization: Bearer $TTSQL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "sem_revenue",
    "question": "ARR by segment for this quarter"
  }'

Response json

{
  "sql": "SELECT segment, SUM(arr) FROM revenue_model WHERE quarter = CURRENT_QUARTER GROUP BY segment",
  "semantic_terms": ["ARR", "segment"]
}

GET /api/v1/federated/sources API key

List federated sources

Use this to show which warehouses, apps, or operational systems can be included in federated generation.

Request curl

curl https://ttsql.com/api/v1/federated/sources \
  -H "Authorization: Bearer $TTSQL_API_KEY"

Response json

{
  "sources": [
    {"id": "pg_prod", "type": "postgres", "status": "ready"},
    {"id": "sf_billing", "type": "snowflake", "status": "ready"}
  ]
}

POST /api/v1/federated/query API key

Generate a federated query plan

Use this when one answer needs context from more than one connected data source.

Request curl

curl -X POST https://ttsql.com/api/v1/federated/query \
  -H "Authorization: Bearer $TTSQL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sources": ["pg_prod", "sf_billing"],
    "question": "Open tickets for customers with unpaid invoices"
  }'

Response json

{
  "plan_id": "fed_01JZ9",
  "steps": ["query support tickets", "join unpaid invoices"],
  "status": "planned"
}

Enterprise

Bring natural-language SQL into a governed workspace.

Use TTSQL for teams that need SSO, policy controls, auditability, dedicated support, and deployment flexibility.

Create account Contact sales