---
title: "Compare two versions of a table row by row and cell by cell"
method: POST
path: "/v1/tables/diff"
tags: ["tables"]
---

# Compare two versions of a table row by row and cell by cell

`POST /v1/tables/diff`

## Request

- Base URL: `https://api.relaex-engineers.de`
- URL: `https://api.relaex-engineers.de/v1/tables/diff`
- Auth: none declared

Compares two versions of a table row by row and cell by cell.

**Input:** multipart `old_file` and `new_file` (or `old_file_url` and `new_file_url`): CSV, TSV,
XLSX or a text-based PDF, each up to 20 MiB and 250,000 rows. Optional `options` as a JSON string
following `/v1/schemas/table-diff-options`: `key` (header(s) of the key column; detected when
absent), `column_map` (old → new header), `ignore_columns`, `numeric_tolerance`, `ignore_case`,
`header_row_old`/`header_row_new`, `sheet_old`/`sheet_new`, `pdf_old`/`pdf_new`, `max_changes`,
`output` (`json` or `csv`).

**Behaviour:** the header row is found in each file, columns are paired by header (also when
spelled differently, e.g. case or punctuation), renamed columns are paired by matching values or
a contained header with evidence. The key is the given column(s), else a unique column (ID-like
names first), else a unique column pair, else the row position (confidence low). Numbers are
compared by value with the number format inferred per column and file; text after Unicode and
whitespace normalisation. Duplicate keys are matched in order and reported.

**Output:** `ApiResponse` with `DiffResult`: both tables (header row, columns), key, column changes,
`rows[]` (changed rows with every cell change and numeric delta, added and removed rows with
their values, source rows), summary (matched, unchanged, changed, added, removed, cell changes
per column). With `output=csv` the changes as semicolon CSV in long format.

**Errors:** 400 invalid file, 413 too large, 422 no header row, no common column or invalid
options, 429 rate limit, 504 timeout.

**Languages:** responses are in English. Error, warning and rule codes are stable and
language-neutral; agents may translate messages for the user. Column headers and common cell words are recognised in English, German, French, Spanish, Italian, Portuguese, Dutch, Polish, Czech, Turkish, Swedish, Danish, Norwegian, Finnish, Korean, Japanese and Chinese; numbers in both 1.234,56 and 1,234.56 style; any ISO 4217 currency (no conversion).

**Access:** open, rate-limited per IP and per MCP session; an `X-API-Key` header raises the
limit. Uploaded files are processed in memory and never stored. Also available as MCP tool
`table_diff` at `/mcp` (Streamable HTTP).

## Response `200`

ApiResponse with DiffResult, or text/csv with output=csv

- unknown

## Other responses

- `400`: INVALID_FILE, EMPTY_FILE, UNSUPPORTED_FORMAT, INVALID_ENCODING
- `413`: FILE_TOO_LARGE, ROW_LIMIT_EXCEEDED
- `422`: HEADER_NOT_FOUND, NO_COMMON_COLUMNS, INVALID_OPTIONS
- `429`: RATE_LIMITED
- `504`: ANALYSIS_TIMEOUT

---

[API](https://skmtc.dev/relaex-engineers/apis/boring-api.md) · [All operations](https://skmtc.dev/relaex-engineers/apis/boring-api/llms.txt) · [OpenAPI document](https://skmtc.dev/relaex-engineers/apis/boring-api/revisions/269481105eb2?raw)