HTML Formatter API Documentation¶

Overview¶

The HTML Formatter API formats and beautifies raw or minified HTML content into a properly indented and human-readable structure.
It supports three input modes:

Body Mode (direct HTML content in request body)
URL Mode (remote HTML file via URL)
File Mode (previously uploaded file reference)

The API returns a downloadable formatted HTML file and a preview snippet for quick inspection.

Endpoint (POST)¶

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

Headers¶

Header	Type	Required	Description
`Content-Type`	`application/json` or `text/plain`	Yes	Defines the content type of the request body.
`x-source-type`	`body` \| `url` \| `file`	Optional	Defines the input mode. Default is `body`.
`x-api-key`	`<API_KEY>`	Yes	API key for authentication.

Accepted File Extensions¶

Mode	Supported Extensions
URL / File	`.html`, `.txt`

Input Example (Body Mode)¶

<html><body><h1>Hello</h1><p>World</p></body></html>

Input Example (URL Mode)¶

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

Input Example (File Mode)¶

{
  "file": "user_uploads/upl_1234567890abcdef/sample.html"
}

Example Request¶

Synchronous (Body Input)¶

curl -X POST "https://api.apidatatools.com/html-formatter-api" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: text/plain" \
  -H "x-source-type: body" \
  --data "<html><body><h1>Hello</h1><p>World</p></body></html>"

Asynchronous (Remote File URL)¶

curl -X POST "https://api.apidatatools.com/html-formatter-api" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-source-type: url" \
  --data '{"url": "https://example.com/sample.html"}'

Asynchronous (Input File)¶

curl -X POST "https://api.apidatatools.com/html-formatter-api" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-source-type: file" \
  --data '{"file": "user_uploads/upl_1234567890abcdef/sample.html"}'

Example Response¶

Successful (Body Mode)¶

{
  "status": "success",
  "request_id": "b2a1e8c3-9f2d-4b9a-8d7a-123456789abc",
  "file": "https://downloads.apidatatools.com/apidatatools_convert_abcdef1234567890.html",
  "preview": "<html>\n <head>\n </head>\n <body>\n  <h1>\n   Hello\n  </h1>\n  <p>\n   World\n  </p>\n </body>\n</html>"
}

Async Job Accepted (URL or File Mode)¶

{
  "status": "accepted",
  "job_id": "a1b2c3d4-e5f6-7890-abcd-1234567890ef",
  "status_url": "https://api.apidatatools.com/jobs/a1b2c3d4-e5f6-7890-abcd-1234567890ef",
  "request_id": "b2a1e8c3-9f2d-4b9a-8d7a-123456789abc"
}

Error Handling¶

Error Code	HTTP Status	Message	Example
`INVALID_HTML`	400	HTML input must be a non-empty string	`{"status":"error","error":"INVALID_HTML","details":{"message":"HTML input must be a non-empty string"}}`
`HTML_FORMAT_ERROR`	400	Failed to Format HTML	`{"status":"error","error":"HTML_FORMAT_ERROR","details":{"message":"Failed to Format HTML."}}`
`INVALID_URL`	400	Missing or invalid 'url'	`{"status":"error","error":"INVALID_URL","details":{"message":"Missing or invalid 'url'."}}`
`URL_UNREACHABLE`	400	Could not reach URL	`{"status":"error","error":"URL_UNREACHABLE","details":{"message":"Could not reach URL"}}`
`URL_NOT_OK`	400	URL returned non-200 status	`{"status":"error","error":"URL_NOT_OK","details":{"message":"URL returned HTTP 404, expected 200."}}`
`FILE_TOO_LARGE`	413	File exceeds plan limit	`{"status":"error","error":"FILE_TOO_LARGE","details":{"message":"Remote file exceeds plan limit."}}`
`INVALID_FILE_EXTENSION`	400	Invalid or unsupported file extension	`{"status":"error","error":"INVALID_FILE_EXTENSION","details":{"message":"Extension '.pdf' is not allowed for 'html-formatter-api'."}}`
`INVALID_FILE`	400	Missing or invalid 'file'	`{"status":"error","error":"INVALID_FILE","details":{"message":"Missing or invalid 'file'."}}`
`FILE_UNAVAILABLE`	400	Could not access file	`{"status":"error","error":"FILE_UNAVAILABLE","details":{"message":"Could not access file"}}`
`PAYLOAD_TOO_LARGE`	413	Request body exceeds plan limit	`{"status":"error","error":"PAYLOAD_TOO_LARGE","details":{"message":"Request body exceeds 5120KB limit for your plan."}}`
`INTERNAL_ERROR`	500	Failed to process your request	`{"status":"error","error":"INTERNAL_ERROR","details":{"message":"Failed to process your request"}}`

Async Job Status¶

To check the status of an asynchronous job, use the status_url provided in the accepted response.

Endpoint¶

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

Example Status Response for Async¶

Queued / Processing¶

{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-1234567890ef",
  "status": "queued",
  "message": "Your job is being processed.",
  "retry_after": 2,
  "created_at": 1712345678,
  "updated_at": 1712345678
}

Success¶

{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-1234567890ef",
  "status": "success",
  "created_at": 1712345678,
  "updated_at": 1712345690,
  "result": {
    "status": "success",
    "request_id": "b2a1e8c3-9f2d-4b9a-8d7a-123456789abc",
    "file": "https://downloads.apidatatools.com/apidatatools_convert_abcdef1234567890.html",
    "preview": "<html>\n <body>\n  <h1>Hello</h1>\n </body>\n</html>"
  }
}

Failed¶

{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-1234567890ef",
  "status": "failed",
  "created_at": 1712345678,
  "updated_at": 1712345680,
  "error": {
    "code": "HTML_FORMAT_ERROR",
    "message": "Failed to Format HTML.",
    "details": {
      "message": "Invalid HTML structure"
    }
  }
}

Notes for Developers¶

The API supports synchronous and asynchronous processing.
Use x-source-type: body for immediate results or x-source-type: url|file for async jobs.
Each response includes a unique request_id for traceability.
Async jobs can be monitored via the /jobs/{job_id} endpoint.
The formatted HTML output is stored temporarily and accessible via the returned file URL.
Input validation ensures only .html and .txt files are accepted for URL or file-based requests.
Preview data is limited to the first 100 KB of the formatted output for quick inspection.