Endpoint
POST https://difflists.site/api/compare
Request body
| Field | Type | Required | Description |
|---|---|---|---|
| listA | string | Yes | The first list, one item per line (or delimited — see options) |
| listB | string | Yes | The second list, same format |
| options | object | No | Any subset of the comparison options below |
Options
| Key | Type | Default | Meaning |
|---|---|---|---|
| caseSensitive | boolean | false | Treat "Apple" and "apple" as different values |
| trimWhitespace | boolean | true | Trim leading/trailing whitespace from each item |
| ignoreBlankLines | boolean | true | Skip empty lines instead of counting them as items |
| naturalSort | boolean | false | Sort results numerically (item-2 before item-10) instead of as plain text |
| ignoreLeadingZeros | boolean | false | Treat "007" and "7" as the same value |
| caseTransform | "unchanged" | "upper" | "lower" | "unchanged" | Transform result values’ case |
| delimiter | "newline" | "comma" | "semicolon" | "tab" | "pipe" | "auto" | "newline" | How each list is split into items |
Example request
curl -X POST https://difflists.site/api/compare \ -H "Content-Type: application/json" \ -d '{"listA":"apple\nbanana\ncherry","listB":"banana\ncherry\ndate"}'
Example response
{ "onlyA": ["apple"], "onlyB": ["date"], "intersection": ["banana", "cherry"], "union": ["apple", "banana", "cherry", "date"], "symmetricDifference": ["apple", "date"], "statsA": { "raw": 3, "unique": 3, "duplicates": 0, "blanks": 0 }, "statsB": { "raw": 3, "unique": 3, "duplicates": 0, "blanks": 0 }, "matchRate": 50 }
Response fields
- onlyA / onlyB — items unique to each list.
- intersection — items present in both lists.
- union — every distinct item across both lists.
- symmetricDifference — everything that doesn’t match on either side.
- statsA / statsB — raw item count, unique count, duplicates removed, and blank lines skipped for each input list.
- matchRate — intersection size as a percentage of the union size.
Errors
| Status | Meaning |
|---|---|
| 400 | Malformed JSON, or listA/listB missing or not strings |
| 413 | A list exceeds 2,000,000 characters |
| 429 | Rate limit exceeded — check the Retry-After header (seconds) |
JavaScript example
const res = await fetch('https://difflists.site/api/compare', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ listA: 'a\nb\nc', listB: 'b\nc\nd' }) }); const result = await res.json();
Prefer a visual embed instead?
If you want a working tool on your page rather than raw JSON to build your own UI around, see the embeddable widget instead — one <iframe>, no code.
Do I need an API key?
No. The endpoint is public and unauthenticated, rate-limited per IP address instead.
What's the rate limit?
30 requests per minute per IP address. Exceeding it returns a 429 status with a Retry-After header.
Is there a size limit on the lists I send?
Each list (listA and listB) must be under 2,000,000 characters. That's comfortably enough for hundreds of thousands of typical list items.
Can I call this from client-side JavaScript on my own site?
Yes, the endpoint sends permissive CORS headers (Access-Control-Allow-Origin: *) specifically so it can be called directly from browser JavaScript on other domains.
Is this API guaranteed to stay free and available?
It's offered as-is, matching the free, no-account model of the rest of DiffLists. Like any free third-party API, don't build a business-critical system with no fallback on it — see the terms of use.