File type vs leading bytes (magic numbers, disguised HTML, truncation)

$0.005 USDC per call · Developer and security · POST /api/v1/magic-bytes · Id magic-bytes

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.

What you get

A saved login page named report.pdf costs a failed parse and a retry loop; this catches it for half a cent.

Call it

Send the JSON body below to https://agents.writerslogic.com/api/v1/magic-bytes. An unpaid request answers 402 with the price and how to pay; a request that fails with a 5xx status is not charged.

curl -i -X POST https://agents.writerslogic.com/api/v1/magic-bytes \
  -H 'content-type: application/json' \
  -d '{"head":"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAAAElFTkSuQmCC","complete":true,"claimedName":"logo.png","claimedMime":"image/png"}'

Input

Field	Type	Required	Description
`head`	string; length 0..43692	yes	Standard padded base64 of the first bytes of the file (up to 32768 bytes decoded).
`tail`	string; length 0..5464	no	Optional base64 of the last bytes (up to 4096 decoded), used for end-of-file markers when head is not the whole file.
`totalSize`	integer; 0..1000000000000	no	Optional total file size in bytes, for size-field comparisons (RIFF, MP4 boxes, ZIP directory).
`complete`	boolean	no	True when head is the entire file; end-of-file markers are then checked on it.
`claimedName`	string; length 0..255	no	File name or path; the last extension is the claim.
`claimedMime`	string; length 0..255	no	Claimed Content-Type, parameters ignored.

Example request body

{
  "head": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAAAElFTkSuQmCC",
  "complete": true,
  "claimedName": "logo.png",
  "claimedMime": "image/png"
}

Result

The response is { "data": ..., "_provenance": ... }. data carries these fields; _provenance is a signed W3C Verifiable Credential with a C2PA-style manifest, checked free at POST /api/v1/verify-provenance.

Field	Type	Required	Description
`status`	string; one of "pass", "fail", "unknown", "unsupported"	no	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`	one of	no	Detected format {kind, mime, offset, subtype?, details?}, or null when no signature matched.
`claimed`	array<object>	no
`truncation`	string; one of "complete", "truncated", "not-evaluated"	no	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`	string	no
`bytesChecked`	integer	no
`notes`	array<string>	no	Non-failing observations.
`witnesses`	array<object>	no
`versions`	object	no	Every semantic dependency of this answer (engine, tables and their as-of dates, tokenizer, calendar, rounding profile).
`limits`	array<string>	no
`deterministic`	boolean	no	Always true: pure code, no model.

Pay and connect

Available through: x402 (USDC on Base), MCP. MCP clients reach it through the infra-preflight-kit package.

Machine-readable

This agent as JSON (schemas, example, OpenAPI operation)
Free signed sample response
OpenAPI 3.1 · Catalog · Index of every agent