Docs/API Reference

API Reference

The DiffChecker Pro REST API allows you to programmatically compare files, generate diffs, and create shareable links from your own applications.

Base URLhttps://diffchecker.pro/api/v1

Authentication

All API requests require authentication using an API key. Generate your key from Account Settings → API Keys. Include it in the Authorization header of every request.

bash
Authorization: Bearer YOUR_API_KEY

Keep your API key secret. Never expose it in client-side code, public repositories, or browser DevTools. Use environment variables or a secrets manager.

Rate Limits

Rate limits are enforced per API key on a rolling hourly window. Exceeding the limit returns HTTP 429 with a Retry-After header.

PlanRequests / HourMax File SizeAI Review
FreeNo API access5 MB5 / day
Pro1,00050 MBUnlimited
Team10,00050 MBUnlimited
EnterpriseCustomCustomUnlimited

Rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (Unix timestamp)

Endpoints

POST/diff/textCompare two text documents and return a structured diff.POST/diff/jsonSemantic JSON comparison with structural diff output.POST/diff/xmlNamespace-aware XML diff with attribute comparison.POST/diff/imagePixel-level image comparison returning a diff percentage and highlight image.POST/shareCreate a shareable link for an existing comparison result.GET/share/{token}Retrieve a previously shared comparison by its token.
POST/diff/text

Compare two text documents and return a structured diff with hunks, line numbers, and change statistics.

Request Body

json
{
  "original": "Hello world\nLine two",
  "modified": "Hello there\nLine two\nLine three",
  "options": {
    "algorithm": "myers",    // "myers" | "patience" | "histogram"
    "context": 3,            // lines of context around changes
    "ignoreWhitespace": false,
    "ignoreCase": false
  }
}

Response

json
{
  "hunks": [
    {
      "oldStart": 1,
      "oldLines": 2,
      "newStart": 1,
      "newLines": 3,
      "changes": [
        { "type": "del", "content": "Hello world", "lineNumber": 1 },
        { "type": "add", "content": "Hello there", "lineNumber": 1 },
        { "type": "normal", "content": "Line two", "lineNumber": 2 },
        { "type": "add", "content": "Line three", "lineNumber": 3 }
      ]
    }
  ],
  "stats": {
    "additions": 2,
    "deletions": 1,
    "changes": 1
  }
}
POST/diff/json

Semantic JSON comparison. Parses both documents and compares their structure, ignoring key order and whitespace by default.

json
// Request
{
  "original": "{"name": "Alice", "age": 30}",
  "modified": "{"name": "Alice", "age": 31, "city": "NYC"}",
  "options": {
    "semantic": true,        // structural comparison (default true)
    "ignoreKeyOrder": true,  // ignore object key ordering
    "arrayOrderMatters": true
  }
}

// Response
{
  "changes": [
    { "path": "age", "type": "changed", "oldValue": 30, "newValue": 31 },
    { "path": "city", "type": "added", "newValue": "NYC" }
  ],
  "stats": { "additions": 1, "deletions": 0, "changes": 1 }
}
POST/diff/xml

Namespace-aware XML diff that compares XML documents structurally, resolving namespace URIs rather than prefixes.

json
// Request
{
  "original": "<user id=\"1\"><name>Alice</name></user>",
  "modified": "<user id=\"1\"><name>Bob</name></user>",
  "options": {
    "namespaceAware": true,    // resolve namespace URIs
    "ignoreAttributeOrder": true,
    "ignoreComments": true
  }
}

// Response
{
  "changes": [
    { "path": "/user/name/text()", "type": "changed", "oldValue": "Alice", "newValue": "Bob" }
  ],
  "stats": { "additions": 0, "deletions": 0, "changes": 1 }
}
POST/diff/image

Pixel-level image comparison. Returns a difference percentage and optionally a base64-encoded highlight image showing changed regions.

json
// Request (multipart/form-data)
{
  "original": "<base64-encoded image>",
  "modified": "<base64-encoded image>",
  "options": {
    "threshold": 0.1,          // pixel sensitivity (0-1)
    "outputHighlight": true,   // include highlight image in response
    "highlightColor": "#ff0000"
  }
}

// Response
{
  "diffPercent": 2.34,
  "changedPixels": 12450,
  "totalPixels": 531441,
  "highlightImage": "data:image/png;base64,..."   // if outputHighlight=true
}
POST/share

Create a shareable link for a comparison. Returns a token and URL that can be shared with anyone.

json
// Request
{
  "original": "content A",
  "modified": "content B",
  "format": "text",           // "text" | "json" | "xml" | "yaml" | "csv"
  "options": {
    "expiresIn": "30d",       // "7d" | "30d" | "90d" | "never" (Pro+)
    "title": "API v2 changes"
  }
}

// Response
{
  "token": "sh_abc123def456",
  "url": "https://diffchecker.pro/share/sh_abc123def456",
  "expiresAt": "2026-03-20T10:30:00Z"
}
GET/share/{token}

Retrieve a previously shared comparison by its token. Returns the original content, modified content, and the diff.

json
// Response
{
  "token": "sh_abc123def456",
  "title": "API v2 changes",
  "format": "json",
  "original": "content A",
  "modified": "content B",
  "diff": { /* same structure as /diff/json response */ },
  "createdAt": "2026-02-20T10:30:00Z",
  "expiresAt": "2026-03-20T10:30:00Z",
  "viewCount": 5
}

Error Codes

HTTP StatusError CodeDescription
400invalid_requestRequest body is malformed or missing required fields.
401unauthorizedMissing or invalid API key.
403forbiddenAPI key does not have permission for this endpoint.
404not_foundShared link token not found or expired.
413payload_too_largeFile size exceeds the limit for your plan.
422unprocessableContent could not be parsed as the specified format.
429rate_limitedRate limit exceeded. Check Retry-After header.
500internal_errorUnexpected server error. Retry with exponential backoff.

Code Examples

cURL

bash
curl -X POST https://diffchecker.pro/api/v1/diff/text \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "original": "Hello world",
    "modified": "Hello there",
    "options": { "context": 3 }
  }'

JavaScript / TypeScript

typescript
const API_KEY = process.env.DIFFCHECKER_API_KEY

async function diffText(original: string, modified: string) {
  const res = await fetch('https://diffchecker.pro/api/v1/diff/text', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ original, modified, options: { context: 3 } }),
  })

  if (!res.ok) {
    const err = await res.json()
    throw new Error(`API error ${res.status}: ${err.code}`)
  }

  const { hunks, stats } = await res.json()
  console.log(`${stats.additions} additions, ${stats.deletions} deletions`)
  return hunks
}

// Usage
const changes = await diffText('before content', 'after content')

Python

python
import os
import requests

API_KEY = os.environ['DIFFCHECKER_API_KEY']
BASE_URL = 'https://diffchecker.pro/api/v1'

def diff_json(original: dict, modified: dict) -> dict:
    response = requests.post(
        f'{BASE_URL}/diff/json',
        headers={
            'Authorization': f'Bearer {API_KEY}',
            'Content-Type': 'application/json',
        },
        json={
            'original': original,
            'modified': modified,
            'options': {'semantic': True, 'ignoreKeyOrder': True}
        }
    )
    response.raise_for_status()
    return response.json()

# Usage
result = diff_json(
    original={'name': 'Alice', 'age': 30},
    modified={'name': 'Alice', 'age': 31}
)
for change in result['changes']:
    print(f"{change['path']}: {change['oldValue']} → {change['newValue']}")

Ready to start building?

Get your API key and make your first request in under 2 minutes.

Get API KeyView Pricing