HTML Decoder API Documentation¶

Overview¶

The HTML Decoder API decodes HTML-encoded strings into their readable text form.
It supports three input modes:

Body Mode (direct text input)
URL Mode (remote file URL)
File Mode (uploaded file reference)

The API can process HTML content synchronously (for direct body input) or asynchronously (for remote URL or uploaded file).

Endpoint (POST)¶

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

Headers¶

Header	Description	Required	Example
`Content-Type`	MIME type of the request body	Yes	`application/json`
`x-api-key`	Your API key for authentication	Yes	`abcd1234xyz`
`x-source-type`	Input source type: `body`, `url`, or `file`	Optional (default: `body`)	`body`

Accepted File Extensions¶

Mode	Allowed Extensions
URL / File	`txt`, `html`

Input Example (Body Mode)¶

&lt;h1&gt;Hello World&lt;/h1&gt;

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-decoder-api" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-source-type: body" \
  -d '&lt;p&gt;Decoded Text&lt;/p&gt;'

Asynchronous (Remote File URL)¶

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

Asynchronous (Input File)¶

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

Example Response¶

Successful (Body Mode)¶

{
  "status": "success",
  "request_id": "f3a1c2d4-5678-90ab-cdef-1234567890ab",
  "file": "https://downloads.apidatatools.com/apidatatools_convert_abc123.html",
  "preview": "<p>Decoded Text</p>"
}

Async Job Accepted (URL or File Mode)¶

{
  "status": "accepted",
  "job_id": "job_123e4567-e89b-12d3-a456-426614174000",
  "status_url": "https://api.apidatatools.com/jobs/job_123e4567-e89b-12d3-a456-426614174000",
  "request_id": "req_9876543210abcdef"
}

Error Handling¶

Error Code	HTTP Status	Description	Example
`INVALID_HTML`	400	Input is empty or not a valid string	`{"status":"error","error":"INVALID_HTML","details":{"message":"HTML input must be a non-empty string"}}`
`HTML_DECODE_ERROR`	400	Failed to decode HTML content	`{"status":"error","error":"HTML_DECODE_ERROR","details":{"message":"Failed to Decode HTML."}}`
`INVALID_URL`	400	Invalid or missing URL in URL mode	`{"status":"error","error":"INVALID_URL","details":{"message":"Missing or invalid 'url'."}}`
`URL_UNREACHABLE`	400	URL could not be reached	`{"status":"error","error":"URL_UNREACHABLE","details":{"message":"Could not reach URL"}}`
`URL_NOT_OK`	400	URL returned non-200 HTTP 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	File extension not allowed	`{"status":"error","error":"INVALID_FILE_EXTENSION","details":{"message":"Invalid or unsupported file extension"}}`
`FILE_UNAVAILABLE`	400	File not accessible in storage	`{"status":"error","error":"FILE_UNAVAILABLE","details":{"message":"Could not access file"}}`
`EMPTY_BODY`	400	Request body is empty	`{"status":"error","error":"EMPTY_BODY","details":{"message":"Request body is empty."}}`
`PAYLOAD_TOO_LARGE`	413	Request body exceeds plan limit	`{"status":"error","error":"PAYLOAD_TOO_LARGE","details":{"message":"Request body exceeds limit"}}`
`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 status_url returned in the accepted response.

Endpoint¶

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

Example Status Response for Async¶

Queued or Processing¶

{
  "job_id": "job_123e4567-e89b-12d3-a456-426614174000",
  "status": "queued",
  "message": "Your job is being processed.",
  "retry_after": 2,
  "created_at": 1712345678,
  "updated_at": 1712345678
}

Successful Completion¶

{
  "job_id": "job_123e4567-e89b-12d3-a456-426614174000",
  "status": "success",
  "created_at": 1712345678,
  "updated_at": 1712345690,
  "result": {
    "status": "success",
    "request_id": "f3a1c2d4-5678-90ab-cdef-1234567890ab",
    "file": "https://downloads.apidatatools.com/apidatatools_convert_abc123.html",
    "preview": "<p>Decoded Text</p>"
  }
}

Failed Job¶

{
  "job_id": "job_123e4567-e89b-12d3-a456-426614174000",
  "status": "failed",
  "error": {
    "code": "HTML_DECODE_ERROR",
    "message": "Failed to Decode HTML.",
    "details": {
      "message": "Invalid HTML entity"
    }
  }
}

Notes for Developers¶

The API supports synchronous (body) and asynchronous (URL or file) modes.
For asynchronous jobs, always use the status_url to poll job completion.
The request_id is unique for every request and can be used for support or debugging.
Uploaded or generated files are stored temporarily and may expire based on your plan’s retention policy.
Ensure that remote URLs are publicly accessible and within your plan’s file size limits.
Allowed file extensions for this tool are strictly txt and html.