SQL Minify API Documentation¶

Overview¶

The SQL Minify API provides functionality to minify or transpile SQL queries between dialects.
It supports both synchronous (direct body input) and asynchronous (remote file or URL) processing.
The API can handle SQL text input and return a minified SQL file output.

Base URL:
https://api.apidatatools.com/sql-minify-api

Endpoint (POST)¶

POST https://api.apidatatools.com/sql-minify-api

Headers¶

Header	Type	Required	Description
`x-input-sql-dialect`	string	optional	Input SQL dialect (default: `ansi`)
`x-output-sql-dialect`	string	required when `x-format-mode` = `rewrite`	Target SQL dialect for transpilation
`x-format-mode`	string	optional	Formatting mode: `compact` (default) or `rewrite`
`x-source-type`	string	optional	Input source type: `body`, `url`, or `file`
`Content-Type`	string	required	Must be `text/plain` or `application/json` depending on mode
`x-api-key`	string	Yes	Your API key for authentication `abcd1234xyz`

Supported dialects: tsql, athena, bigquery, clickhouse, databricks, doris, dremio, drill, druid, duckdb, dune, exasol, fabric, hive, materialize, mysql, oracle, postgres, presto, prql, redshift, risingwave, singlestore, snowflake, solr, spark, spark2, sqlite, starrocks, tableau, teradata, trino

Accepted File Extensions¶

Supported extensions for this tool: - .sql - .txt

Input Example (Body Mode)¶

SELECT * FROM users WHERE id = 1;

Headers:

x-format-mode: compact
x-input-sql-dialect: ansi
x-output-sql-dialect: postgres
x-api-key: YOUR_API_KEY

Input Example (URL Mode)¶

{
  "url": "https://example.com/sample.sql"
}

Headers:

x-source-type: url
x-format-mode: rewrite
x-input-sql-dialect: mysql
x-output-sql-dialect: postgres
x-api-key: YOUR_API_KEY

Input Example (File Mode)¶

{
  "file": "user_uploads/sample.sql"
}

Headers:

x-source-type: file
x-format-mode: compact
x-input-sql-dialect: ansi
x-output-sql-dialect: postgres
x-api-key: YOUR_API_KEY

Example Request¶

Synchronous (Body Input)¶

curl -X POST "https://api.apidatatools.com/sql-formatter-api" \
  -H "Content-Type: text/plain" \
  -H "x-format-mode: compact" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-input-sql-dialect: ansi" \
  -H "x-output-sql-dialect: postgres" \
  --data "SELECT id, name FROM customers WHERE active = 1;"

Asynchronous (Remote File URL)¶

curl -X POST "https://api.apidatatools.com/sql-formatter-api" \
  -H "Content-Type: application/json" \
  -H "x-source-type: url" \
  -H "x-format-mode: rewrite" \
  -H "x-input-sql-dialect: mysql" \
  -H "x-output-sql-dialect: postgres" \
  -H "x-api-key: YOUR_API_KEY" \
  --data '{"url": "https://example.com/data.sql"}'

Asynchronous (Input File)¶

curl -X POST "https://api.apidatatools.com/sql-formatter-api" \
  -H "Content-Type: application/json" \
  -H "x-source-type: file" \
  -H "x-format-mode: compact" \
  -H "x-input-sql-dialect: ansi" \
  -H "x-output-sql-dialect: postgres" \
  -H "x-api-key: YOUR_API_KEY" \
  --data '{"file": "uploads/user123/query.sql"}'

Example Response¶

Successful (Body Mode)¶

{
  "request_id": "b1a2c3d4e5",
  "status": "success",
  "file": "https://downloads.apidatatools.com/apidatatools_convert_abc123.sql",
  "preview": "SELECT id, name FROM customers WHERE active = 1;"
}

Async Job Accepted¶

{
  "status": "accepted",
  "job_id": "job-12345",
  "status_url": "https://api.apidatatools.com/jobs/job-12345",
  "request_id": "req-67890"
}

Error Handling¶

