API Documentation

Getting Started

Compare text, documents, images, and spreadsheets programmatically with the Diffchecker API.

Base URLhttps://api.staging.diffchecker.com/public
OpenAPI JSONOpenAPI YAML

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.

1

Authentication

There are two ways of interacting with the Diffchecker API:

  • Email: Just pass your email as a query string parameter. This method does not require you to have a Diffchecker account and will allow you to make as many diffs as free tier limits allow.
  • API Key: Every paid subscriber gets their own API key, which needs to be passed as the request's X-Api-Key header. This will allow you to make as many diffs as your paid plan allows.

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

    2

    Rate Limiting

    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.

    3

    Errors

    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"
  }
}
  • status repeats the HTTP status code, so a logged or forwarded error object stays self-describing.
  • code is stable and machine-readable — branch on it rather than on message.
  • message describes what went wrong.
  • hint gives a concrete next step that resolves the error.
  • documentation links to this reference.
  • details is present on some errors with structured, error-specific context.

    • 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`.

    4

    Resources

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

  • Data URLs (MDN)
  • FormData (MDN)