URL Decode API Documentation¶

Overview¶

The URL Decode API decodes URL-encoded strings into their original readable form.
It supports synchronous processing via direct body input and asynchronous processing via remote file URL or uploaded file.
The API returns decoded text as a downloadable file and a preview of the decoded content.

Endpoint (POST)¶

POST https://api.apidatatools.com/url-decode-api

Headers¶

Header	Description	Required	Example
`Content-Type`	Defines the request content type.	Yes	`application/json`
`x-source-type`	Defines input mode: `body`, `url`, or `file`.	Optional	`body`
`x-api-key`	API key for authentication.	Yes	`<api_key>`

Accepted File Extensions¶

Mode	Allowed Extensions
URL / File Mode	`txt`

Input Example (Body Mode)¶

hello%20world%3F

Input Example (URL Mode)¶

{
  "url": "https://example.com/data/urlencoded.txt"
}

Input Example (File Mode)¶

{
  "file": "user_uploads/urlencoded.txt"
}

Example Request¶

Synchronous (Body Input)¶

curl -X POST "https://api.apidatatools.com/url-decode-api" \
  -H "Content-Type: application/json" \
  -H "x-source-type: body" \
  -H "x-api-key: YOUR_API_KEY" \
  -d 'hello%20world%3F'

Asynchronous (Remote File URL)¶

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

Asynchronous (Input File)¶

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

Example Response¶

Successful (Body Mode)¶

{
  "request_id": "b7f1e0a2-9d3c-4e3a-8a7b-1e9f9c6a2d8e",
  "status": "success",
  "file": "https://downloads.apidatatools.com/apidatatools_convert_abc123.txt",
  "preview": "hello world?"
}

Async Job Accepted¶

{
  "status": "accepted",
  "job_id": "job-12345-abcde",
  "status_url": "https://api.apidatatools.com/jobs/job-12345-abcde",
  "request_id": "b7f1e0a2-9d3c-4e3a-8a7b-1e9f9c6a2d8e"
}

Error Handling¶

Error Code	HTTP Status	Description	Example
`INVALID_TEXT`	400	Input must be a non-empty string.	`{"status":"error","error":"INVALID_TEXT","details":{"message":"Input must be a non-empty string."}}`
`URL_DECODE_ERROR`	400	Failed to decode the input string.	`{"status":"error","error":"URL_DECODE_ERROR","details":{"message":"Failed to URL-decode input."}}`
`INVALID_BODY_ENCODING`	400	Body could not be base64-decoded.	`{"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."}}`
`PAYLOAD_TOO_LARGE`	413	Body exceeds plan limit.	`{"status":"error","error":"PAYLOAD_TOO_LARGE","details":{"message":"Request body exceeds limit."}}`
`INVALID_URL`	400	Invalid or missing URL in URL mode.	`{"status":"error","error":"INVALID_URL","details":{"message":"URL must be valid http/https."}}`
`URL_UNREACHABLE`	400	Could not reach remote URL.	`{"status":"error","error":"URL_UNREACHABLE","details":{"message":"Could not reach URL."}}`
`URL_NOT_OK`	400	Remote 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":"File exceeds plan limit."}}`
`INVALID_FILE_EXTENSION`	400	Unsupported file extension.	`{"status":"error","error":"INVALID_FILE_EXTENSION","details":{"message":"Invalid or unsupported file extension."}}`
`INVALID_SOURCE_TYPE`	400	Must be `url` or `file` when using async mode.	`{"status":"error","error":"INVALID_SOURCE_TYPE","details":{"message":"Must be 'url' or 'file'."}}`
`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 provided in the accepted response.

Endpoint¶

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

Example Status Response for Async¶

Queued¶

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

Success¶

{
  "job_id": "job-12345-abcde",
  "status": "success",
  "created_at": 1712345678,
  "updated_at": 1712345690,
  "result": {
    "request_id": "b7f1e0a2-9d3c-4e3a-8a7b-1e9f9c6a2d8e",
    "status": "success",
    "file": "https://downloads.apidatatools.com/apidatatools_convert_abc123.txt",
    "preview": "hello world?"
  }
}

Failed¶

{
  "job_id": "job-12345-abcde",
  "status": "failed",
  "error": {
    "code": "URL_DECODE_ERROR",
    "message": "Failed to URL-decode input.",
    "details": {"error": "Invalid encoding sequence"}
  }
}

Notes for Developers¶

The API supports three modes: body, url, and file.
For url or file mode, the operation is asynchronous and returns a job_id with a status_url.
The decoded output is stored temporarily and accessible via the returned file URL.
Each response includes a unique request_id for traceability.
Ensure proper authentication headers are included in all requests.
The preview field in successful responses is limited to the first 100 KB of decoded text.
Use the Status API to poll job progress until completion for asynchronous operations.