utilsforagents

JSON structural diff — compare two JSON values and get a precise list of every difference. PURPOSE: Deep-compare any two JSON values (objects, arrays, strings, numbers, booleans, null) and return a machine-readable changeset. Ideal for change detection, audit trails, configuration drift checks, comparing API responses, building changelogs, or diffing LLM tool call arguments. REQUEST FORMAT: Method: POST Content-Type: application/json Body: {"left": <original structured JSON>, "right": <modified structured JSON>} Both left and right are required. Each must be a JSON object or array. Null, numbers, strings, and booleans are rejected with a 422 error. OPTIONAL PARAMETERS (in body): options.includeUnchanged (boolean, default false): When true, the stats.unchanged counter includes paths that are identical in both inputs. options.maxDepth (integer 1–256, default 64): Maximum nesting depth to traverse. Beyond this depth, values are compared by reference equality only. Set lower for very deeply nested structures to limit output size. RESPONSE FORMAT (200 OK, application/json): { "ok": true, "stats": { "added": <number of new paths in right>, "removed": <number of paths missing from right>, "changed": <number of paths with different values>, "unchanged": <count, non-zero only when includeUnchanged is true>, "processingTimeMs": <float, typically under 1ms> }, "diff": [ {"op": "add", "path": "/newField", "value": "new"}, {"op": "remove", "path": "/oldField", "value": "was here"}, {"op": "replace", "path": "/name", "oldValue": "Alice", "newValue": "Bob"} ] } Each diff entry has: op (one of 'add', 'remove', 'replace'), path (RFC 6901 JSON Pointer, e.g. '/users/0/email'), and value fields. ERROR RESPONSES (all errors use application/problem+json per RFC 9457): 400 Bad Request — body is not valid JSON 402 Payment Required — x402 payment not provided or invalid 422 Unprocessable Entity — missing 'left'/'right', invalid top-level types, or invalid option types LIMITS: No explicit size limit on the JSON body, but Cloudflare Workers enforce a maximum request size. Typical latency: <1ms for small objects, <50ms for very large structures. COST: $0.003 USD per call, paid via x402 protocol (USDC on Base network, eip155:8453).

EXIF metadata extraction — read all camera, GPS, and image metadata from a JPEG photo. PURPOSE: Parse the EXIF APP1 segment of a JPEG image and return structured metadata as JSON. Extracts camera make/model, GPS coordinates (latitude, longitude, altitude), timestamps (DateTimeOriginal, DateTimeDigitized, DateTime), exposure settings (aperture/f-number, shutter speed/exposure time, ISO), focal length, image dimensions (width x height in pixels), orientation flag (1-8), and software tag. Only JPEG images with embedded EXIF data are supported; PNG, GIF, WebP, and HEIF are not supported. REQUEST FORMAT — two upload modes: Mode 1 — Raw binary body: Method: POST Content-Type: image/jpeg Body: raw JPEG bytes Mode 2 — Multipart form: Method: POST Content-Type: multipart/form-data Field name: 'file' (must be exactly this name) Field value: JPEG binary RESPONSE FORMAT (200 OK, application/json): { "ok": true, "processingTimeMs": 1.2, "exif": { "make": "Apple", "model": "iPhone 15 Pro", "dateTimeOriginal": "2024:06:15 14:23:01", "gps": {"latitude": 37.7749, "longitude": -122.4194, "altitude": 12.5}, "fNumber": 1.78, "exposureTime": "1/120", "isoSpeedRatings": 64, "focalLength": 6.86, "orientation": 1, "imageWidth": 4032, "imageHeight": 3024, "software": "17.5.1" } } GPS coords are decimal degrees (positive = N/E, negative = S/W). gps is null if no GPS IFD is present. ERROR RESPONSES (all errors use application/problem+json per RFC 9457): 400 Bad Request — upload too small to be a valid image (<4 bytes), or multipart missing 'file' field 402 Payment Required — x402 payment not provided or invalid 413 Payload Too Large — upload exceeds the 5 MB limit (5,242,880 bytes) 415 Unsupported Media Type — no EXIF data found (not a JPEG, or JPEG has no EXIF segment) LIMITS: Maximum upload size: 5 MB (5,242,880 bytes). Only JPEG format supported. Images without EXIF return 415. Typical latency: 1-5ms. COST: $0.003 USD per call, paid via x402 protocol (USDC on Base network, eip155:8453).

