{ "openapi": "3.1.0", "info": { "title": "mondello.dev marketplace API", "version": "1.0.0", "description": "x402-gated micropayment APIs — image generation, TTS, site diagnostics, and more. USDC on Base mainnet. Each paid route returns HTTP 402 with a PAYMENT-REQUIRED header; pay with any x402 client to retrieve the response.", "contact": { "name": "Romy Mondello", "email": "roman@mondello.dev", "url": "https://mondello.dev" }, "license": { "name": "CC BY 4.0" }, "x-payment-protocol": { "name": "x402", "version": "v2", "specUrl": "https://x402.org", "facilitator": "https://pay.openfacilitator.io", "treasury": "0x0E4d1C7Ca47879C7Dd518526ef38f290C7081028", "network": "Base mainnet (eip155:8453)", "asset": "USDC (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913)" } }, "servers": [ { "url": "https://www.mondello.dev", "description": "Production" } ], "paths": { "/api/catalog.json": { "get": { "summary": "Master catalog of all paid surfaces (free)", "description": "The canonical agent-facing pointer map. Lists every paid x402 skill + hosted API, the facilitator + wallet config, and a `pointers` block with URLs for every discovery surface (feeds, OpenAPI, MCP, audio proxy template, etc.). Agents starting from a single URL use this to bootstrap everything else.", "operationId": "getCatalog", "responses": { "200": { "description": "Full catalog with x402 payment metadata.", "content": { "application/json": { "schema": { "type": "object", "required": [ "version", "source", "wallet", "currency", "network", "facilitator", "counts", "skills", "hostedApis", "content", "pointers" ], "properties": { "version": { "type": "string", "description": "Catalog schema version." }, "source": { "type": "string", "description": "Canonical URL of this catalog." }, "description": { "type": "string" }, "wallet": { "type": "string", "description": "Destination wallet address (0x...) for x402 payments." }, "currency": { "type": "string", "enum": [ "USDC" ] }, "network": { "type": "string", "description": "Payment network, e.g. 'base' (Ethereum L2 chainId 8453)." }, "facilitator": { "type": "string", "format": "uri", "description": "x402 facilitator URL that processes the payment." }, "counts": { "type": "object", "description": "Aggregate counts (skills, hosted APIs, content items)." }, "skills": { "type": "array", "description": "Every published paid skill with price + install metadata." }, "hostedApis": { "type": "array", "description": "Every hosted x402 API with method, path, price, and description." }, "content": { "type": "array", "description": "Paid content bundles (e.g. /llms-full.txt)." }, "pointers": { "type": "object", "description": "Named URLs for every discovery surface — feeds, OpenAPI, MCP, audio proxy, cron health. Keys are stable across catalog versions; use these instead of hard-coding paths.", "additionalProperties": { "type": "string", "format": "uri" } } } } } } } } } }, "/api/stats.json": { "get": { "summary": "Coarse activity stats (free, public, cached 5 min)", "description": "Point-in-time marketplace activity — total x402 transactions, last sale timestamp, top-selling resources by revenue, and a 30-day dated summary. Used by /status + external dashboards.", "operationId": "getStats", "responses": { "200": { "description": "Activity snapshot.", "content": { "application/json": { "schema": { "type": "object", "required": [ "totalTransactions", "topResources", "last30Days", "updatedAt" ], "properties": { "totalTransactions": { "type": "integer", "minimum": 0, "description": "Lifetime count of paid x402 transactions." }, "lastSaleAt": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO-8601 timestamp of the most-recent paid transaction, or null if no sales yet." }, "topResources": { "type": "array", "description": "Top-revenue resources all-time. Empty while the marketplace is new.", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "Resource URL path, e.g. /skills/auto-audio-player." }, "count": { "type": "integer", "minimum": 1 }, "totalCents": { "type": "integer", "description": "Revenue in USD cents (summed across transactions)." } } } }, "last30Days": { "type": "array", "description": "Date-bucketed transaction counts for the trailing 30 days, oldest → newest.", "items": { "type": "object", "required": [ "date", "count" ], "properties": { "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "count": { "type": "integer", "minimum": 0 } } } }, "updatedAt": { "type": "string", "format": "date-time", "description": "When this payload was generated. 5-minute cache TTL upstream." } } } } } } } } }, "/api/cron-health.json": { "get": { "summary": "Cron observability payload (free, public)", "description": "Reports the latest run of each scheduled job (hourly D1 backup, auto-media scan, daily/weekly/monthly backups). Use for external monitoring — the top-level `fresh` boolean goes false once the most-recent cron is older than expected. Uptime monitors can flip an alert on `.fresh === false` without any threshold math of their own.", "operationId": "getCronHealth", "responses": { "200": { "description": "Latest per-tier cron run + combined latest + freshness boolean.", "content": { "application/json": { "schema": { "type": "object", "required": [ "fresh", "byTier" ], "properties": { "fresh": { "type": "boolean", "description": "True when the most-recent cron across all tiers is within its expected window. False is the actionable signal for external monitors." }, "secondsSinceLastRun": { "type": "integer", "description": "Seconds elapsed since the most-recent cron finish." }, "cronLastRun": { "type": [ "object", "null" ], "properties": { "cron": { "type": "string", "description": "Cron expression." }, "tier": { "type": "string", "description": "Job tier name, e.g. 'backup:hourly' / 'auto-media'." }, "startedAt": { "type": "string", "format": "date-time" }, "finishedAt": { "type": "string", "format": "date-time" }, "ok": { "type": "boolean" }, "results": { "description": "Tier-specific payload. backup jobs report {prefix, tables, totalBytes}; auto-media reports the per-post results array." }, "error": { "type": "string" } } }, "byTier": { "type": "object", "additionalProperties": { "type": "object", "properties": { "cron": { "type": "string" }, "tier": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time" }, "finishedAt": { "type": "string", "format": "date-time" }, "ok": { "type": "boolean" }, "results": {}, "error": { "type": "string" } } } } } } } } } } } }, "/api/search.json": { "get": { "summary": "Public full-text search (free)", "description": "Scored search over published posts + pages. Title matches score 2x, excerpt 1x, body tokens 0.3x. Surfaces `hasNarration` + `narrationDuration` on post results so LiveSearch clients can render the 🎧 badge with duration inline.", "operationId": "search", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2 }, "description": "Query string (min 2 chars)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 } }, { "name": "collections", "in": "query", "required": false, "schema": { "type": "string", "default": "posts,pages" }, "description": "Comma-separated list of collections to search across. Currently 'posts' and 'pages'." } ], "responses": { "200": { "description": "Scored results.", "content": { "application/json": { "schema": { "type": "object", "required": [ "results", "query", "total" ], "properties": { "query": { "type": "string" }, "total": { "type": "integer", "description": "Total matches across all collections before limit is applied." }, "results": { "type": "array", "items": { "type": "object", "required": [ "title", "url", "collection" ], "properties": { "title": { "type": "string" }, "url": { "type": "string", "format": "uri-reference" }, "collection": { "type": "string", "enum": [ "posts", "pages" ] }, "snippet": { "type": "string", "description": "Excerpt context around the match, with wrapping the matched terms (HTML-safe — only is allowed)." }, "hasNarration": { "type": "boolean", "description": "True if this post has AI-narrated audio (posts only; never set on pages)." }, "narrationDuration": { "type": "string", "pattern": "^\\d+:\\d{2}(:\\d{2})?$", "description": "Formatted audio duration as mm:ss or h:mm:ss when narration exists." } } } } } } } } } } } }, "/skills.json": { "get": { "summary": "Skills-only manifest (free)", "description": "Published skills with price + install metadata + x402 payment parameters. Narrower scope than /api/catalog.json — ideal for agents iterating the skills marketplace without walking the full catalog.", "operationId": "listSkills", "responses": { "200": { "description": "Skills manifest.", "content": { "application/json": { "schema": { "type": "object", "required": [ "version", "source", "count", "currency", "network", "payTo", "installPattern", "previewPattern", "items" ], "properties": { "version": { "type": "string", "description": "Manifest schema version." }, "source": { "type": "string", "format": "uri" }, "count": { "type": "integer", "minimum": 0, "description": "items.length — aggregate published-skill count." }, "currency": { "type": "string", "enum": [ "USDC" ] }, "network": { "type": "string", "description": "CAIP-2 chain ID, e.g. 'eip155:8453' for Base mainnet." }, "payTo": { "type": "string", "description": "Destination wallet (0x...) for x402 payments." }, "description": { "type": "string" }, "installPattern": { "type": "string", "description": "URL template for installing any skill, e.g. 'https://mondello.dev/skills/:slug/install'. Agents substitute :slug to build the install URL." }, "previewPattern": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "required": [ "slug", "title", "price", "previewUrl", "rawUrl", "installUrl", "installCommand", "x402" ], "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "excerpt": { "type": [ "string", "null" ] }, "price": { "type": "string", "description": "Display price like '$0.10'." }, "previewUrl": { "type": "string", "format": "uri" }, "rawUrl": { "type": "string", "format": "uri", "description": "402-gated download URL for the raw markdown." }, "installUrl": { "type": "string", "format": "uri" }, "installCommand": { "type": "string", "description": "Ready-to-paste curl | bash one-liner." }, "publishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "x402": { "type": "object", "description": "Payment parameters for agents.", "required": [ "scheme", "network", "asset", "payTo", "priceUsd", "priceMicroUsd" ], "properties": { "scheme": { "type": "string", "enum": [ "exact" ] }, "network": { "type": "string" }, "asset": { "type": "string" }, "assetName": { "type": "string" }, "payTo": { "type": "string" }, "priceUsd": { "type": "number" }, "priceMicroUsd": { "type": "string" } } } } } } } } } } } } } }, "/api/x402/media/image/generate": { "post": { "summary": "Generate a 16:9 editorial hero image ($0.05)", "description": "Calls MiniMax image-01. Takes ~100s per image. Returns raw JPEG bytes.", "operationId": "generateImage", "x-x402-payment": { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "assetName": "USDC", "payTo": "0x0E4d1C7Ca47879C7Dd518526ef38f290C7081028", "priceUsd": 0.05, "priceMicroUsd": "50000", "description": "Image generation via MiniMax image-01" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string", "description": "Title/prompt for the image." }, "excerpt": { "type": "string", "description": "Optional extra prompt context." }, "style": { "type": "string", "enum": [ "editorial-minimal", "photographic", "illustration" ], "default": "editorial-minimal" }, "aspectRatio": { "type": "string", "enum": [ "16:9", "1:1", "4:3" ], "default": "16:9" } } } } } }, "responses": { "200": { "description": "Generated JPEG", "content": { "image/jpeg": { "schema": { "type": "string", "format": "binary" } } } }, "402": { "description": "x402 payment required" } } } }, "/api/x402/media/narrate": { "post": { "summary": "Text → MP3 narration ($0.05)", "description": "Calls MiniMax speech-2.8-hd. Accepts up to 9500 chars of text or Portable Text blocks.", "operationId": "narrate", "x-x402-payment": { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "assetName": "USDC", "payTo": "0x0E4d1C7Ca47879C7Dd518526ef38f290C7081028", "priceUsd": 0.05, "priceMicroUsd": "50000", "description": "TTS narration via MiniMax speech-2.8-hd" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "description": "Plain text (preferred)" }, "blocks": { "type": "array", "description": "Portable Text blocks (alt to text)", "items": { "type": "object" } }, "voiceId": { "type": "string", "default": "English_SereneWoman" }, "speed": { "type": "number", "minimum": 0.5, "maximum": 2, "default": 1 }, "model": { "type": "string", "enum": [ "speech-2.8-hd", "speech-2.8-turbo" ], "default": "speech-2.8-hd" } } } } } }, "responses": { "200": { "description": "Generated MP3", "content": { "audio/mpeg": { "schema": { "type": "string", "format": "binary" } } } }, "402": { "description": "x402 payment required" } } } }, "/api/x402/agent-seo/bot-catalog": { "get": { "summary": "AI agent crawler catalog ($0.05, free with ?inspect=1)", "description": "Maintained list of 16+ AI crawlers — user-agent, operator, purpose, docs URL. Source for robots.txt generators.", "operationId": "getBotCatalog", "x-x402-payment": { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "assetName": "USDC", "payTo": "0x0E4d1C7Ca47879C7Dd518526ef38f290C7081028", "priceUsd": 0.05, "priceMicroUsd": "50000", "description": "Agent-SEO bot catalog" }, "parameters": [ { "name": "inspect", "in": "query", "schema": { "type": "string", "enum": [ "1" ] }, "description": "Set to 1 for free landing docs instead of the paid JSON." } ], "responses": { "200": { "description": "Catalog JSON", "content": { "application/json": { "schema": { "type": "object" } } } }, "402": { "description": "x402 payment required" } } } }, "/api/x402/llms/pack": { "post": { "summary": "URL → plaintext bundle packer ($0.05 base + $0.01/url)", "description": "Submit 1..20 https URLs, get a packaged plaintext bundle with HTML stripped. Cost scales with count.", "operationId": "packUrls", "x-x402-payment": { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "assetName": "USDC", "payTo": "0x0E4d1C7Ca47879C7Dd518526ef38f290C7081028", "priceUsd": 0.06, "priceMicroUsd": "60000", "description": "URL → llms-full bundle packer (1-URL minimum)" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "urls" ], "properties": { "urls": { "type": "array", "items": { "type": "string", "format": "uri" }, "minItems": 1, "maxItems": 20 }, "maxCharsPerPage": { "type": "integer", "default": 20000, "minimum": 1000 } } } } } }, "responses": { "200": { "description": "Packaged plaintext bundle", "content": { "text/plain": { "schema": { "type": "string" } } } }, "402": { "description": "x402 payment required" } } } }, "/api/x402/emdash/session-status": { "post": { "summary": "EmDash site diagnostic probe ($0.05)", "description": "Hits 12 standard EmDash surfaces (sitemap, llms.txt, mcp, admin, catalog) and returns findings + recommendations.", "operationId": "emdashSessionStatus", "x-x402-payment": { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "assetName": "USDC", "payTo": "0x0E4d1C7Ca47879C7Dd518526ef38f290C7081028", "priceUsd": 0.05, "priceMicroUsd": "50000", "description": "EmDash site diagnostic probe" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "siteUrl" ], "properties": { "siteUrl": { "type": "string", "format": "uri", "description": "Absolute https URL to probe." } } } } } }, "responses": { "200": { "description": "Findings + recommendations", "content": { "application/json": { "schema": { "type": "object" } } } }, "402": { "description": "x402 payment required" } } } }, "/llms-full.txt": { "get": { "summary": "Full content ingest — all posts inlined ($0.25)", "operationId": "getLlmsFull", "x-x402-payment": { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "assetName": "USDC", "payTo": "0x0E4d1C7Ca47879C7Dd518526ef38f290C7081028", "priceUsd": 0.25, "priceMicroUsd": "250000", "description": "Full blog content ingest" }, "responses": { "200": { "description": "Plaintext bundle", "content": { "text/plain": { "schema": { "type": "string" } } } }, "402": { "description": "x402 payment required" } } } }, "/skills/{slug}/raw": { "get": { "summary": "Skill markdown (paid download, $0.10)", "operationId": "getSkillRaw", "x-x402-payment": { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "assetName": "USDC", "payTo": "0x0E4d1C7Ca47879C7Dd518526ef38f290C7081028", "priceUsd": 0.1, "priceMicroUsd": "100000", "description": "Claude Code skill markdown download" }, "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Skill slug from /skills.json" } ], "responses": { "200": { "description": "Skill markdown", "content": { "text/plain": { "schema": { "type": "string" } } } }, "402": { "description": "x402 payment required" } } } }, "/skills/{slug}/install": { "get": { "summary": "Skill install script (free, fetches paid /raw)", "operationId": "getSkillInstallScript", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Bash install script", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/audio/{storage_key}.mp3": { "get": { "summary": "Narration audio stream (free, Range-aware)", "description": "MP3 endpoint for AI-narrated post audio, backed directly by the R2 MEDIA bucket. Accepts HTTP Range requests and returns 206 Partial Content — useful for agents that stream or seek audio in chunks rather than downloading the whole file. Storage keys are exposed in the tags of /rss.xml, /atom.xml, /feed.json, and /podcast.xml.", "operationId": "getNarrationAudio", "parameters": [ { "name": "storage_key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "R2 storage_key of the narration file (without the .mp3 extension already in the path). Take it from the enclosure URL of the matching feed item." }, { "name": "Range", "in": "header", "required": false, "schema": { "type": "string", "example": "bytes=0-1023" }, "description": "Optional RFC 7233 byte range. Presence triggers 206 Partial Content + Content-Range response headers." } ], "responses": { "200": { "description": "Full audio (no Range requested). Includes Accept-Ranges: bytes.", "content": { "audio/mpeg": { "schema": { "type": "string", "format": "binary" } } } }, "206": { "description": "Partial audio (Range request satisfied). Includes Content-Range: bytes N-M/TOTAL.", "content": { "audio/mpeg": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Unknown storage key, or key not ending in .mp3" }, "416": { "description": "Range not satisfiable" } } } } } }