{"id":"magic-bytes","title":"File type vs leading bytes (magic numbers, disguised HTML, truncation)","description":"Compares a claimed file type (MIME type and/or file name) with the first bytes of the file, for an agent that is about to open, parse or forward a download. Detects PNG, JPEG, GIF, WebP, ZIP and OOXML (docx/xlsx/pptx), GZIP, PDF, MP4 (ftyp), ELF, PE, RAR, BMP, ICO and HTML, flags an HTML login or error page saved as a PDF/image/archive, and reports truncation from end-of-file markers when the last bytes or the total size are supplied. Input is base64 of up to 32 KiB of head bytes and optionally 4 KiB of tail bytes. It does not decompress, validate image data, scan for malware, or prove a file is safe; a pass means the signature and the structural markers it could see are consistent with the claim.","roi":"A saved login page named report.pdf costs a failed parse and a retry loop; this catches it for half a cent.","audience":"developer","package":"infra-preflight-kit","channels":["x402","mcp"],"endpoint":{"method":"POST","url":"https://agents.writerslogic.com/api/v1/magic-bytes","path":"/api/v1/magic-bytes","contentType":"application/json"},"price":{"amount":"0.005","currency":"USDC","network":"base","perCall":true,"failedCallsCharged":false},"inputSchema":{"type":"object","additionalProperties":false,"required":["head"],"properties":{"head":{"type":"string","maxLength":43692,"description":"Standard padded base64 of the first bytes of the file (up to 32768 bytes decoded)."},"tail":{"type":"string","maxLength":5464,"description":"Optional base64 of the last bytes (up to 4096 decoded), used for end-of-file markers when head is not the whole file."},"totalSize":{"type":"integer","minimum":0,"maximum":1000000000000,"description":"Optional total file size in bytes, for size-field comparisons (RIFF, MP4 boxes, ZIP directory)."},"complete":{"type":"boolean","description":"True when head is the entire file; end-of-file markers are then checked on it."},"claimedName":{"type":"string","maxLength":255,"description":"File name or path; the last extension is the claim."},"claimedMime":{"type":"string","maxLength":255,"description":"Claimed Content-Type, parameters ignored."}}},"resultSchema":{"type":"object","properties":{"status":{"type":"string","enum":["pass","fail","unknown","unsupported"],"description":"pass: every rule held. fail: a rule was violated (see witnesses). unknown: the input lacks the evidence to decide. unsupported: outside what this engine covers. Missing evidence is never a pass."},"detected":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string"},"mime":{"type":"string"},"offset":{"type":"integer"},"subtype":{"type":"string"},"details":{"description":"Format-specific facts such as ZIP entry names or the PE machine."}}},{"type":"null"}],"description":"Detected format {kind, mime, offset, subtype?, details?}, or null when no signature matched."},"claimed":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string","enum":["mime","extension"]},"value":{"type":"string"},"format":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Format kind the engine maps the claim to, or null."}}}},"truncation":{"type":"string","enum":["complete","truncated","not-evaluated"],"description":"Rule ids: magic.mismatch, magic.html-disguised, magic.no-signature, magic.binary-as-text, magic.truncated, magic.empty, magic.claims-disagree, magic.container-subtype, plus per-format png.*, jpeg.*, pdf.*, zip.*, gzip.*, webp.*, elf.*, pe.*, mp4.*."},"firstBytesHex":{"type":"string"},"bytesChecked":{"type":"integer"},"notes":{"type":"array","items":{"type":"string"},"description":"Non-failing observations."},"witnesses":{"type":"array","items":{"type":"object","properties":{"ruleId":{"type":"string"},"detail":{"type":"string"},"path":{"type":"string","description":"JSON pointer or dotted path into the input."},"offset":{"type":"integer"},"index":{"type":"integer"},"expected":{"description":"What the rule required."},"actual":{"description":"What the input had."}}}},"versions":{"type":"object","description":"Every semantic dependency of this answer (engine, tables and their as-of dates, tokenizer, calendar, rounding profile)."},"limits":{"type":"array","items":{"type":"string"}},"deterministic":{"type":"boolean","description":"Always true: pure code, no model."}}},"outputSchema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","enum":["pass","fail","unknown","unsupported"],"description":"pass: every rule held. fail: a rule was violated (see witnesses). unknown: the input lacks the evidence to decide. unsupported: outside what this engine covers. Missing evidence is never a pass."},"detected":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string"},"mime":{"type":"string"},"offset":{"type":"integer"},"subtype":{"type":"string"},"details":{"description":"Format-specific facts such as ZIP entry names or the PE machine."}}},{"type":"null"}],"description":"Detected format {kind, mime, offset, subtype?, details?}, or null when no signature matched."},"claimed":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string","enum":["mime","extension"]},"value":{"type":"string"},"format":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Format kind the engine maps the claim to, or null."}}}},"truncation":{"type":"string","enum":["complete","truncated","not-evaluated"],"description":"Rule ids: magic.mismatch, magic.html-disguised, magic.no-signature, magic.binary-as-text, magic.truncated, magic.empty, magic.claims-disagree, magic.container-subtype, plus per-format png.*, jpeg.*, pdf.*, zip.*, gzip.*, webp.*, elf.*, pe.*, mp4.*."},"firstBytesHex":{"type":"string"},"bytesChecked":{"type":"integer"},"notes":{"type":"array","items":{"type":"string"},"description":"Non-failing observations."},"witnesses":{"type":"array","items":{"type":"object","properties":{"ruleId":{"type":"string"},"detail":{"type":"string"},"path":{"type":"string","description":"JSON pointer or dotted path into the input."},"offset":{"type":"integer"},"index":{"type":"integer"},"expected":{"description":"What the rule required."},"actual":{"description":"What the input had."}}}},"versions":{"type":"object","description":"Every semantic dependency of this answer (engine, tables and their as-of dates, tokenizer, calendar, rounding profile)."},"limits":{"type":"array","items":{"type":"string"}},"deterministic":{"type":"boolean","description":"Always true: pure code, no model."}}},"_provenance":{"type":"object","description":"C2PA-aligned manifest and W3C VC 2.0 (eddsa-jcs-2022) issued by the hub DID; verify at POST /api/v1/verify-provenance"}},"required":["data","_provenance"]},"example":{"head":"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAAAElFTkSuQmCC","complete":true,"claimedName":"logo.png","claimedMime":"image/png"},"openapiOperation":{"operationId":"magic_bytes","summary":"File type vs leading bytes (magic numbers, disguised HTML, truncation)","description":"Compares a claimed file type (MIME type and/or file name) with the first bytes of the file, for an agent that is about to open, parse or forward a download. Detects PNG, JPEG, GIF, WebP, ZIP and OOXML (docx/xlsx/pptx), GZIP, PDF, MP4 (ftyp), ELF, PE, RAR, BMP, ICO and HTML, flags an HTML login or error page saved as a PDF/image/archive, and reports truncation from end-of-file markers when the last bytes or the total size are supplied. Input is base64 of up to 32 KiB of head bytes and optionally 4 KiB of tail bytes. It does not decompress, validate image data, scan for malware, or prove a file is safe; a pass means the signature and the structural markers it could see are consistent with the claim.\n\nPrice: 0.005 USDC on Base (x402).","x-x402-price-usdc":"0.005","x-x402-amount":"5000","x-payment-info":{"protocols":["x402"],"price":{"mode":"fixed","currency":"USD","amount":"0.005"}},"x-audience":"developer","x-sample-url":"https://agents.writerslogic.com/api/v1/samples/magic-bytes","security":[{"x402":[]},{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["head"],"properties":{"head":{"type":"string","maxLength":43692,"description":"Standard padded base64 of the first bytes of the file (up to 32768 bytes decoded)."},"tail":{"type":"string","maxLength":5464,"description":"Optional base64 of the last bytes (up to 4096 decoded), used for end-of-file markers when head is not the whole file."},"totalSize":{"type":"integer","minimum":0,"maximum":1000000000000,"description":"Optional total file size in bytes, for size-field comparisons (RIFF, MP4 boxes, ZIP directory)."},"complete":{"type":"boolean","description":"True when head is the entire file; end-of-file markers are then checked on it."},"claimedName":{"type":"string","maxLength":255,"description":"File name or path; the last extension is the claim."},"claimedMime":{"type":"string","maxLength":255,"description":"Claimed Content-Type, parameters ignored."}}},"example":{"head":"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAAAElFTkSuQmCC","complete":true,"claimedName":"logo.png","claimedMime":"image/png"}}}},"responses":{"200":{"description":"Paid result with provenance","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","enum":["pass","fail","unknown","unsupported"],"description":"pass: every rule held. fail: a rule was violated (see witnesses). unknown: the input lacks the evidence to decide. unsupported: outside what this engine covers. Missing evidence is never a pass."},"detected":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string"},"mime":{"type":"string"},"offset":{"type":"integer"},"subtype":{"type":"string"},"details":{"description":"Format-specific facts such as ZIP entry names or the PE machine."}}},{"type":"null"}],"description":"Detected format {kind, mime, offset, subtype?, details?}, or null when no signature matched."},"claimed":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string","enum":["mime","extension"]},"value":{"type":"string"},"format":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Format kind the engine maps the claim to, or null."}}}},"truncation":{"type":"string","enum":["complete","truncated","not-evaluated"],"description":"Rule ids: magic.mismatch, magic.html-disguised, magic.no-signature, magic.binary-as-text, magic.truncated, magic.empty, magic.claims-disagree, magic.container-subtype, plus per-format png.*, jpeg.*, pdf.*, zip.*, gzip.*, webp.*, elf.*, pe.*, mp4.*."},"firstBytesHex":{"type":"string"},"bytesChecked":{"type":"integer"},"notes":{"type":"array","items":{"type":"string"},"description":"Non-failing observations."},"witnesses":{"type":"array","items":{"type":"object","properties":{"ruleId":{"type":"string"},"detail":{"type":"string"},"path":{"type":"string","description":"JSON pointer or dotted path into the input."},"offset":{"type":"integer"},"index":{"type":"integer"},"expected":{"description":"What the rule required."},"actual":{"description":"What the input had."}}}},"versions":{"type":"object","description":"Every semantic dependency of this answer (engine, tables and their as-of dates, tokenizer, calendar, rounding profile)."},"limits":{"type":"array","items":{"type":"string"}},"deterministic":{"type":"boolean","description":"Always true: pure code, no model."}}},"_provenance":{"type":"object","description":"C2PA-aligned manifest and W3C VC 2.0 (eddsa-jcs-2022) issued by the hub DID; verify at POST /api/v1/verify-provenance"}},"required":["data","_provenance"]}}}},"400":{"description":"Invalid request (no payment consumed)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"401":{"description":"Invalid X-API-KEY","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"402":{"description":"Payment required or invalid","content":{"application/json":{"schema":{"type":"object","description":"x402 v2 PaymentRequired (also base64 in the PAYMENT-REQUIRED header)","properties":{"x402Version":{"type":"integer"},"error":{"type":"string"},"code":{"type":"string"},"resource":{"type":"object"},"accepts":{"type":"array","items":{"type":"object"}},"extensions":{"type":"object"}}}}}},"502":{"description":"Upstream failure; the payment is released or not settled","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}}}},"links":{"docs":"https://agents.writerslogic.com/docs/magic-bytes/","docsJson":"https://agents.writerslogic.com/docs/magic-bytes.json","sample":"https://agents.writerslogic.com/api/v1/samples/magic-bytes","openapi":"https://agents.writerslogic.com/openapi.json","catalog":"https://agents.writerslogic.com/api/v1/catalog","verifyProvenance":"https://agents.writerslogic.com/api/v1/verify-provenance","index":"https://agents.writerslogic.com/docs/index.json"}}