Image metadata scrubber — permanently remove all EXIF, XMP, and IPTC metadata from JPEG or PNG images. PURPOSE: Strip all embedded metadata from an image file and return the cleaned image as raw binary bytes. Removes EXIF (camera make/model, GPS location, timestamps, lens info, orientation), XMP (Adobe edit history, rights, color profiles), IPTC (captions, keywords, copyright, contact details), ICC color profiles, and all APP0-APP15 marker segments for JPEG. For PNG, strips all ancillary chunks (tEXt, iTXt, zTXt, eXIf, iCCP, etc.), keeping only critical chunks (IHDR, PLTE, IDAT, IEND). The output is pixel-identical to the input — only metadata blobs are removed, image data is never re-encoded or modified. REQUEST FORMAT — two upload modes: Mode 1 — Raw binary body: Method: POST Content-Type: image/jpeg OR image/png Body: raw image bytes Mode 2 — Multipart form: Method: POST Content-Type: multipart/form-data Field name: 'file' (must be exactly this name) Field value: JPEG or PNG binary RESPONSE FORMAT (200 OK): Raw binary image bytes. Content-Type: image/jpeg (if input was JPEG) or image/png (if input was PNG). The response body is NOT JSON — it is the cleaned image file ready to save or forward. If no metadata was present, the image is returned unchanged. ERROR RESPONSES (all errors use application/problem+json per RFC 9457): 400 Bad Request — upload too small (<8 bytes for valid image), or multipart missing 'file' field 402 Payment Required — x402 payment not provided or invalid 413 Payload Too Large — upload exceeds the 5 MB limit (5,242,880 bytes) 415 Unsupported Media Type — file is not a valid JPEG (missing FFD8 SOI) or PNG (missing 89504E47 header) LIMITS: Maximum upload size: 5 MB (5,242,880 bytes). Only JPEG and PNG formats supported — not GIF, WebP, HEIF, BMP, TIFF, or AVIF. Typical latency: 2-10ms. IMPORTANT: The response is raw binary, NOT JSON. Parse the Content-Type header to determine the image format. Write the response body bytes directly to a file to save. USE CASES: Privacy protection before publishing photos (strip GPS that reveals home/work), GDPR compliance for user-uploaded images, removing editing history metadata, sanitizing images before feeding to vision models, stripping watermark metadata from stock photos. COST: $0.003 USD per call, paid via x402 protocol (USDC on Base network, eip155:8453).

