{"openapi":"3.1.0","info":{"title":"Readmint API","version":"1.0.0","description":"Any web page as clean Markdown, for LLMs and AI agents. Send a URL, get back its main content as Markdown, text or HTML, without menus, ads or cookie banners. Pages built by JavaScript are loaded in a real browser when they need it. Link previews and site maps too, from one REST call or MCP tool.","contact":{"email":"support@readmint.plxi.us","url":"https://readmint.plxi.us/contact"},"termsOfService":"https://readmint.plxi.us/terms"},"externalDocs":{"url":"https://readmint.plxi.us/docs"},"servers":[{"url":"https://api-readmint.plxi.us"}],"security":[{"apiKey":[]}],"paths":{"/v1/read":{"post":{"operationId":"read","summary":"Read a web page","description":"Read a public web page and get its main content as clean Markdown (default), plain text or HTML: navigation, footers, ads, cookie banners and pop-ups are left out, tables become Markdown tables, and links and images point to full URLs. Pages built by JavaScript are loaded in a real browser automatically. Send the page in `url`. Optional: `format` (`markdown`, `text`, `html`), `selector` (a CSS selector to read one element instead of the main content), `include` (`links`, `images`, `metadata` for lists of links and images and the page's Open Graph, JSON-LD and other metadata), `images: false` to leave images out of the content, `max_chars` (default 100,000; longer content is cut and `truncated` is true) and `max_age` (seconds a cached copy may be, default 3600; 0 reads it fresh). Returns `content`, `title`, `byline`, `published`, `lang`, `word_count`, `final_url` and `status`. Pages behind a bot check, a login or an HTTP error are refused with a 4xx error and not charged.","x-credits":1,"externalDocs":{"url":"https://readmint.plxi.us/docs#op-read"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","minLength":10,"maxLength":2048,"pattern":"^[Hh][Tt][Tt][Pp][Ss]?://\\S+$","description":"The page to read: a public http or https URL."},"format":{"enum":["markdown","text","html"],"default":"markdown","description":"What `content` is: Markdown (headings, lists, tables, links), plain text with paragraph breaks, or the cleaned HTML."},"render":{"enum":["auto","always","never"],"default":"auto","description":"`auto` fetches the page directly and loads it in a real browser only when it has to (it's built by JavaScript, or the site turns plain clients away). `always` loads it in the browser; `never` never does."},"selector":{"type":"string","minLength":1,"maxLength":400,"description":"A CSS selector: read only the first element it matches, instead of finding the main content."},"wait_for_selector":{"type":"string","minLength":1,"maxLength":400,"description":"When the page is loaded in the browser, wait up to 30 seconds for this CSS selector to appear first."},"images":{"type":"boolean","default":true,"description":"Keep images in the content (`![alt](url)` in Markdown). false leaves them out."},"include":{"type":"array","items":{"enum":["links","images","metadata"]},"uniqueItems":true,"maxItems":3,"description":"Extra lists in the result: `links` (each link in the content, with its text), `images` (each image, with its alt text) and `metadata` (description, canonical URL, Open Graph, Twitter, icons, feeds and JSON-LD)."},"max_chars":{"type":"integer","minimum":1000,"maximum":1000000,"default":100000,"description":"The most characters of content to return; past it the content is cut and `truncated` is true."},"max_age":{"type":"integer","minimum":0,"maximum":86400,"default":3600,"description":"How old, in seconds, a cached copy of this read may be. 0 reads the page fresh."}},"required":["url"],"additionalProperties":false},"example":{"url":"https://example.com/"}}}},"responses":{"200":{"description":"Success. The body includes the credits charged.","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"The URL asked for."},"final_url":{"type":["string","null"],"description":"Where the page ended up after redirects."},"status":{"type":["integer","null"],"description":"The page's HTTP status."},"title":{"type":["string","null"]},"byline":{"type":["string","null"],"description":"The author, when the page names one."},"excerpt":{"type":["string","null"],"description":"A short summary: the page's description or first paragraph."},"site_name":{"type":["string","null"]},"published":{"type":["string","null"],"description":"When it was published, as the page gives it."},"lang":{"type":["string","null"]},"format":{"enum":["markdown","text","html"]},"content":{"type":"string","description":"The main content, in `format`."},"word_count":{"type":"integer"},"truncated":{"type":"boolean","description":"The content was cut at `max_chars`."},"rendered":{"type":"boolean","description":"The page was loaded in a real browser."},"article":{"type":"boolean","description":"The page read as an article; otherwise the content is the page without its navigation, header and footer."},"fetched_at":{"type":"string","description":"When the page was read (a cached copy keeps its time)."},"links":{"type":"array","items":{"type":"object","properties":{"href":{"type":"string"},"text":{"type":"string"}},"required":["href","text"]}},"images":{"type":"array","items":{"type":"object","properties":{"src":{"type":"string"},"alt":{"type":"string"},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]}},"required":["src","alt"]}},"metadata":{"type":"object"},"credits":{"type":"integer","description":"Credits this call was charged."}},"required":["url","final_url","status","title","format","content","word_count","truncated","rendered","fetched_at","credits"]},"example":{"url":"https://example.com/","final_url":"https://example.com/","status":200,"title":"Example Domain","byline":null,"excerpt":"This domain is for use in documentation examples without needing permission. This is not a service; avoid relying on it for testing and monitoring purposes.","site_name":null,"published":null,"lang":"en","format":"markdown","content":"This domain is for use in documentation examples without needing permission. This is not a service; avoid relying on it for testing and monitoring purposes.\n\n…\n\n[Learn more](https://iana.org/help/example-domains)","word_count":133,"truncated":false,"rendered":true,"article":true,"fetched_at":"2026-10-31T13:20:00Z","credits":1}}}},"400":{"description":"Invalid JSON or input. Not charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit, concurrency limit or monthly quota reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/preview":{"post":{"operationId":"preview","summary":"Preview a link","description":"Get what a link preview card needs for a public web page: `title`, `description`, `site_name`, `type`, `image` (`url`, `width`, `height`, `alt`), `favicon` and every icon, `theme_color`, `author`, `published`, `lang`, `canonical`, feeds, and `oembed` (the provider's embed answer, for YouTube, Vimeo, X, Spotify and other oEmbed sites). Open Graph tags come first, then Twitter's, then the page's own title and description. Send the page in `url`. Optional: `render: \"never\"` to skip loading pages built by JavaScript in a browser, and `max_age` (seconds a cached preview may be, default 86,400; 0 fetches it fresh). Refused pages (bot checks, HTTP errors, non-HTML) are a 4xx error and not charged.","x-credits":1,"externalDocs":{"url":"https://readmint.plxi.us/docs#op-preview"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","minLength":10,"maxLength":2048,"pattern":"^[Hh][Tt][Tt][Pp][Ss]?://\\S+$","description":"The page to preview: a public http or https URL."},"render":{"enum":["auto","never"],"default":"auto","description":"`auto` loads the page in a real browser when a plain fetch finds no title (pages built by JavaScript, sites that turn plain clients away). `never` doesn't."},"max_age":{"type":"integer","minimum":0,"maximum":604800,"default":86400,"description":"How old, in seconds, a cached preview may be. 0 fetches it fresh."}},"required":["url"],"additionalProperties":false},"example":{"url":"https://example.com/"}}}},"responses":{"200":{"description":"Success. The body includes the credits charged.","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"final_url":{"type":["string","null"]},"status":{"type":["integer","null"]},"title":{"type":["string","null"]},"description":{"type":["string","null"]},"site_name":{"type":["string","null"]},"type":{"type":["string","null"],"description":"Open Graph type: article, website, video.other…"},"image":{"type":["object","null"],"properties":{"url":{"type":"string"},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"alt":{"type":["string","null"]}}},"favicon":{"type":["string","null"]},"icons":{"type":"array","items":{"type":"object"}},"theme_color":{"type":["string","null"]},"author":{"type":["string","null"]},"published":{"type":["string","null"]},"lang":{"type":["string","null"]},"canonical":{"type":["string","null"]},"feeds":{"type":"array","items":{"type":"object"}},"oembed_url":{"type":["string","null"]},"oembed":{"type":["object","null"],"description":"The page's oEmbed answer: type, title, author_name, provider_name, thumbnail_url, html, width, height."},"content_type":{"type":"string"},"rendered":{"type":"boolean"},"fetched_at":{"type":"string"},"credits":{"type":"integer","description":"Credits this call was charged."}},"required":["url","final_url","title","description","image","favicon","rendered","credits"]},"example":{"url":"https://example.com/","final_url":"https://example.com/","status":200,"title":"Example Domain","description":null,"site_name":"example.com","type":null,"image":null,"favicon":"https://example.com/favicon.ico","icons":[],"theme_color":null,"author":null,"published":null,"lang":"en","canonical":null,"feeds":[],"oembed_url":null,"oembed":null,"content_type":"text/html","rendered":false,"fetched_at":"2026-10-31T13:20:00Z","credits":1}}}},"400":{"description":"Invalid JSON or input. Not charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit, concurrency limit or monthly quota reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/map":{"post":{"operationId":"map","summary":"Map a site's URLs","description":"List the pages of a website, to choose which to read: the URLs in its sitemaps (found through robots.txt or /sitemap.xml, sitemap indexes and .gz files included) and the links on the start page, same site only, without duplicates or #fragments. Send the start page in `url`. Optional: `search` (keep only URLs containing this text), `max_urls` (1 to 5,000, default 1,000; `truncated` says there were more), `sitemap: false` or `links: false` to skip either source, and `include_subdomains: true` to keep other hosts under the same domain. Returns `urls` (the start URL first), `count`, how many came `from_sitemap` and `from_page`, and the `sitemaps` read.","x-credits":1,"externalDocs":{"url":"https://readmint.plxi.us/docs#op-map"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","minLength":10,"maxLength":2048,"pattern":"^[Hh][Tt][Tt][Pp][Ss]?://\\S+$","description":"The site's start page: a public http or https URL."},"search":{"type":"string","minLength":1,"maxLength":200,"description":"Keep only URLs that contain this text (any case), e.g. \"/blog/\" or \"pricing\"."},"max_urls":{"type":"integer","minimum":1,"maximum":5000,"default":1000,"description":"The most URLs to return."},"sitemap":{"type":"boolean","default":true,"description":"Read the site's sitemaps."},"links":{"type":"boolean","default":true,"description":"Read the links on the start page."},"include_subdomains":{"type":"boolean","default":false,"description":"Also keep URLs on other hosts under the same domain (docs.example.com for example.com). www. is always the same site."}},"required":["url"],"additionalProperties":false},"example":{"url":"https://example.com/","max_urls":100}}}},"responses":{"200":{"description":"Success. The body includes the credits charged.","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"urls":{"type":"array","items":{"type":"string"}},"count":{"type":"integer"},"from_sitemap":{"type":"integer"},"from_page":{"type":"integer"},"sitemaps":{"type":"array","items":{"type":"string"},"description":"The sitemap files read."},"truncated":{"type":"boolean","description":"There were more than `max_urls`."},"credits":{"type":"integer","description":"Credits this call was charged."}},"required":["url","urls","count","from_sitemap","from_page","sitemaps","truncated","credits"]},"example":{"url":"https://example.com/","urls":["https://example.com/"],"count":1,"from_sitemap":0,"from_page":0,"sitemaps":["https://example.com/sitemap.xml"],"truncated":false,"credits":1}}}},"400":{"description":"Invalid JSON or input. Not charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit, concurrency limit or monthly quota reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/usage":{"get":{"operationId":"getUsage","summary":"Usage and limits for the current billing period.","responses":{"200":{"description":"Usage summary.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"X-API-Key"}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Stable error code, listed in the API reference."},"message":{"type":"string"},"reset_at":{"type":"string","format":"date-time"}}}}}}