SQL Formatter API Documentation¶

Overview¶

The SQL Formatter API provides a robust way to format or transpile SQL queries between dialects.
It supports both synchronous (direct body input) and asynchronous (remote file or URL) operations.
This API ensures clean, readable SQL output and allows conversion between supported dialects.

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

Endpoint (POST)¶

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

Headers¶

Header	Description	Required	Example
`x-input-sql-dialect`	Input SQL dialect (e.g., `ansi`, `mysql`, `postgres`)	Optional	`mysql`
`x-output-sql-dialect`	Output SQL dialect (required when `x-format-mode` = `rewrite`)	Conditional	`postgres`
`x-format-mode`	Operation mode: `pretty` (format only) or `rewrite` (transpile)	Optional	`pretty`
`x-source-type`	Input source type: `body`, `url`, or `file`	Optional	`body`
`Content-Type`	MIME type of input	Required	`text/plain`
`x-api-key`	Your API key for authentication	Yes	`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¶

This tool accepts the following file extensions for URL or file mode:

.sql
.txt

Input Example (Body Mode)¶

select * from users where id=1

Input Example (URL Mode)¶

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

Input Example (File Mode)¶

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

Example Request¶

Synchronous (Body Input)¶

curl -X POST "https://api.apidatatools.com/sql-formatter-api" \
  -H "x-format-mode: pretty" \
  -H "x-input-sql-dialect: mysql" \
  -H "Content-Type: text/plain" \
  -H "x-api-key: YOUR_API_KEY" \
  -d "select * from users where id=1"

Asynchronous (Remote File URL)¶

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

Asynchronous (Input File)¶

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

Example Response¶

Successful (Body Mode)¶

{
  "request_id": "b7f8c2e1-9d3a-4f2b-8c9a-123456789abc",
  "status": "success",
  "file": "https://downloads.apidatatools.com/apidatatools_convert_abc123.sql",
  "preview": "SELECT *\nFROM users\nWHERE id = 1;\n"
}

Async Job Accepted¶

{
  "status": "accepted",
  "job_id": "job-1234567890abcdef",
  "status_url": "https://api.apidatatools.com/jobs/job-1234567890abcdef",
  "request_id": "b7f8c2e1-9d3a-4f2b-8c9a-123456789abc"
}

Error Handling¶

Error Code	HTTP Status	Description	Example
`INVALID_INPUT`	400	Input is not valid UTF-8 text	`{"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 is not supported	`{"error":"UNSUPPORTED_DIALECT","details":{"message":"Unsupported SQL dialect: 'xyz'."}}`
`MISSING_OUTPUT_DIALECT`	400	Missing output dialect when rewrite mode is used	`{"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: 'pretty', 'rewrite'."}}`
`FORMAT_FAILED`	400	Unable to format or transpile SQL	`{"error":"FORMAT_FAILED","details":{"message":"Unable to format the provided SQL."}}`
`SQL_SYNTAX_ERROR`	400	SQL contains syntax errors	`{"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	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: '.exe'"}}`
`FILE_UNAVAILABLE`	400	File cannot be accessed	`{"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:

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

Example Status Response for Async¶

{
  "job_id": "job-1234567890abcdef",
  "status": "success",
  "created_at": 1712345678,
  "updated_at": 1712345690,
  "result": {
    "request_id": "b7f8c2e1-9d3a-4f2b-8c9a-123456789abc",
    "status": "success",
    "file": "https://downloads.apidatatools.com/apidatatools_convert_abc123.sql",
    "preview": "SELECT *\nFROM users\nWHERE id = 1;\n"
  }
}

If the job is still processing:

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

If the job failed:

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

Notes for Developers¶

The API supports three input modes: body, url, and file.
For asynchronous operations (url or file), a job_id is returned with a status_url.
The output file is stored temporarily and accessible via a secure download link.
Always include request_id in logs and responses for traceability.
Ensure x-output-sql-dialect is provided when using rewrite mode.
The preview in responses is limited to the first 100 KB of formatted SQL.