URL Encode API Documentation¶

Overview¶

The URL Encode API converts plain text into a URL-safe encoded format using standard percent-encoding rules.
It supports direct text input (body mode), remote file URLs, and uploaded files for asynchronous processing.
The API returns an encoded text file (.txt) containing the encoded result.

Base URL:
https://api.apidatatools.com/url-encode-api

Endpoint (POST)¶

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

Headers¶

Header	Type	Required	Description
`Content-Type`	`application/json`	Yes	Must be `application/json` for body input
`x-url-safe`	`string`	Optional	Characters that should not be encoded
`x-source-type`	`string`	Optional	Defines input mode: `body`, `url`, or `file` (default: `body`)
`x-api-key`	`<API_KEY>`	Yes	Your API key for authentication `abcd1234xyz`

Accepted File Extensions¶

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

.txt

Input Example (Body Mode)¶

https://www.example.com/id=123&file=abc

Input Example (URL Mode)¶

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

Header:

x-source-type: url

Input Example (File Mode)¶

{
  "file": "user_uploads/upl_12345abcde/sample.txt"
}

Header:

x-source-type: file

Example Request¶

Synchronous (Body Input)¶

curl -X POST "https://api.apidatatools.com/url-encode-api" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d 'https://www.example.com/id=123&file=abc'

Asynchronous (Remote File URL)¶

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

Asynchronous (Input File)¶

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

Example Response¶

Successful (Body Mode)¶

{
  "request_id": "b8a9f0e2-1234-4f56-9a78-abcdef123456",
  "status": "success",
  "file": "https://downloads.apidatatools.com/apidatatools_convert_abc123.txt",
  "preview": "hello%20world%3F"
}

Async Job Accepted¶

{
  "status": "accepted",
  "job_id": "job_1234567890abcdef",
  "status_url": "https://api.apidatatools.com/jobs/job_1234567890abcdef",
  "request_id": "b8a9f0e2-1234-4f56-9a78-abcdef123456"
}

Error Handling¶

Error Code	HTTP Status	Message	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_ENCODE_ERROR`	400	Failed to URL-encode input.	`{"status":"error","error":"URL_ENCODE_ERROR","details":{"message":"Failed to URL-encode input."}}`
`EMPTY_BODY`	400	Request body is empty.	`{"status":"error","error":"EMPTY_BODY","details":{"message":"Request body is empty."}}`
`INVALID_BODY`	400	Body must be valid JSON.	`{"status":"error","error":"INVALID_BODY","details":{"message":"Body must be valid JSON."}}`
`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":"File exceeds plan limit."}}`
`INVALID_FILE_EXTENSION`	400	Invalid or unsupported file extension.	`{"status":"error","error":"INVALID_FILE_EXTENSION","details":{"message":"Invalid or unsupported file extension"}}`
`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 limit"}}`
`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 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_1234567890abcdef",
  "status": "queued",
  "created_at": 1712345678,
  "updated_at": 1712345678,
  "message": "Your job is being processed.",
  "retry_after": 2
}

Successful¶

{
  "job_id": "job_1234567890abcdef",
  "status": "success",
  "created_at": 1712345678,
  "updated_at": 1712345690,
  "result": {
    "request_id": "b8a9f0e2-1234-4f56-9a78-abcdef123456",
    "status": "success",
    "file": "https://downloads.apidatatools.com/apidatatools_convert_abc123.txt",
    "preview": "hello%20world%3F"
  }
}

Failed¶

{
  "job_id": "job_1234567890abcdef",
  "status": "failed",
  "created_at": 1712345678,
  "updated_at": 1712345685,
  "error": {
    "code": "URL_ENCODE_ERROR",
    "message": "Failed to URL-encode input.",
    "details": {
      "message": "Failed to URL-encode input."
    }
  }
}

Notes for Developers¶

The API supports three modes:
Body mode (synchronous): Direct text input.
URL mode (asynchronous): Remote file URL input.
File mode (asynchronous): Uploaded file reference input.
For asynchronous operations, a job_id and status_url are returned. Use the status endpoint to check progress or retrieve results.
The x-url-safe header allows specifying characters that should not be encoded.
The response always includes a unique request_id for traceability.
The output file is stored temporarily and accessible via the returned S3 download link.
Ensure that URLs provided in url mode are publicly accessible and within plan size limits.
For file mode, the file must be uploaded using the platform’s upload API before referencing it.