{ "openapi": "3.1.1", "info": { "title": "Paperwell Document Text & Data Scan API", "version": "1.0.0", "summary": "Full text of a PDF, DOCX or scan plus identifiers, personal data, dates and amounts in it.", "description": "Every endpoint performs the same calculation as the human page and returns inputs, result, units, assumptions, sources, warnings and computedAt. MCP endpoint: /mcp." }, "servers": [ { "url": "https://paperwelldocumentscan.usefulweb.app" } ], "paths": { "/api/v1/calculate": { "post": { "operationId": "calculate", "summary": "Full text of a PDF, DOCX or scan plus identifiers, personal data, dates and amounts in it.", "description": "Extracts the full plain text of a PDF (per page), DOCX, HTML, text file or photo/scan (OCR) and scans it for DOIs, ISBNs, ISSNs, ORCIDs, arXiv ids and PMIDs (with check-digit validation), personal data to redact (e-mail, IBAN, phone, payment card numbers), dates, amounts and periods. Paperwell uses it to make documents searchable, comparable and ready for redaction.\n\nMethodology:\n- Text comes from the pasted text or the uploaded file: PDFs through their text layer (pdftotext, one form feed per page; scanned PDFs need OCR first), DOCX from its document XML, HTML without tags, images through Tesseract OCR (English).\n- Identifiers are matched by pattern and validated by their check digits: ISBN-10 (mod 11), ISBN-13 (mod 10), ISSN (mod 11), ORCID (ISO 7064 MOD 11-2). DOIs, arXiv ids and PMIDs have no check digit and are reported as found.\n- Personal data candidates: e-mail addresses, IBANs (only with a valid mod-97 checksum), payment card numbers (only with a valid Luhn checksum) and phone numbers (7–15 digits starting with + or 0). They become exact search terms and presets for the secure-pdf-redactor tool.\n- Dates are recognised as 2026-03-12, 12.03.2026, 12 March 2026 / 12. März 2026 and March 12, 2026; slash dates like 03/04/2026 are reported without an ISO date because the order is ambiguous.\n\nPattern matching finds typical formats, not every personal detail: names, addresses and IDs in free text are not detected. Always review a document before sharing it.", "tags": [ "apps" ], "x-mcp-tool": "paperwell_document_scan", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaperwellDocumentScanInput" }, "examples": { "example1": { "summary": "Reading notes with DOIs, ISBNs and an ORCID", "value": { "text": "Little (1961), doi:10.1287/opre.9.3.383. Textbook ISBN 0-306-40615-2. Author ORCID 0000-0002-1825-0097. Slide typo: ISBN 978-3-16-148410-5.", "includeText": false } }, "example2": { "summary": "Letter with personal data to redact", "value": { "text": "Dear Ms Doe,\nyour refund of EUR 249.00 will be paid to IBAN DE89 3704 0044 0532 0130 00 within 14 days. Questions: billing@shop.example or +49 30 1234 5678.\nBerlin, 12.03.2026", "includeText": true } } } } } }, "responses": { "200": { "description": "Calculation result envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaperwellDocumentScanResult" } } } }, "400": { "description": "Malformed JSON body.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid input (see errors[]).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded (see Retry-After).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/tool": { "get": { "operationId": "getToolDefinition", "summary": "Inputs, output schema and examples for this tool", "responses": { "200": { "description": "Tool definition.", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "components": { "schemas": { "Problem": { "type": "object", "description": "RFC 9457 problem details. 422 responses include per-field `errors`.", "required": [ "type", "title", "status", "detail" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "PaperwellDocumentScanInput": { "type": "object", "additionalProperties": false, "properties": { "text": { "title": "Text", "description": "Paste text, or upload a file below (exactly one).", "type": "string", "maxLength": 400000 }, "file": { "title": "Or upload a file", "description": "PDF (text layer), DOCX, HTML, text or a photo/scan (PNG/JPG, read with OCR). Max 10 MiB. Read in memory and not stored. Upload as {filename, contentType?, contentBase64}. Max 10240 KiB. Accepts .txt,.md,.pdf,.docx,.png,.jpg,.jpeg,.html,.htm.", "type": "object", "additionalProperties": false, "required": [ "filename", "contentBase64" ], "properties": { "filename": { "type": "string" }, "contentType": { "type": "string" }, "contentBase64": { "type": "string" } } }, "includeText": { "title": "Include the full text in the result", "type": "boolean", "default": true } }, "required": [] }, "PaperwellDocumentScanResult": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "tool", "computedAt", "inputs", "summary", "result", "units", "assumptions", "sources", "warnings", "presentation", "links" ], "properties": { "schemaVersion": { "type": "string", "const": "1.0" }, "tool": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "version" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" } } }, "computedAt": { "type": "string", "format": "date-time" }, "inputs": { "type": "object", "description": "Normalised inputs actually used, including applied defaults." }, "summary": { "type": "string" }, "result": { "type": "object", "additionalProperties": false, "required": [ "source", "method", "stats", "pages", "identifiers", "pii", "dates", "amounts", "periods", "redactionTerms", "redactionPresets", "text", "truncated" ], "properties": { "source": { "type": "string", "enum": [ "text", "file" ] }, "method": { "type": "string", "description": "How the text was read: text, pdftotext, tesseract-ocr, docx, html." }, "stats": { "type": "object", "additionalProperties": false, "required": [ "characters", "words", "lines", "pages", "sentences", "readingMinutes" ], "properties": { "characters": { "type": "integer" }, "words": { "type": "integer" }, "lines": { "type": "integer" }, "pages": { "type": "integer" }, "sentences": { "type": "integer" }, "readingMinutes": { "type": "integer" } } }, "pages": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "page", "characters", "words" ], "properties": { "page": { "type": "integer" }, "characters": { "type": "integer" }, "words": { "type": "integer" } } } }, "identifiers": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "kind", "value", "normalized", "valid", "count" ], "properties": { "kind": { "type": "string" }, "value": { "type": "string" }, "normalized": { "type": "string" }, "valid": { "type": "boolean" }, "count": { "type": "integer" } } } }, "pii": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "kind", "value", "count", "valid" ], "properties": { "kind": { "type": "string" }, "value": { "type": "string" }, "count": { "type": "integer" }, "valid": { "type": [ "boolean", "null" ] } } } }, "dates": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "text", "iso", "count" ], "properties": { "text": { "type": "string" }, "iso": { "type": [ "string", "null" ] }, "count": { "type": "integer" } } } }, "amounts": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "text", "count" ], "properties": { "text": { "type": "string" }, "count": { "type": "integer" } } } }, "periods": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "text", "count" ], "properties": { "text": { "type": "string" }, "count": { "type": "integer" } } } }, "redactionTerms": { "type": "array", "items": { "type": "string" } }, "redactionPresets": { "type": "array", "items": { "type": "string" } }, "text": { "type": "string", "description": "The full plain text (form feeds separate PDF pages); empty when includeText is false." }, "truncated": { "type": "boolean" } } }, "units": { "type": "object", "additionalProperties": { "type": "string" } }, "assumptions": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "title" ], "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "publisher": { "type": "string" }, "retrievedAt": { "type": "string" }, "note": { "type": "string" } } } }, "warnings": { "type": "array", "items": { "type": "string" } }, "presentation": { "type": "array", "items": { "type": "object" }, "description": "Display blocks used by the human page (same data)." }, "links": { "type": "object", "additionalProperties": false, "required": [ "human", "api", "openapi", "methodology" ], "properties": { "human": { "type": "string", "format": "uri" }, "api": { "type": "string", "format": "uri" }, "openapi": { "type": "string", "format": "uri" }, "methodology": { "type": "string", "format": "uri" } } } } } } } }