Skip to content

YAML Diff API

Overview

Compares two YAML inputs as parser event streams and returns structural changes as JSONL.

Endpoint and authentication

POST https://api.apidatatools.com/yaml-diff-api with x-api-key: YOUR_API_KEY.

Input modes

Body mode accepts {"left":"YAML text","right":"YAML text"}. URL mode uses left_url and right_url; file mode uses left_file and right_file. Accepted extensions are .yaml, .yml, .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/yaml-diff-api' \\
  -H 'x-api-key: YOUR_API_KEY' \\
  --data-raw '{"left":"active: false","right":"active: true"}'

URL and file examples

curl --request POST --url https://api.apidatatools.com/yaml-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.yaml","right_url":"https://example.com/new.yaml"}'
curl --request POST --url https://api.apidatatools.com/yaml-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"}'

Result and async process

The JSONL result contains metadata, structural event changes, and a summary with equal, changes, comparedTokens, and truncated. Body mode returns HTTP 200. Async submission returns HTTP 202 with job_id and status_url. Poll with the same API key; queued/processing includes retry_after, success includes result, and failure includes error.

Error handling

HTTP status Error codes
400 INVALID_SOURCE_TYPE, INVALID_BODY_ENCODING, EMPTY_BODY, INVALID_DIFF_BODY, INVALID_YAML, 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 errors include INVALID_DIFF_INPUTS, FILE_TOO_LARGE, CONFIG_ERROR, PLAN_CONFIG_ERROR, DOWNLOAD_FAILED, and UPLOAD_FAILED. Status errors include INVALID_JOB_ID, JOB_NOT_FOUND, FORBIDDEN, and DDB_ERROR.

Notes

Both sources are independently validated. Honor retry_after; plan size and output retention limits apply.