Text Diff API¶
Overview¶
Compares two UTF-8 text inputs line by line and produces newline-delimited JSON (.jsonl) changes.
Endpoint and authentication¶
POST https://api.apidatatools.com/text-diff-api with x-api-key: YOUR_API_KEY.
Input modes¶
Body mode accepts left and right strings synchronously. URL and file modes compare two sources asynchronously.
| Mode | Request body |
|---|---|
body | {"left":"old text","right":"new text"} |
url | {"left_url":"https://.../old.txt","right_url":"https://.../new.txt"} |
file | {"left_file":"OLD_KEY","right_file":"NEW_KEY"} |
Accepted URL/file extensions: .txt, .log, .md.
Options¶
| Header | Default | Description |
|---|---|---|
x-ignore-case | false | Compare case-insensitively. |
x-ignore-whitespace | false | Collapse whitespace before comparison. |
x-max-changes | 100000 | Change limit, clamped from 1 to 1,000,000. |
curl example¶
curl -X POST 'https://api.apidatatools.com/text-diff-api' \
-H 'x-api-key: YOUR_API_KEY' \
--data-raw '{"left":"one\ntwo","right":"one\nthree"}'
URL and file mode examples¶
curl --request POST --url https://api.apidatatools.com/text-diff-api \
--header 'x-api-key: YOUR_API_KEY' --header 'x-source-type: url' \
--header 'Content-Type: application/json' \
--data '{"left_url":"https://example.com/old.txt","right_url":"https://example.com/new.txt"}'
curl --request POST --url https://api.apidatatools.com/text-diff-api \
--header 'x-api-key: YOUR_API_KEY' --header 'x-source-type: file' \
--header 'Content-Type: application/json' \
--data '{"left_file":"LEFT_UPLOAD_KEY","right_file":"RIGHT_UPLOAD_KEY"}'
Both async sources are validated independently for extension and size.
Result format¶
The JSONL output contains metadata, change records, and a summary with equal, changes, comparedLines, and truncated. Change records contain operation, leftLine, rightLine, oldValue, and newValue. Output is truncated at x-max-changes or the service output limit. A line larger than 8 MB is rejected.
Success and async process¶
Body mode returns HTTP 200 with a temporary .jsonl file and summary preview. Async submission returns HTTP 202:
{"status":"accepted","job_id":"JOB_ID","status_url":"https://api.apidatatools.com/jobs/JOB_ID","request_id":"REQUEST_ID"}
Poll GET /jobs/JOB_ID with the same API key. Queued/processing states include message and retry_after; success includes result.file and result.preview; failure includes error.code, message, and details.
Error handling¶
| HTTP status | Error codes |
|---|---|
400 | INVALID_SOURCE_TYPE, INVALID_BODY_ENCODING, EMPTY_BODY, INVALID_DIFF_BODY, EMPTY_DIFF_INPUT, INVALID_UTF8, DIFF_LINE_TOO_LARGE |
401 | UNAUTHORIZED |
404 | USER_NOT_FOUND, UNKNOWN_FUNCTION |
413 | PAYLOAD_TOO_LARGE |
429 | QUOTA_EXCEEDED, RATE_LIMITED |
500 | PLAN_NOT_FOUND, AUTH_ERROR, INTERNAL_ERROR |
Async submission can return INVALID_BODY, INVALID_DIFF_INPUTS, FILE_TOO_LARGE, CONFIG_ERROR, or PLAN_CONFIG_ERROR. Worker failures include INVALID_JOB, DOWNLOAD_FAILED, and UPLOAD_FAILED. Status errors include INVALID_JOB_ID, JOB_NOT_FOUND, FORBIDDEN, and DDB_ERROR.
Notes¶
Honor retry_after. Each left/right file has its own plan size limit. Output URLs are temporary.