Getting Started

The Diffchecker API provides HTTP endpoints for comparing text, PDF and Word documents, images, and Excel spreadsheets. Document endpoints include PDF plain-text and rich-text comparisons plus DOCX redlines with Microsoft Word tracked changes.

Canonical PDF comparison routes use /document/plaintext and /document/richtext. The legacy /pdf, /pdf/plaintext, and /pdf/richtext routes remain supported for compatibility.

There are two ways of interacting with the Diffchecker API:

When both are provided, email gets ignored in favor of the API key. The examples in these docs assume you are authenticating via email.

No sandbox is needed: the free tier is the test environment, and GET /auth-test costs no credits, so you can confirm your credentials work before spending any quota.

API requests are rate-limited based on your authentication method. Free tier (email) users have lower limits than paid subscribers using an API key. If you exceed the rate limit, the API will return a 429 Too Many Requests response.

Every public API response includes an X-Credits-Used response header. For backwards compatibility, JSON responses also continue to include the same value in the creditsUsed response body field.

Some 429 responses are returned for exhausted free or paid diff quotas. Zero-credit failed requests are also throttled separately and may include a retryAfterSeconds field in the JSON body.

The API is currently at version 1. Select a version with the optional Diffchecker-Version request header. When the header is omitted the request is served by the newest version, currently 1. Every response echoes the version that served it in a Diffchecker-Version response header. A version the API does not support is rejected with 400 UNSUPPORTED_API_VERSION rather than silently served by another version; details.supportedVersions lists the accepted values.

Within a version we only make backwards-compatible changes: new endpoints, new optional parameters, new response fields, new response headers and new error codes. Clients should ignore fields and headers they do not recognize. A breaking change — removing or renaming an endpoint, parameter or response field, changing a type or default, or tightening validation — is released as a new version (Diffchecker-Version: 2), which immediately becomes the version served to requests that omit the header. Pin Diffchecker-Version to the version you integrated against if you want to choose when you take a breaking change; an unpinned integration takes it as soon as the new version ships. The previous version is deprecated at that point, keeps answering pinned requests until its Sunset date, and is removed after it. info.version in this document tracks revisions of the specification itself.

When an endpoint or version is deprecated, its responses signal it:

Deprecated operations are also marked deprecated: true in this document. Nothing is deprecated today.

Every failure is answered with JSON — never an HTML error page — using the same envelope as a successful response:

{
  "creditsUsed": 0,
  "error": {
    "status": 400,
    "code": "VALIDATION_ERROR",
    "message": "One or more validation errors occurred.",
    "hint": "Each entry in `details` names the offending parameter and its location. Correct those parameters and retry.",
    "documentation": "https://www.diffchecker.com/docs/getting-started"
  }
}

This holds for every status the API can return, including unknown paths (404 NOT_FOUND), unsupported methods (405 METHOD_NOT_ALLOWED, with an Allow response header), unsupported request bodies (415 UNSUPPORTED_MEDIA_TYPE) and unexpected server failures (500 INTERNAL_SERVER_ERROR). Every operation documents those four responses.

A request body whose Content-Type the endpoint does not accept is rejected with 415 UNSUPPORTED_MEDIA_TYPE before any endpoint logic runs. /text accepts only application/json; the upload endpoints accept application/json and multipart/form-data. A body of an accepted type that does not match the input_type query parameter (for example a JSON body with input_type=form) is not a 415: the endpoint finds no inputs and answers 400 INVALID_INPUT.

Malformed multipart bodies on /document/plaintext, /document/richtext, /image and /excel (and the legacy /pdf routes) return 400 INVALID_MULTIPART. Send a complete body with a boundary matching the Content-Type header; let your HTTP client generate the header and boundary together. Recognized upload errors retain their specific codes, such as LIMIT_UNEXPECTED_FILE, INVALID_FILE_EXTENSION and LIMIT_FILE_SIZE. /document/redline uses its own DOCX parser and reports the same condition as 400 INVALID_DOCX_UPLOAD.

You may find the following resources helpful when dealing with PDF, Image, or Excel diffs: