FileDiffs API
Welcome to the FileDiffs REST API. Integrate our secure file comparison engine into your backend using Node.js, Python, PHP, Ruby, Java, .NET, Go, or any language that supports HTTP requests to compare PDFs, Word documents, Excel spreadsheets, PowerPoint presentations, text files, and source code quickly with simple REST endpoints, consistent JSON responses, and reliable performance.
1. Developer API Pricing & Plans
Choose the plan that best fits your integration needs. Every plan includes secure file processing, automatic deletion of temporary files after comparison, isolated processing environments, and TLS-encrypted data transfer to help keep your documents protected.
Premium API
Enterprise API
2. Headless Endpoints Reference
Our developer REST API includes four primary endpoints that help you programmatically manage document parsing, versioning, callbacks, and file comparison workflows with a simple, reliable integration experience.
/api/v1/compareUpload two PDFs, Word, Excel, PowerPoint, or text files using multipart form-data. The API detects document structure, compares changes, and supports optional granularity (auto, word, or character).
/api/v1/compare/batchSubmit up to 500 pairs of raw text comparisons in one request. Optimized for high-volume text, code, and database content. Use multiple /compare requests for formatted documents like PDFs.
/api/v1/webhooksRegister HTTP callback URLs to automatically receive comparison results, alignment data, and difference payloads when asynchronous batch comparison jobs are complete.
/api/v1/versionsTrack document version history and compare any two saved version IDs to identify changes, monitor revisions, and manage document history programmatically.
3. Supported Formats & MIME Types
The FileDiffs parser automatically detects uploaded file formats and extracts their content, so you can start comparing files without specifying additional type parameters.
| Format | Extensions | Standard MIME Types |
|---|---|---|
| PDF Documents | .pdf | application/pdf |
| Word Documents | .docx | application/vnd.openxmlformats-officedocument.wordprocessingml.document |
| Excel Sheets | .xlsx, .csv | application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, text/csv |
| PowerPoint Presentations | .pptx, .ppt | application/vnd.openxmlformats-officedocument.presentationml.presentation |
| Plain Text | .txt, .json, .js, .html, .xml, .css, .md, .yaml | text/plain, application/json, text/html, text/xml |
4. REST API Output Modes (JSON vs HTML)
Choose your preferred response format by setting the output parameter when starting a comparison.
Option A: Raw JSON (output=json)
Receive a structured JSON response with similarity scores, change summaries, and diff data. Ideal for building custom comparison interfaces or integrating results into your own application.
Option B: Side-by-Side HTML (output=html)
Receive fully rendered side-by-side HTML with highlighted insertions and deletions, ready to embed directly into your frontend for a synchronized comparison view.
5. Rate Limit & Billing Usage Response Headers
Every comparison response includes custom HTTP headers that let you programmatically monitor rate limits, remaining requests, and API usage.
| Header Key | Value Type | Description |
|---|---|---|
X-RateLimit-Limit | Integer | The maximum number of API requests allowed per minute for your current plan. |
X-RateLimit-Remaining | Integer | The number of requests remaining in the current one-minute rate limit window. |
X-Usage-Tier | String | The active API plan associated with your key, such as free, premium, or enterprise. |
6. Universal Compare Code Snippets (POST /api/v1/compare)
Send document payloads from your backend to compare files and retrieve detailed comparison results.
const fs = require('fs');
const FormData = require('form-data');
const axios = require('axios');
async function compareFiles() {
const form = new FormData();
form.append('left', fs.createReadStream('./contract_v1.pdf'));
form.append('right', fs.createReadStream('./contract_v2.pdf'));
form.append('output', 'json');
try {
const response = await axios.post('https://filediffs.com/api/v1/compare', form, {
headers: {
...form.getHeaders(),
'Authorization': 'Bearer YOUR_API_KEY'
}
});
console.log('Differences:', response.data.differences);
console.log('Similarity:', response.data.similarity);
console.log('Viewer URL:', response.data.viewerUrl);
} catch (error) {
console.error('Comparison error:', error.message);
}
}
compareFiles();7. Live Key Validation Sandbox
Validate your API key and test authentication requests instantly using our live sandbox console.
⚡ Sandbox Validation Testing
Test your API key by entering it below to verify authentication and access.
8. REST Key Verification & Error Reference
Validate your API key programmatically before sending comparison requests using our API validation endpoint.
/api/v1/validateQuery Parameters
apiKey(Required): Your FileDiffs API key (for example,key_pro_123).
Comprehensive API Error & Status Code Reference
| HTTP Status | Error Response Body | Cause |
|---|---|---|
400 Bad Request | { "valid": false, "error": "Bad Request" } | Missing or invalid request parameters. |
401 Unauthorized | { "valid": false, "error": "Unauthorized" } | Invalid, suspended, or unauthorized API key. |
403 Forbidden | { "valid": false, "error": "Forbidden" } | Expired key or access not permitted. |
429 Too Many Requests | { "valid": false, "error": "Rate limit exceeded." } | API rate limit exceeded. Try again later. |
500 Internal Server Error | { "valid": false, "error": "Internal Server Error" } | Unexpected server error. Please retry. |
9. Developer FAQ
The FileDiffs API supports PDF, Word (DOCX), Excel (XLSX and CSV), plain text, JSON, HTML, XML, Markdown, source code, and many other text-based file formats. File types are detected automatically, so you don't need to specify them manually.
Upload two files to the /api/v1/compare endpoint using multipart form-data and include your API key in the Authorization header. The API compares the files and returns either a JSON response or rendered HTML, depending on the selected output mode.
Yes. The /api/v1/compare/batch endpoint lets you compare up to 500 pairs of text or code in a single request. For PDFs and other formatted documents, you can send multiple /api/v1/compare requests in parallel for better performance.
Yes. Every request is protected with TLS encryption, processed in isolated environments, and temporary files are automatically deleted after comparison to help keep your documents secure.
Yes. The FileDiffs REST API works with any language or framework that supports HTTP requests, including Node.js, Python, PHP, Java, Ruby, Go, .NET, and TypeScript. You can also use the OpenAPI specification to generate SDKs automatically.