JSON Diff API¶
Overview¶
Compares two JSON inputs as parser event streams and returns structural changes as JSONL.
Endpoint and authentication¶
POST https://api.apidatatools.com/json-diff-api with x-api-key: YOUR_API_KEY.
Input modes¶
Body mode accepts non-empty JSON strings inside {"left":"...","right":"..."}. URL mode uses left_url and right_url; file mode uses left_file and right_file. Accepted extensions are .json, .txt, and .log.
Options¶
x-max-changes defaults to 100,000 and is clamped between 1 and 1,000,000.
curl example¶
curl -X POST 'https://api.apidatatools.com/json-diff-api' \\
-H 'x-api-key: YOUR_API_KEY' \\
--data-raw '{"left":"{\\"active\\":false}","right":"{\\"active\\":true}"}'
Result¶
JSONL output contains metadata, changes with parser path/event/value fields, and a summary with equal, changes, comparedTokens, and truncated.
URL and file examples¶
curl --request POST --url https://api.apidatatools.com/json-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.json","right_url":"https://example.com/new.json"}'
curl --request POST --url https://api.apidatatools.com/json-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"}'
Success and async process¶
Body mode returns HTTP 200 with a .jsonl file and summary preview. Async submission returns HTTP 202 with job_id, status_url, and request_id. Poll with the same API key. Queued/processing responses include retry_after; success includes result.file and result.preview; failure includes error.code, message, and details.
The JSONL result starts with metadata, contains structural change records (path, old/new event and value), and ends with a summary containing equal, changes, comparedTokens, and truncated.
Errors¶
| HTTP status | Error codes |
|---|---|
400 | INVALID_SOURCE_TYPE, INVALID_BODY_ENCODING, EMPTY_BODY, INVALID_DIFF_BODY, INVALID_JSON, EMPTY_DIFF_INPUT |
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 source validation can return INVALID_DIFF_INPUTS or FILE_TOO_LARGE. Worker errors include DOWNLOAD_FAILED and UPLOAD_FAILED; status errors include INVALID_JOB_ID, JOB_NOT_FOUND, FORBIDDEN, and DDB_ERROR.
Notes¶
Both JSON sources must be valid. Honor retry_after; source and output retention limits are plan-dependent.