{"openapi":"3.1.0","info":{"title":"essentials.sh API","version":"1.0.0","summary":"Generators for the small assets every site ships with.","description":"Free, unauthenticated, stateless REST API for the essentials.sh generators: QR codes (SVG), head meta tags, robots.txt with AI Content Signals, sitemap.xml, and llms.txt. Errors are structured JSON. An MCP server with the same tools lives at POST /mcp (see /.well-known/mcp/server-card.json).","contact":{"name":"essentials.sh","url":"https://github.com/cashmash-io/essentials"}},"servers":[{"url":"https://essentials.sh"}],"paths":{"/api/qr.svg":{"get":{"operationId":"generateQrSvg","summary":"Generate a QR code as SVG","description":"Encodes a URL into a QR code and returns an SVG document. https:// is assumed when the URL has no scheme.","parameters":[{"name":"url","in":"query","required":true,"description":"The URL to encode","schema":{"type":"string","examples":["https://example.com"]}},{"name":"ec","in":"query","required":false,"description":"Error correction level: L ~7%, M ~15% (default), Q ~25%, H ~30% of the code recoverable. Use H when overlaying a logo.","schema":{"type":"string","enum":["L","M","Q","H"],"default":"M"}}],"responses":{"200":{"description":"The QR code as an SVG document","content":{"image/svg+xml":{"schema":{"type":"string"}}}},"400":{"description":"Missing or invalid url parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/meta":{"post":{"operationId":"buildMetaTags","summary":"Build head meta tags","description":"Builds a complete HTML head metadata block: title, meta description, canonical link, Open Graph tags, and Twitter card tags. All attribute values are HTML-escaped. twitter:card is summary_large_image when an image is provided.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetaTagsRequest"}}}},"responses":{"200":{"description":"The generated tags","content":{"application/json":{"schema":{"type":"object","required":["meta_tags"],"properties":{"meta_tags":{"type":"string","description":"HTML to paste into "}}}}}},"400":{"description":"Missing title or description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/robots":{"post":{"operationId":"buildRobotsTxt","summary":"Build a robots.txt","description":"Builds a robots.txt with AI Content Signals (search / ai-input / ai-train), optional Disallow paths for all crawlers, and optional hard Disallow: / blocks for known AI-training crawlers (GPTBot, CCBot, Google-Extended, Applebot-Extended, Bytespider, meta-externalagent).","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RobotsRequest"}}}},"responses":{"200":{"description":"The generated robots.txt","content":{"application/json":{"schema":{"type":"object","required":["robots_txt"],"properties":{"robots_txt":{"type":"string"}}}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/sitemap":{"post":{"operationId":"buildSitemap","summary":"Build a sitemap.xml","description":"Builds a sitemap.xml from a site URL and a list of page paths or absolute URLs.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SitemapRequest"}}}},"responses":{"200":{"description":"The generated sitemap","content":{"application/json":{"schema":{"type":"object","required":["sitemap_xml"],"properties":{"sitemap_xml":{"type":"string"}}}}}},"400":{"description":"Missing siteUrl or paths","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/llms-txt":{"post":{"operationId":"buildLlmsTxt","summary":"Build an llms.txt","description":"Builds an llms.txt document per llmstxt.org: H1 name, blockquote summary, optional prose, and H2 sections of markdown links.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LlmsTxtRequest"}}}},"responses":{"200":{"description":"The generated llms.txt","content":{"application/json":{"schema":{"type":"object","required":["llms_txt"],"properties":{"llms_txt":{"type":"string"}}}}}},"400":{"description":"Missing siteName","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code","examples":["invalid_url","missing_field","not_found"]},"message":{"type":"string"},"hint":{"type":"string","description":"How to fix the request"}}}}},"MetaTagsRequest":{"type":"object","required":["title","description"],"properties":{"title":{"type":"string","description":"Page title (≤60 chars recommended)"},"description":{"type":"string","description":"Meta description (≤160 chars recommended)"},"url":{"type":"string","description":"Canonical URL"},"siteName":{"type":"string"},"image":{"type":"string","description":"Absolute URL of the social image (1200×630 recommended)"},"twitterHandle":{"type":"string"},"themeColor":{"type":"string"}}},"RobotsRequest":{"type":"object","properties":{"siteUrl":{"type":"string","description":"Absolute site URL for the Sitemap pointer"},"search":{"type":"boolean","default":true},"aiInput":{"type":"boolean","default":true},"aiTrain":{"type":"boolean","default":false},"disallow":{"type":"array","items":{"type":"string"},"description":"Paths disallowed for all crawlers"},"blockAiTrainers":{"type":"boolean","default":false}}},"SitemapRequest":{"type":"object","required":["siteUrl","paths"],"properties":{"siteUrl":{"type":"string"},"paths":{"type":"array","items":{"type":"string"},"description":"Page paths (e.g. \"/\", \"/about\") or absolute URLs"},"lastmod":{"type":"string","description":"ISO date (YYYY-MM-DD)"}}},"LlmsTxtRequest":{"type":"object","required":["siteName"],"properties":{"siteName":{"type":"string"},"summary":{"type":"string","description":"One-line summary"},"details":{"type":"string"},"sections":{"type":"array","items":{"type":"object","required":["title","links"],"properties":{"title":{"type":"string"},"links":{"type":"array","items":{"type":"object","required":["title","url"],"properties":{"title":{"type":"string"},"url":{"type":"string"},"note":{"type":"string"}}}}}}}}}}}}