{ "openapi": "3.1.1", "info": { "title": "File Format Doctor API", "version": "1.0.0", "summary": "Find out what a file really is from its bytes, why it will not open and how to convert 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://fileformatdoctor.usefulweb.site" } ], "paths": { "/api/v1/calculate": { "post": { "operationId": "calculate", "summary": "Find out what a file really is from its bytes, why it will not open and how to convert it.", "description": "Upload a file (or paste its first bytes as hex) and the doctor reads its magic number against a table of 74 formats, looks inside ZIP containers (DOCX, XLSX, ODT, EPUB, JAR, APK), and diagnoses wrong extensions, truncated or encrypted files, text encoding problems and disguised executables — with offline conversion commands.\n\nMethodology:\n- Magic numbers are matched at their documented offsets for 74 formats (e.g. \"%PDF-\" at 0, \"ustar\" at 257, \"CD001\" at 0x8001, \"ftyp\" brands at 4).\n- ISO-BMFF files are told apart by their ftyp brands (heic/heix → HEIC, mif1 → HEIF, avif → AVIF, qt → QuickTime, M4A → audio, isom/mp42 → MP4).\n- ZIP files are opened by reading the central directory (or local file headers in a sample): [Content_Types].xml + word/ → DOCX, xl/ → XLSX, ppt/ → PPTX, the stored \"mimetype\" entry → ODT/ODS/ODP/EPUB, AndroidManifest.xml → APK, META-INF/MANIFEST.MF → JAR. General-purpose bit 0 marks encrypted entries.\n- Without a binary signature the bytes are checked for BOMs, UTF-16 patterns, strict UTF-8 validity and typical mojibake sequences (e.g. \"é\", \"’\"), then for SVG/HTML/XML/JSON/CSV structure.\n- Truncation checks (uploads only): PDF must end with %%EOF, PNG with IEND, JPEG with FF D9, GIF with 3B, ZIP must have an end-of-central-directory record, RIFF/BMP declared sizes must fit.\n- Conversion suggestions use free, offline tools (LibreOffice, ImageMagick, FFmpeg, 7-Zip, iconv) with the exact command for your file name.\n\nDetection reads bytes only; it does not scan for malware. Never run an executable you did not expect to receive.", "tags": [ "internet" ], "x-mcp-tool": "file_format_doctor", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileFormatDoctorInput" }, "examples": { "example1": { "summary": "iPhone photo renamed to .jpg (HEIC inside)", "value": { "filename": "IMG_0420.jpg", "hexBytes": "00 00 00 18 66 74 79 70 68 65 69 63 00 00 00 00 6d 69 66 31 68 65 69 63" } }, "example2": { "summary": "Invoice that is really a Windows program", "value": { "filename": "invoice_2026.pdf.exe", "hexBytes": "4D 5A 90 00 03 00 00 00 04 00 00 00 FF FF 00 00 B8 00 00 00 00 00 00 00 40 00 00 00 00 00 00 00" } }, "example3": { "summary": "Word document (ZIP local header with word/ entry)", "value": { "filename": "contract.zip", "hexBytes": "50 4B 03 04 14 00 00 00 08 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 11 00 00 00 77 6F 72 64 2F 64 6F 63 75 6D 65 6E 74 2E 78 6D 6C" } } } } } }, "responses": { "200": { "description": "Calculation result envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileFormatDoctorResult" } } } }, "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" } } } } } }, "FileFormatDoctorInput": { "type": "object", "additionalProperties": false, "properties": { "file": { "title": "File", "description": "Analysed in memory and not stored. Max 10 MiB. Upload as {filename, contentType?, contentBase64}. Max 10240 KiB. Accepts */*.", "type": "object", "additionalProperties": false, "required": [ "filename", "contentBase64" ], "properties": { "filename": { "type": "string" }, "contentType": { "type": "string" }, "contentBase64": { "type": "string" } } }, "filename": { "title": "File name (for hex input)", "description": "Used to compare the extension with the detected format. Ignored when a file is uploaded.", "type": "string", "maxLength": 255 }, "hexBytes": { "title": "Or: first bytes as hex", "description": "E.g. from `xxd -l 512 file` or `Format-Hex`. At least 16 bytes recommended; 512+ for ZIP-based formats.", "type": "string", "maxLength": 140000 } }, "required": [] }, "FileFormatDoctorResult": { "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": [ "input", "detected", "alternatives", "extensionMatches", "encrypted", "executable", "container", "text", "diagnoses", "conversions" ], "properties": { "input": { "type": "object", "additionalProperties": false, "required": [ "mode", "filename", "extension", "bytesAnalyzed", "completeFile" ], "properties": { "mode": { "type": "string", "enum": [ "upload", "hex" ] }, "filename": { "type": [ "string", "null" ] }, "extension": { "type": [ "string", "null" ] }, "bytesAnalyzed": { "type": "integer", "minimum": 0 }, "completeFile": { "type": "boolean", "description": "True for uploads (truncation checks possible); false for hex samples." } } }, "detected": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "mime", "category", "extensions", "confidence", "evidence" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "mime": { "type": "string" }, "category": { "type": "string" }, "extensions": { "type": "array", "items": { "type": "string" } }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ] }, "evidence": { "type": "string" } } }, "alternatives": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "evidence" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "evidence": { "type": "string" } } } }, "extensionMatches": { "type": [ "boolean", "null" ] }, "encrypted": { "type": [ "boolean", "null" ], "description": "null = cannot be determined from the bytes provided." }, "executable": { "type": "boolean" }, "container": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "entries", "sampleEntries", "encryptedEntries", "hasEndRecord", "mimetype" ], "properties": { "entries": { "type": "integer" }, "sampleEntries": { "type": "array", "items": { "type": "string" }, "maxItems": 20 }, "encryptedEntries": { "type": "integer" }, "hasEndRecord": { "type": "boolean" }, "mimetype": { "type": [ "string", "null" ] } } }, "text": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "encoding", "bom", "mojibake" ], "properties": { "encoding": { "type": "string" }, "bom": { "type": "boolean" }, "mojibake": { "type": "array", "items": { "type": "string" } } } }, "diagnoses": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "code", "severity", "message", "evidence" ], "properties": { "code": { "type": "string" }, "severity": { "type": "string", "enum": [ "critical", "warning", "info", "ok" ] }, "message": { "type": "string" }, "evidence": { "type": "string" } } } }, "conversions": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "goal", "tool", "command", "note" ], "properties": { "goal": { "type": "string" }, "tool": { "type": "string" }, "command": { "type": "string" }, "note": { "type": "string" } } } } } }, "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" } } } } } } } }