HTML to Markdown converter — transform an HTML string into clean, readable Markdown. PURPOSE: Convert raw HTML to Markdown for use in LLM context windows, document storage, downstream text processing, or anywhere you need clean readable text from HTML. The converter handles inline formatting (bold, italic, strikethrough, inline code, links, images, line breaks), block elements (paragraphs, headings h1-h6, blockquotes, horizontal rules, preformatted/code blocks with fenced ``` syntax), ordered and unordered lists with nesting, and GitHub Flavored Markdown tables (GFM pipe syntax). Non-content elements are stripped entirely: script, style, iframe, noscript, svg, canvas, template, object, embed. Block containers (div, section, article, aside, header, footer, nav, form) are collapsed to whitespace, preserving their inner text. HTML entities are decoded (including &amp; &lt; &gt; &nbsp; &mdash; &hellip; and numeric/hex entities). REQUEST FORMAT — two modes: Mode 1 — JSON body: Method: POST Content-Type: application/json Body: {"html": "<h1>Hello</h1><p>World</p>"} The 'html' field is required and must be a non-empty string. Mode 2 — Raw HTML body: Method: POST Content-Type: text/html (or any non-JSON content type) Body: raw HTML string bytes RESPONSE FORMAT (200 OK, application/json): { "ok": true, "processingTimeMs": 0.3, "charsBefore": 4200, "charsAfter": 1150, "markdown": "# Hello\n\nWorld" } charsBefore = character count of input HTML, charsAfter = character count of output Markdown. Use these to measure compression ratio. ERROR RESPONSES (all errors use application/problem+json per RFC 9457): 400 Bad Request — body is empty, or 'html' field is missing/empty in JSON mode, or body is not valid JSON when Content-Type is application/json 402 Payment Required — x402 payment not provided or invalid 413 Payload Too Large — input exceeds the 5 MB limit (5,242,880 bytes) 422 Unprocessable Entity — JSON body present but missing required 'html' field LIMITS: Maximum input size: 5 MB (5,242,880 bytes). Designed for <10ms on typical web pages (up to ~500 KB HTML). No external fetching — you must provide the HTML string directly. Use /v1/html/fetch-markdown if you need to fetch a URL first. COST: $0.003 USD per call, paid via x402 protocol (USDC on Base network, eip155:8453).

URL to Markdown fetcher — download a web page and convert its HTML to clean Markdown in one step. PURPOSE: Fetch a remote URL, download the HTML response, strip non-content elements (scripts, styles, nav, ads), and convert to clean Markdown. Follows HTTP redirects automatically. Returns both the Markdown text and the final resolved URL after redirects. Ideal for reading web articles, documentation pages, blog posts, or any public HTML page and getting clean text suitable for LLM context windows, RAG pipelines, or document storage. REQUEST FORMAT: Method: POST Content-Type: application/json Body: {"url": "https://quotes.toscrape.com/article"} The 'url' field is required and must be a non-empty string containing a valid http or https URL. URL RESTRICTIONS (SSRF protection — these will return 400): Blocked: Private/RFC-1918 IPs (10.x.x.x, 172.16-31.x.x, 192.168.x.x), loopback (127.x.x.x, localhost, [::1], 0.0.0.0), link-local (169.254.x.x, fe80::), cloud metadata (169.254.169.254, metadata.google.internal), internal hostnames (*.internal, *.local, *.localhost), URLs with embedded credentials (user:pass@host), non-HTTP protocols (ftp://, file://, data:, javascript:). Allowed: Only http:// and https:// with public hostnames. RESPONSE FORMAT (200 OK, application/json): { "ok": true, "processingTimeMs": 145.2, "sourceUrl": "https://quotes.toscrape.com/article", "charsBefore": 58000, "charsAfter": 4200, "markdown": "# Article Title\n\nContent..." } sourceUrl reflects the final URL after any redirects (may differ from the requested URL). ERROR RESPONSES (all errors use application/problem+json per RFC 9457): 400 Bad Request — invalid URL format, URL points to private/blocked address, remote server returned non-2xx, remote fetch timed out after 5 seconds, or 'url' field missing/empty 402 Payment Required — x402 payment not provided or invalid 413 Payload Too Large — remote response exceeds the 2 MB download limit (2,097,152 bytes) 422 Unprocessable Entity — JSON body present but missing required 'url' field LIMITS: Remote fetch timeout: 5 seconds. Maximum download size: 2 MB (2,097,152 bytes). Sends Accept: text/html,application/xhtml+xml. Follows redirects. Does NOT execute JavaScript — this is an HTML-only fetch, not a headless browser. COST: $0.003 USD per call, paid via x402 protocol (USDC on Base network, eip155:8453).

Universal URL content fetcher — download any URL and return its text content with automatic format detection. PURPOSE: Fetch a remote URL, detect the content format from the response Content-Type header (falling back to content sniffing), and return clean text. Supports four formats: HTML (stripped of tags and converted to Markdown), JSON (recursively extracts human-readable text from content fields like title, body, content, description, summary, excerpt, headline, message while skipping metadata fields like id, url, timestamp, type), Markdown (returned as-is), and plain text (returned as-is). Use when you need to read content from any URL without knowing the format in advance. REQUEST FORMAT: Method: POST Content-Type: application/json Body: {"url": "https://quotes.toscrape.com/readme.md"} The 'url' field is required and must be a non-empty string containing a valid http or https URL. URL RESTRICTIONS (SSRF protection — these will return 400): Blocked: Private/RFC-1918 IPs (10.x.x.x, 172.16-31.x.x, 192.168.x.x), loopback (127.x.x.x, localhost, [::1], 0.0.0.0), link-local (169.254.x.x, fe80::), cloud metadata (169.254.169.254, metadata.google.internal), internal hostnames (*.internal, *.local, *.localhost), URLs with embedded credentials (user:pass@host), non-HTTP protocols (ftp://, file://, data:, javascript:). Allowed: Only http:// and https:// with public hostnames. RESPONSE FORMAT (200 OK, application/json): { "ok": true, "processingTimeMs": 88.4, "sourceUrl": "https://quotes.toscrape.com/readme.md", "contentType": "application/json", "detectedFormat": "markdown", "charsBefore": 3200, "charsAfter": 3200, "content": "{\"title\":\"README\",...}", "text": "# README\n\nProject documentation...", "markdown": "# README\n\nProject documentation..." } detectedFormat is one of: 'html', 'json', 'markdown', 'text'. sourceUrl reflects the final URL after any redirects. content is the decoded remote response body as text. text is the normalized readable text representation used for consumers that want extracted content. markdown is a backward-compatible alias of text. ERROR RESPONSES (all errors use application/problem+json per RFC 9457): 400 Bad Request — invalid URL, URL points to private/blocked address, remote server returned non-2xx, remote fetch timed out after 5 seconds, or 'url' field missing/empty 402 Payment Required — x402 payment not provided or invalid 413 Payload Too Large — remote response exceeds the 2 MB download limit (2,097,152 bytes) 422 Unprocessable Entity — JSON body present but missing required 'url' field LIMITS: Remote fetch timeout: 5 seconds. Maximum download size: 2 MB (2,097,152 bytes). Follows redirects. Does NOT execute JavaScript. Sends Accept: text/markdown,text/plain,application/json,*/*. COMPARISON WITH OTHER ENDPOINTS: /v1/html/to-markdown — use when you already have HTML in memory (no fetching). /v1/html/fetch-markdown — use when you know the URL serves HTML and want Markdown. /v1/text/fetch-content — use when you don't know the format and want the best text extraction automatically. /v1/url/metadata — use when you only need metadata (title, OG tags, etc.) not the full page content. COST: $0.003 USD per call, paid via x402 protocol (USDC on Base network, eip155:8453).

URL metadata extractor — fetch a web page and extract structured metadata from its HTML head. PURPOSE: Download a URL's HTML and parse all metadata from the <head> section, returning structured JSON without the full page content. Extracts title (<title> tag, with og:title fallback), description (<meta name='description'>, with og:description fallback), canonical URL (<link rel='canonical'>), language (<html lang>), favicon (resolved absolute URL from <link rel='icon'>, <link rel='shortcut icon'>, or <link rel='apple-touch-icon'>), RSS/Atom feed links (<link rel='alternate' type='application/rss+xml' or application/atom+xml>), Open Graph properties (all og:* meta tags: title, description, image, image:width, image:height, type, url, site_name, locale, video, audio, etc.), Twitter Card properties (all twitter:* meta tags: card, title, description, image, site, creator, player, etc.), and standard meta tags (author, keywords, robots, generator, theme-color, application-name). REQUEST FORMAT: Method: POST Content-Type: application/json Body: {"url": "https://quotes.toscrape.com"} The 'url' field is required and must be a non-empty string containing a valid http or https URL. URL RESTRICTIONS (SSRF protection — these will return 400): Blocked: Private/RFC-1918 IPs (10.x.x.x, 172.16-31.x.x, 192.168.x.x), loopback (127.x.x.x, localhost, [::1], 0.0.0.0), link-local (169.254.x.x, fe80::), cloud metadata (169.254.169.254, metadata.google.internal), internal hostnames (*.internal, *.local, *.localhost), URLs with embedded credentials (user:pass@host), non-HTTP protocols (ftp://, file://, data:, javascript:). Allowed: Only http:// and https:// with public hostnames. RESPONSE FORMAT (200 OK, application/json): { "ok": true, "processingTimeMs": 95.0, "sourceUrl": "https://quotes.toscrape.com", "metadata": { "title": "Example Domain", "description": "This domain is for illustrative examples.", "canonical": "https://quotes.toscrape.com", "language": "en", "favicon": "https://quotes.toscrape.com/favicon.ico", "feeds": [{"type": "application/rss+xml", "href": "https://quotes.toscrape.com/feed", "title": "Blog"}], "openGraph": {"title": "Example", "image": "https://quotes.toscrape.com/og.png", "type": "website"}, "twitterCard": {"card": "summary_large_image", "site": "@example"}, "meta": {"author": "Jane Doe", "keywords": "example, demo", "robots": "index, follow"} } } All metadata fields (title, description, canonical, language, favicon) are null when not present in the HTML. openGraph, twitterCard, and meta are empty objects {} when no matching tags are found. feeds is an empty array [] when no feed links are found. ERROR RESPONSES (all errors use application/problem+json per RFC 9457): 400 Bad Request — invalid URL, URL points to private/blocked address, remote server returned non-2xx, remote fetch timed out after 5 seconds, or 'url' field missing/empty 402 Payment Required — x402 payment not provided or invalid 413 Payload Too Large — remote response exceeds the 2 MB download limit (2,097,152 bytes) 422 Unprocessable Entity — JSON body present but missing required 'url' field LIMITS: Remote fetch timeout: 5 seconds. Maximum download size: 2 MB (2,097,152 bytes). Follows redirects. Sends Accept: text/html,application/xhtml+xml. Does NOT execute JavaScript — only parses the raw HTML response. USE CASES: Generating social sharing preview cards, checking Open Graph and Twitter Card setup for SEO tools, discovering RSS feed URLs, extracting canonical URLs for deduplication, building link unfurler/preview tools, getting page metadata for search indexing. COST: $0.003 USD per call, paid via x402 protocol (USDC on Base network, eip155:8453).

Token counter — count the number of tokens in a text string for any major LLM tokenizer. PURPOSE: Determine the exact or estimated token count of a text string using a specified tokenizer encoding. Use before sending text to an LLM to check context window fit, estimate API cost, enforce token budgets in agent pipelines, or split documents at token boundaries. SUPPORTED ENCODINGS (pass via 'encoding' field): 'cl100k_base' — GPT-4, GPT-4-turbo, GPT-3.5-turbo, text-embedding-ada-002. EXACT count via WASM-compiled BPE tokenizer (tiktoken). Default if encoding is omitted. 'o200k_base' — GPT-4o, GPT-4o-mini. EXACT count via WASM-compiled BPE tokenizer. 'claude' — Anthropic Claude 3, Claude 3.5, Claude 4 models. ESTIMATED count: ceil(character_count / 3.5). 'gemini' — Google Gemini 1.5, Gemini 2 models. ESTIMATED count: ceil(character_count / 4). IMAGE TOKEN ESTIMATION: Set content_type='image' when the text field contains a base64-encoded image. Uses tile-based estimation: ceil(raw_bytes / 750) where raw_bytes = base64_length * 0.75. Auto-detection: base64 strings starting with /9j/ (JPEG), iVBOR (PNG), or R0lGO (GIF) are automatically treated as images even if content_type is not set. REQUEST FORMAT: Method: POST Content-Type: application/json Body: {"text": "Your text here", "encoding": "cl100k_base"} Required fields: 'text' (non-empty string). Optional fields: 'encoding' (string, default 'cl100k_base'), 'content_type' (string: 'text' or 'image', default 'text'). RESPONSE FORMAT (200 OK, application/json): { "ok": true, "processingTimeMs": 1.23, "encoding": "cl100k_base", "method": "exact", "tokenCount": 4, "characterCount": 13, "utf8Sanitized": false } method is 'exact' for cl100k_base and o200k_base (real BPE tokenization), or 'estimate' for claude, gemini, and image content. utf8Sanitized is true if the input contained invalid UTF-8 byte sequences that were cleaned before counting (characterCount reflects the sanitized length). ERROR RESPONSES (all errors use application/problem+json per RFC 9457): 400 Bad Request — 'text' field is missing, empty, or not a string; invalid encoding name; body is not valid JSON 402 Payment Required — x402 payment not provided or invalid 413 Payload Too Large — text input exceeds the 50 MB limit (52,428,800 bytes) 422 Unprocessable Entity — JSON body present but missing required 'text' field LIMITS: Maximum text size: 50 MB (52,428,800 bytes). Both the Content-Length header and the actual text byte length are checked against this limit. Typical latency: <2ms for estimates (claude, gemini, image), 5-50ms for exact BPE tokenization (cl100k_base, o200k_base) depending on text length. COMMON MISTAKES: Sending encoding='gpt-4' — use 'cl100k_base' or 'o200k_base' instead (these are tokenizer names, not model names). Sending an empty text field — will return 400. Sending a number or array as text — must be a string. COST: $0.003 USD per call, paid via x402 protocol (USDC on Base network, eip155:8453).