Error Code	HTTP Status	Description	Example
`INVALID_INPUT`	400	Input is not a valid UTF-8 string	`{"error":"INVALID_INPUT","details":{"message":"SQL content must be plain UTF-8 text."}}`
`EMPTY_SQL`	400	SQL query is empty or whitespace only	`{"error":"EMPTY_SQL","details":{"message":"SQL query is empty or contains only whitespace."}}`
`UNSUPPORTED_DIALECT`	400	Provided dialect not supported	`{"error":"UNSUPPORTED_DIALECT","details":{"message":"Unsupported SQL dialect: 'xyz'."}}`
`MISSING_OUTPUT_DIALECT`	400	Output dialect missing for rewrite mode	`{"error":"MISSING_OUTPUT_DIALECT","details":{"message":"Output dialect is required when using rewrite mode."}}`
`INVALID_FORMAT_MODE`	400	Invalid format mode provided	`{"error":"INVALID_FORMAT_MODE","details":{"message":"Invalid format mode. Supported: 'compact', 'rewrite'."}}`
`FORMAT_FAILED`	400	SQL could not be formatted	`{"error":"FORMAT_FAILED","details":{"message":"Unable to format the provided SQL."}}`
`SQL_SYNTAX_ERROR`	400	SQL syntax invalid	`{"error":"SQL_SYNTAX_ERROR","details":{"message":"The provided SQL contains syntax errors."}}`
`INTERNAL_FORMATTER_ERROR`	500	Unexpected internal error	`{"error":"INTERNAL_FORMATTER_ERROR","details":{"message":"An unexpected error occurred during processing."}}`
`FILE_TOO_LARGE`	413	File exceeds plan limit	`{"error":"FILE_TOO_LARGE","details":{"message":"Remote file exceeds plan limit."}}`
`INVALID_URL`	400	Invalid or missing URL	`{"error":"INVALID_URL","details":{"message":"URL must be valid http/https."}}`
`URL_UNREACHABLE`	400	Remote URL cannot be reached	`{"error":"URL_UNREACHABLE","details":{"message":"Could not reach URL."}}`
`URL_NOT_OK`	400	URL returned non-200 status	`{"error":"URL_NOT_OK","details":{"message":"URL returned HTTP 404, expected 200."}}`
`INVALID_FILE_EXTENSION`	400	File extension not allowed	`{"error":"INVALID_FILE_EXTENSION","details":{"message":"Invalid or unsupported file extension."}}`
`FILE_UNAVAILABLE`	400	File not accessible	`{"error":"FILE_UNAVAILABLE","details":{"message":"Could not access file."}}`
`INVALID_SOURCE_TYPE`	400	Source type must be `url` or `file`	`{"error":"INVALID_SOURCE_TYPE","details":{"message":"Must be 'url' or 'file'."}}`

Async Job Status¶

To check the status of an asynchronous job, use the Status API:

GET https://api.apidatatools.com/jobs/{job_id}

Example Status Response for Async¶

Queued¶

{
  "job_id": "job-12345",
  "status": "queued",
  "message": "Your job is being processed.",
  "retry_after": 2
}

Success¶

{
  "job_id": "job-12345",
  "status": "success",
  "created_at": 1712345678,
  "updated_at": 1712345690,
  "result": {
    "request_id": "req-67890",
    "status": "success",
    "file": "https://downloads.apidatatools.com/apidatatools_convert_abc123.sql",
    "preview": "SELECT id, name FROM customers WHERE active = 1;"
  }
}

Failed¶

{
  "job_id": "job-12345",
  "status": "failed",
  "error": {
    "code": "SQL_SYNTAX_ERROR",
    "message": "The provided SQL contains syntax errors.",
    "details": {}
  }
}

Notes for Developers¶

The API supports three modes: body, url, and file.
When x-source-type is url or file, the request is processed asynchronously and returns a job_id.
Use the Status API to poll job progress or retrieve results.
The output file is uploaded to a secure storage and accessible via the returned file URL.
Always include request_id in logs or client-side tracking for debugging and correlation.
Supported dialects are dynamically derived from sqlglot dialect classes.
compact mode preserves SQL structure without rewriting; rewrite mode performs dialect conversion.