HTML Encoder API Documentation¶

Overview¶

The HTML Encoder API converts raw HTML content into a safely escaped version, preventing special characters from being interpreted as HTML tags.
It supports body, url, and file input modes.
When using url or file mode, the operation runs asynchronously, and a job ID is returned for status tracking.

Base URL:
https://api.apidatatools.com/html-encoder-api

Endpoint (POST)¶

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

Headers¶

Header	Description	Required	Example
`Content-Type`	MIME type of the request body	Yes	`application/json`
`x-source-type`	Input source type (`body`, `url`, or `file`)	Optional (defaults to `body`)	`body`
`x-api-key`	API key	Yes	`<api_key>`

Accepted File Extensions¶

This tool accepts the following file extensions when using url or file mode:

.txt
.html

Input Example (Body Mode)¶

<div>Hello & Welcome</div>

Input Example (URL Mode)¶

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

Input Example (File Mode)¶

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

Example Request¶

Synchronous (Body Input)¶

curl -X POST "https://api.apidatatools.com/html-encoder-api" \
  -H "Content-Type: application/json" \
  -H "x-source-type: body" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '<div>Hello & Welcome</div>'

Asynchronous (Remote File URL)¶

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

Asynchronous (Input File)¶

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

Example Response¶

Successful (Body Mode)¶

{
  "status": "success",
  "request_id": "c4b8e9f2-1234-4a9b-9cde-5678abcd9012",
  "file": "https://downloads.apidatatools.com/apidatatools_convert_abc123.html",
  "preview": "&lt;div&gt;Hello &amp; Welcome&lt;/div&gt;"
}

Async Job Accepted¶

{
  "status": "accepted",
  "job_id": "job-12345678-abcd-efgh-ijkl-9876543210",
  "status_url": "https://api.apidatatools.com/jobs/job-12345678-abcd-efgh-ijkl-9876543210",
  "request_id": "c4b8e9f2-1234-4a9b-9cde-5678abcd9012"
}

Error Handling¶

Error Code	HTTP Status	Description	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_ENCODE_ERROR`	400	Failed to encode HTML	`{"status":"error","error":"HTML_ENCODE_ERROR","details":{"message":"Failed to Encode HTML."}}`
`INVALID_BODY_ENCODING`	400	Failed to decode base64 body	`{"status":"error","error":"INVALID_BODY_ENCODING","details":{"message":"Failed to base64-decode request body."}}`
`EMPTY_BODY`	400	Request body is empty	`{"status":"error","error":"EMPTY_BODY","details":{"message":"Request body is empty."}}`
`FILE_TOO_LARGE`	413	File exceeds plan limit	`{"status":"error","error":"FILE_TOO_LARGE","details":{"message":"File exceeds plan limit."}}`
`INVALID_URL`	400	Invalid or missing 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"}}`
`INVALID_FILE_EXTENSION`	400	Unsupported file extension	`{"status":"error","error":"INVALID_FILE_EXTENSION","details":{"message":"Invalid or unsupported file extension"}}`
`INTERNAL_ERROR`	500	Unexpected server error	`{"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 following endpoint:

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

Example Status Response for Async¶

{
  "job_id": "job-12345678-abcd-efgh-ijkl-9876543210",
  "status": "success",
  "created_at": 1712345678,
  "updated_at": 1712345689,
  "result": {
    "status": "success",
    "request_id": "c4b8e9f2-1234-4a9b-9cde-5678abcd9012",
    "file": "https://downloads.apidatatools.com/apidatatools_convert_abc123.html",
    "preview": "&lt;div&gt;Hello &amp; Welcome&lt;/div&gt;"
  }
}

If the job is still processing:

{
  "job_id": "job-12345678-abcd-efgh-ijkl-9876543210",
  "status": "queued",
  "message": "Your job is being processed.",
  "retry_after": 2
}

If the job failed:

{
  "job_id": "job-12345678-abcd-efgh-ijkl-9876543210",
  "status": "failed",
  "error": {
    "code": "HTML_ENCODE_ERROR",
    "message": "Failed to Encode HTML.",
    "details": {"message": "Encoding failed due to invalid characters"}
  }
}

Notes for Developers¶

For large files or remote URLs, use x-source-type: url or x-source-type: file to trigger asynchronous processing.
The preview field contains the first 100KB of encoded content for quick inspection.
The returned file URL is temporary and expires based on your plan’s retention policy.
Each response includes a unique request_id for tracking and debugging.
Use the status API to poll job progress when using asynchronous modes.
Ensure file extensions match the accepted list (.txt, .html) to avoid validation errors.