{"openapi":"3.0.3","info":{"title":"SEO Audit API","version":"1.0.0","description":"Audit the HTML of a single public page and get back everything an SEO review needs, without a headless browser.\n\n**What one call returns:** status and timing for the fetch, the final URL after redirects, title and meta description with length warnings, canonical, robots directives, lang, charset, viewport, H1-H6 counts with the first three headings of each level, image and alt-text counts, internal vs external link counts, word count, text-to-HTML ratio, Flesch reading ease and grade level, Open Graph and Twitter card completeness, JSON-LD types, hreflang entries, HTTPS, response compression, and a 0-100 score built from 14 weighted checks whose weights sum to exactly 100.\n\n**Other endpoints:** head metadata only, every anchor with rel attributes, keyword frequency with density, readability on its own, robots.txt parsing and sitemap.xml parsing. POST /v1/text runs the readability and keyword analysis on text you already have, with no network call.\n\n**Honest scope:** this API audits a single public page's HTML. It does not crawl a whole site, does not render JavaScript (so client-side injected tags are invisible to it), and does not measure Core Web Vitals, Lighthouse metrics or real-user performance. Word and syllable statistics target Latin-script languages; CJK word segmentation is not implemented.\n\n**Built for:** SEO agencies doing first-pass page reviews, SaaS products embedding a site audit feature, growth marketers checking metadata before a launch.","termsOfService":"https://example.com/terms","contact":{"name":"Ayam Labs","url":"https://github.com/ayam04","email":"ayamullahkhan04@gmail.com"}},"servers":[{"url":"https://seo-audit.ayamk.in","description":"Direct origin"},{"url":"https://rapidapi.com","description":"RapidAPI marketplace"}],"tags":[{"name":"Audit","description":"Full weighted on-page audit of one URL"},{"name":"Metadata","description":"Head tags: title, description, canonical, social cards, structured data"},{"name":"Links","description":"Anchor extraction and internal/external classification"},{"name":"Content","description":"Keyword frequency and readability for a URL or raw text"},{"name":"Crawling","description":"robots.txt and sitemap.xml inspection"}],"x-provider":"Ayam Labs","components":{"schemas":{"AuditResponse":{"type":"object","properties":{"requestedUrl":{"type":"string","description":"Normalised URL that was requested.","example":"https://acme.example/pricing"},"finalUrl":{"type":"string","description":"URL of the response actually parsed, after redirects.","example":"https://acme.example/pricing/"},"redirected":{"type":"boolean","description":"True when the final URL differs from the requested URL.","example":false},"redirectChainLength":{"type":"integer","description":"0 for a direct hit, 1 when at least one redirect was followed. The runtime exposes only the final URL, so a multi hop chain is reported as 1.","example":0},"statusCode":{"type":"integer","description":"HTTP status of the final response. Pages are still parsed when the origin returns 4xx/5xx.","example":200},"https":{"type":"boolean","description":"Whether the page was served over HTTPS.","example":true},"contentType":{"type":"string","nullable":true,"description":"Content-Type reported by the origin.","example":"text/html; charset=utf-8"},"contentEncoding":{"type":"string","nullable":true,"description":"Content-Encoding reported by the origin, when present.","example":"gzip"},"bodyBytes":{"type":"integer","description":"Bytes read from the body, after decompression.","example":48213},"truncated":{"type":"boolean","description":"True when the page exceeded the 2 MB audit cap and was cut off.","example":false},"timings":{"$ref":"#/components/schemas/AuditTimings"},"page":{"$ref":"#/components/schemas/AuditPage"},"headings":{"$ref":"#/components/schemas/AuditHeadings"},"images":{"$ref":"#/components/schemas/AuditImages"},"links":{"$ref":"#/components/schemas/AuditLinks"},"content":{"$ref":"#/components/schemas/AuditContent"},"readability":{"$ref":"#/components/schemas/ReadabilityMetrics"},"openGraph":{"$ref":"#/components/schemas/OpenGraph"},"twitter":{"$ref":"#/components/schemas/TwitterCard"},"jsonLd":{"$ref":"#/components/schemas/JsonLdAudit"},"hreflang":{"type":"array","items":{"$ref":"#/components/schemas/HreflangEntry"},"maxItems":200,"description":"link rel=alternate hreflang entries, capped at 200."},"score":{"$ref":"#/components/schemas/AuditScore"}},"required":["requestedUrl","finalUrl","redirected","redirectChainLength","statusCode","https","contentType","contentEncoding","bodyBytes","truncated","timings","page","headings","images","links","content","readability","openGraph","twitter","jsonLd","hreflang","score"]},"AuditTimings":{"type":"object","properties":{"fetchMs":{"type":"integer","description":"Time to receive response headers.","example":214},"parseMs":{"type":"integer","description":"Time spent parsing and scoring the body.","example":31},"totalMs":{"type":"integer","description":"End to end handler time.","example":249}},"required":["fetchMs","parseMs","totalMs"]},"AuditPage":{"type":"object","properties":{"title":{"type":"string","nullable":true,"example":"Pricing - Acme Analytics"},"titleLength":{"type":"integer","description":"Characters in the normalised title, 0 when absent.","example":27},"titleTooLong":{"type":"boolean","description":"True when the title exceeds 60 characters.","example":false},"metaDescription":{"type":"string","nullable":true,"example":"Simple usage based pricing for product teams."},"metaDescriptionLength":{"type":"integer","example":47},"metaDescriptionTooLong":{"type":"boolean","description":"True when the description exceeds 160 characters.","example":false},"canonical":{"type":"string","nullable":true,"example":"https://acme.example/pricing"},"robots":{"$ref":"#/components/schemas/RobotsMeta"},"lang":{"type":"string","nullable":true,"example":"en"},"charset":{"type":"string","nullable":true,"description":"Declared character encoding, from meta charset or Content-Type.","example":"utf-8"},"viewport":{"type":"string","nullable":true,"description":"Raw viewport meta content.","example":"width=device-width, initial-scale=1"},"themeColor":{"type":"string","nullable":true,"example":"#0f172a"},"metaTagCount":{"type":"integer"},"linkTagCount":{"type":"integer"}},"required":["title","titleLength","titleTooLong","metaDescription","metaDescriptionLength","metaDescriptionTooLong","canonical","robots","lang","charset","viewport","themeColor","metaTagCount","linkTagCount"]},"RobotsMeta":{"type":"object","properties":{"raw":{"type":"string","nullable":true,"description":"Raw content of the robots meta tag.","example":"index, follow, max-snippet:-1"},"index":{"type":"boolean","description":"False when a noindex/none directive is present.","example":true},"follow":{"type":"boolean","description":"False when a nofollow/none directive is present.","example":true},"directives":{"type":"array","items":{"type":"string"},"description":"Lowercased directives as written.","example":["index","follow","max-snippet:-1"]}},"required":["raw","index","follow","directives"]},"AuditHeadings":{"type":"object","properties":{"counts":{"$ref":"#/components/schemas/HeadingCounts"},"total":{"type":"integer","description":"Total h1-h6 elements.","example":16},"texts":{"$ref":"#/components/schemas/HeadingTexts"}},"required":["counts","total","texts"]},"HeadingCounts":{"type":"object","properties":{"h1":{"type":"integer","example":1},"h2":{"type":"integer","example":6},"h3":{"type":"integer","example":9},"h4":{"type":"integer","example":0},"h5":{"type":"integer","example":0},"h6":{"type":"integer","example":0}},"required":["h1","h2","h3","h4","h5","h6"]},"HeadingTexts":{"type":"object","properties":{"h1":{"type":"array","items":{"type":"string"},"maxItems":3,"example":["Acme Analytics"]},"h2":{"type":"array","items":{"type":"string"},"maxItems":3,"example":["Why teams switch","How pricing works","FAQ"]},"h3":{"type":"array","items":{"type":"string"},"maxItems":3,"example":["Built for product teams"]},"h4":{"type":"array","items":{"type":"string"},"maxItems":3,"example":[]},"h5":{"type":"array","items":{"type":"string"},"maxItems":3,"example":[]},"h6":{"type":"array","items":{"type":"string"},"maxItems":3,"example":[]}},"required":["h1","h2","h3","h4","h5","h6"]},"AuditImages":{"type":"object","properties":{"total":{"type":"integer","example":12},"missingAlt":{"type":"integer","description":"Images with no alt attribute at all.","example":2},"emptyAlt":{"type":"integer","description":"Images with an empty alt attribute (treated as decorative).","example":3},"missingAltPercent":{"type":"number","example":16.7}},"required":["total","missingAlt","emptyAlt","missingAltPercent"]},"AuditLinks":{"type":"object","properties":{"total":{"type":"integer","example":64},"internal":{"type":"integer","example":41},"external":{"type":"integer","example":19},"other":{"type":"integer","description":"mailto:, tel:, javascript: and other non-http hrefs.","example":4},"nofollow":{"type":"integer","example":5},"sponsored":{"type":"integer","example":0},"ugc":{"type":"integer","example":0},"emptyAnchorText":{"type":"integer","description":"Anchors whose visible text is empty.","example":3}},"required":["total","internal","external","other","nofollow","sponsored","ugc","emptyAnchorText"]},"AuditContent":{"type":"object","properties":{"wordCount":{"type":"integer","example":812},"sentenceCount":{"type":"integer","example":48},"paragraphCount":{"type":"integer","example":11},"htmlBytes":{"type":"integer","description":"UTF-8 bytes of the HTML body.","example":48213},"textBytes":{"type":"integer","description":"UTF-8 bytes of the visible text.","example":5120},"textToHtmlRatioPercent":{"type":"number","description":"Visible text bytes as a percentage of HTML bytes.","example":10.6}},"required":["wordCount","sentenceCount","paragraphCount","htmlBytes","textBytes","textToHtmlRatioPercent"]},"ReadabilityMetrics":{"type":"object","properties":{"wordCount":{"type":"integer","description":"Words found in the analysed text.","example":812},"sentenceCount":{"type":"integer","description":"Sentences found. Line breaks always end a sentence.","example":48},"paragraphCount":{"type":"integer","description":"Paragraphs: block elements for HTML, blank-line blocks for raw text.","example":11},"syllableCount":{"type":"integer","description":"Estimated syllables across all words (heuristic vowel-group count).","example":1310},"complexWordCount":{"type":"integer","description":"Words with three or more syllables that do not end in -ed, -es, -ing or -ly (Gunning-Fog input).","example":121},"charCount":{"type":"integer","description":"Characters in the analysed text.","example":4620},"avgWordsPerSentence":{"type":"number","description":"Average words per sentence.","example":16.92},"avgSyllablesPerWord":{"type":"number","description":"Average syllables per word.","example":1.61},"fleschReadingEase":{"type":"number","description":"Flesch Reading Ease, clamped to 0-100. Higher is easier to read.","example":62.4},"fleschKincaidGrade":{"type":"number","description":"Flesch-Kincaid grade level, floored at 0. Approximate US school grade.","example":8.2},"gunningFogIndex":{"type":"number","description":"Gunning Fog index, floored at 0. Years of formal education needed.","example":10.1},"readingLevel":{"type":"string","enum":["very easy","easy","fairly easy","standard","fairly difficult","difficult","very difficult","insufficient text"],"description":"Flesch reading-ease band.","example":"standard"},"longestSentence":{"$ref":"#/components/schemas/LongestSentence"},"passiveVoiceHints":{"type":"integer","description":"Sentences matching a be-verb plus participle pattern. A hint, not grammatical analysis.","example":4},"passiveVoiceRatePer100Sentences":{"type":"number","description":"Passive hints per 100 sentences.","example":8.3}},"required":["wordCount","sentenceCount","paragraphCount","syllableCount","complexWordCount","charCount","avgWordsPerSentence","avgSyllablesPerWord","fleschReadingEase","fleschKincaidGrade","gunningFogIndex","readingLevel","longestSentence","passiveVoiceHints","passiveVoiceRatePer100Sentences"]},"LongestSentence":{"type":"object","properties":{"text":{"type":"string","description":"The longest sentence, truncated to 300 characters.","example":"The shop opened in 1998 and has sold..."},"wordCount":{"type":"integer","description":"Words in that sentence.","example":41},"index":{"type":"integer","description":"Zero based position of the sentence in the document.","example":12}},"required":["text","wordCount","index"]},"OpenGraph":{"type":"object","properties":{"title":{"type":"string","nullable":true,"example":"Acme Analytics - product analytics without the setup"},"description":{"type":"string","nullable":true,"example":"Track activation, retention and revenue in one place."},"image":{"type":"string","nullable":true,"example":"https://acme.example/og.png"},"imageAlt":{"type":"string","nullable":true,"example":"Acme dashboard screenshot"},"url":{"type":"string","nullable":true,"example":"https://acme.example/"},"type":{"type":"string","nullable":true,"example":"website"},"siteName":{"type":"string","nullable":true,"example":"Acme Analytics"},"locale":{"type":"string","nullable":true,"example":"en_US"},"missing":{"type":"array","items":{"type":"string"},"description":"Recommended og: fields that are absent.","example":["og:image"]},"complete":{"type":"boolean","description":"True when og:title, og:description, og:image, og:url and og:type are all present.","example":false}},"required":["title","description","image","imageAlt","url","type","siteName","locale","missing","complete"]},"TwitterCard":{"type":"object","properties":{"card":{"type":"string","nullable":true,"example":"summary_large_image"},"title":{"type":"string","nullable":true,"example":"Acme Analytics"},"description":{"type":"string","nullable":true,"example":"Track activation, retention and revenue in one place."},"image":{"type":"string","nullable":true,"example":"https://acme.example/twitter.png"},"site":{"type":"string","nullable":true,"example":"@acme"},"creator":{"type":"string","nullable":true,"example":"@acmehq"},"missing":{"type":"array","items":{"type":"string"},"description":"Recommended twitter: fields that are absent.","example":["twitter:image"]},"complete":{"type":"boolean","description":"True when twitter:card, twitter:title, twitter:description and twitter:image are all present.","example":false}},"required":["card","title","description","image","site","creator","missing","complete"]},"JsonLdAudit":{"type":"object","properties":{"blocks":{"type":"integer","description":"Number of script[type=application/ld+json] blocks found.","example":2},"validBlocks":{"type":"integer","description":"Blocks that parsed as JSON.","example":2},"invalidBlocks":{"type":"integer","description":"Blocks that did not parse.","example":0},"types":{"type":"array","items":{"type":"string"},"description":"Distinct schema.org types found across all blocks, capped at 20.","example":["Article","BreadcrumbList"]},"items":{"type":"array","items":{"$ref":"#/components/schemas/JsonLdBlock"},"maxItems":20,"description":"Per block details, capped at 20 blocks."}},"required":["blocks","validBlocks","invalidBlocks","types","items"]},"JsonLdBlock":{"type":"object","properties":{"valid":{"type":"boolean","description":"Whether the block parsed as JSON.","example":true},"types":{"type":"array","items":{"type":"string"},"description":"Every @type found, including inside @graph.","example":["Article","BreadcrumbList"]},"keys":{"type":"array","items":{"type":"string"},"description":"Top level property names, @context excluded, capped at 25.","example":["@type","headline","author"]},"summary":{"$ref":"#/components/schemas/JsonLdSummary"},"error":{"type":"string","nullable":true,"description":"Why the block could not be parsed, when valid is false.","example":null}},"required":["valid","types","keys","summary","error"]},"JsonLdSummary":{"type":"object","properties":{"type":{"type":"string","nullable":true,"example":"Product"},"name":{"type":"string","nullable":true,"example":"Acme Pro plan"},"headline":{"type":"string","nullable":true,"example":null},"description":{"type":"string","nullable":true,"example":"Everything in Starter, plus SSO."},"url":{"type":"string","nullable":true,"example":"https://acme.example/pro"},"author":{"type":"string","nullable":true,"example":null},"datePublished":{"type":"string","nullable":true,"example":null}},"required":["type","name","headline","description","url","author","datePublished"]},"HreflangEntry":{"type":"object","properties":{"hreflang":{"type":"string","example":"de-DE"},"href":{"type":"string","example":"https://acme.example/de/"}},"required":["hreflang","href"]},"AuditScore":{"type":"object","properties":{"value":{"type":"integer","minimum":0,"maximum":100,"description":"Weighted on-page score from 0 to 100.","example":78},"grade":{"type":"string","enum":["A","B","C","D","F"],"description":"Letter grade derived from value: A >= 90, B >= 80, C >= 70, D >= 60, F below.","example":"C"},"passed":{"type":"integer","description":"Number of checks that passed.","example":9},"warned":{"type":"integer","description":"Number of checks that produced a warning.","example":3},"failed":{"type":"integer","description":"Number of checks that failed.","example":2},"checks":{"type":"array","items":{"$ref":"#/components/schemas/AuditCheck"},"description":"Every check with its weight, status and message. Weights always sum to 100."}},"required":["value","grade","passed","warned","failed","checks"]},"AuditCheck":{"type":"object","properties":{"id":{"type":"string","description":"Stable check identifier, safe to switch on.","example":"title"},"label":{"type":"string","description":"Human readable check name.","example":"Title tag"},"status":{"type":"string","enum":["pass","warn","fail"],"description":"Outcome of one weighted check: pass earns the full weight, warn half (rounded up), fail nothing.","example":"pass"},"weight":{"type":"integer","description":"Maximum points this check can contribute. All weights sum to 100.","example":15},"points":{"type":"integer","description":"Points actually earned for this page.","example":15},"message":{"type":"string","description":"What was found, in one sentence.","example":"Title is 42 characters, inside the 15-60 range."}},"required":["id","label","status","weight","points","message"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"INVALID_INPUT","description":"Stable machine-readable error code."},"message":{"type":"string","example":"Request validation failed","description":"Human-readable explanation."},"details":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}}},{"type":"object","additionalProperties":{"nullable":true}}],"description":"Optional structured details (usually field-level validation issues)."},"hint":{"type":"string","example":"Pass the email address in the \"email\" query parameter."}},"required":["code","message"]},"requestId":{"type":"string","example":"8f14e45f-ceea-467f-a8e7-9b5e4f0e2a31"},"timestamp":{"type":"string","example":"2026-11-21T10:15:30.000Z"}},"required":["error","requestId","timestamp"]},"MetaResponse":{"type":"object","properties":{"requestedUrl":{"type":"string","example":"https://acme.example/pricing"},"finalUrl":{"type":"string","example":"https://acme.example/pricing"},"statusCode":{"type":"integer","example":200},"https":{"type":"boolean","example":true},"contentType":{"type":"string","nullable":true,"example":"text/html; charset=utf-8"},"bodyBytes":{"type":"integer","example":48213},"title":{"type":"string","nullable":true,"example":"Pricing - Acme Analytics"},"titleLength":{"type":"integer","example":27},"metaDescription":{"type":"string","nullable":true,"example":"Simple usage based pricing for product teams."},"metaDescriptionLength":{"type":"integer","example":47},"canonical":{"type":"string","nullable":true,"example":"https://acme.example/pricing"},"robots":{"$ref":"#/components/schemas/RobotsMeta"},"lang":{"type":"string","nullable":true,"example":"en"},"charset":{"type":"string","nullable":true,"example":"utf-8"},"viewport":{"type":"string","nullable":true,"example":"width=device-width, initial-scale=1"},"themeColor":{"type":"string","nullable":true,"example":"#0f172a"},"openGraph":{"$ref":"#/components/schemas/OpenGraph"},"twitter":{"$ref":"#/components/schemas/TwitterCard"},"jsonLd":{"$ref":"#/components/schemas/JsonLdAudit"},"favicons":{"type":"array","items":{"$ref":"#/components/schemas/Favicon"},"maxItems":20,"description":"icon, shortcut icon and apple-touch-icon links, capped at 20."},"hreflang":{"type":"array","items":{"$ref":"#/components/schemas/HreflangEntry"},"maxItems":200},"metaTagCount":{"type":"integer","example":21},"linkTagCount":{"type":"integer","example":14},"durationMs":{"type":"integer","example":231}},"required":["requestedUrl","finalUrl","statusCode","https","contentType","bodyBytes","title","titleLength","metaDescription","metaDescriptionLength","canonical","robots","lang","charset","viewport","themeColor","openGraph","twitter","jsonLd","favicons","hreflang","metaTagCount","linkTagCount","durationMs"]},"Favicon":{"type":"object","properties":{"href":{"type":"string","description":"href exactly as written.","example":"/favicon-32.png"},"url":{"type":"string","nullable":true,"description":"Resolved absolute URL.","example":"https://acme.example/favicon-32.png"},"rel":{"type":"string","nullable":true,"example":"icon"},"sizes":{"type":"string","nullable":true,"example":"32x32"},"type":{"type":"string","nullable":true,"example":"image/png"}},"required":["href","url","rel","sizes","type"]},"LinksResponse":{"type":"object","properties":{"requestedUrl":{"type":"string","example":"https://acme.example/"},"finalUrl":{"type":"string","example":"https://acme.example/"},"statusCode":{"type":"integer","example":200},"siteHost":{"type":"string","description":"Hostname of the audited page.","example":"acme.example"},"registrableDomain":{"type":"string","description":"Registrable domain used for internal/external classification.","example":"acme.example"},"total":{"type":"integer","description":"Every anchor counted, including those beyond the list cap.","example":64},"internal":{"type":"integer","example":41},"external":{"type":"integer","example":19},"other":{"type":"integer","example":4},"nofollow":{"type":"integer","example":5},"sponsored":{"type":"integer","example":0},"ugc":{"type":"integer","example":0},"emptyAnchorText":{"type":"integer","example":3},"returned":{"type":"integer","description":"Number of entries in the links array.","example":64},"truncated":{"type":"boolean","description":"True when the page had more than 500 anchors.","example":false},"relCounts":{"$ref":"#/components/schemas/RelCounts"},"links":{"type":"array","items":{"$ref":"#/components/schemas/LinkEntry"},"maxItems":500},"durationMs":{"type":"integer","example":189}},"required":["requestedUrl","finalUrl","statusCode","siteHost","registrableDomain","total","internal","external","other","nofollow","sponsored","ugc","emptyAnchorText","returned","truncated","relCounts","links","durationMs"]},"RelCounts":{"type":"object","properties":{"nofollow":{"type":"integer","example":5},"sponsored":{"type":"integer","example":0},"ugc":{"type":"integer","example":0},"noopener":{"type":"integer","example":12},"noreferrer":{"type":"integer","example":3},"other":{"type":"integer","description":"Links with a rel attribute not covered above.","example":8}},"required":["nofollow","sponsored","ugc","noopener","noreferrer","other"]},"LinkEntry":{"type":"object","properties":{"href":{"type":"string","description":"href exactly as written in the document, trimmed.","example":"/pricing"},"url":{"type":"string","nullable":true,"description":"Absolute URL after resolution, null for non-http schemes.","example":"https://acme.example/pricing"},"type":{"type":"string","enum":["internal","external","other"],"description":"internal = same registrable domain, external = different registrable domain, other = mailto/tel/javascript/non-http.","example":"internal"},"text":{"type":"string","description":"Visible anchor text, whitespace collapsed, capped at 300 characters.","example":"See pricing"},"rel":{"type":"array","items":{"type":"string"},"example":["nofollow","noopener"]},"target":{"type":"string","nullable":true,"example":"_blank"},"nofollow":{"type":"boolean","example":false}},"required":["href","url","type","text","rel","target","nofollow"]},"KeywordsResponse":{"type":"object","properties":{"source":{"type":"string","enum":["url","text"],"description":"Where the analysed text came from.","example":"url"},"url":{"type":"string","nullable":true,"description":"Requested URL when source is url.","example":"https://acme.example/blog/post"},"finalUrl":{"type":"string","nullable":true,"example":"https://acme.example/blog/post"},"statusCode":{"type":"integer","nullable":true,"description":"HTTP status of the fetched page, null for raw text.","example":200},"htmlBytes":{"type":"integer","nullable":true,"description":"Bytes of HTML read, null for raw text.","example":48213},"truncated":{"type":"boolean","description":"True when the page hit the 2 MB cap or the text hit the 100,000 character cap.","example":false},"analysis":{"$ref":"#/components/schemas/KeywordAnalysis"},"durationMs":{"type":"integer","example":204}},"required":["source","url","finalUrl","statusCode","htmlBytes","truncated","analysis","durationMs"]},"KeywordAnalysis":{"type":"object","properties":{"totalWords":{"type":"integer","description":"All word tokens, including stopwords and short words.","example":812},"uniqueWords":{"type":"integer","description":"Distinct tokens after lowercasing.","example":301},"stopwordCount":{"type":"integer","description":"Tokens removed as stopwords or site-chrome words.","example":344},"stopwordRatePercent":{"type":"number","description":"Share of tokens that were stopwords.","example":42.4},"termCount":{"type":"integer","description":"Distinct scored terms (unigrams plus bigrams) before the limit is applied.","example":214},"unigramCount":{"type":"integer","description":"Distinct single word terms.","example":158},"bigramCount":{"type":"integer","description":"Distinct two word phrases.","example":56},"terms":{"type":"array","items":{"$ref":"#/components/schemas/KeywordTerm"},"maxItems":100,"description":"Ranked terms, capped by the limit parameter."},"densityTop10":{"type":"array","items":{"$ref":"#/components/schemas/KeywordDensity"},"maxItems":10,"description":"Density percentages for the top ten terms."}},"required":["totalWords","uniqueWords","stopwordCount","stopwordRatePercent","termCount","unigramCount","bigramCount","terms","densityTop10"]},"KeywordTerm":{"type":"object","properties":{"term":{"type":"string","description":"Lowercased term. One or two words.","example":"keyword research"},"wordCount":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[2]}],"description":"1 for a single word, 2 for a two word phrase.","example":2},"count":{"type":"integer","description":"Occurrences in the analysed text.","example":7},"densityPercent":{"type":"number","description":"Occurrences as a percentage of all words.","example":0.86},"score":{"type":"number","description":"count x IDF-style weight. Used only for ranking inside this response.","example":36.4},"importance":{"type":"integer","minimum":0,"maximum":100,"description":"Score relative to the top term, 0-100.","example":100}},"required":["term","wordCount","count","densityPercent","score","importance"]},"KeywordDensity":{"type":"object","properties":{"term":{"type":"string","example":"keyword research"},"count":{"type":"integer","example":7},"densityPercent":{"type":"number","example":0.86}},"required":["term","count","densityPercent"]},"ReadabilityResponse":{"type":"object","properties":{"source":{"type":"string","enum":["url","text"],"description":"Where the analysed text came from.","example":"url"},"url":{"type":"string","nullable":true,"example":"https://acme.example/blog/post"},"finalUrl":{"type":"string","nullable":true,"example":"https://acme.example/blog/post"},"statusCode":{"type":"integer","nullable":true,"example":200},"htmlBytes":{"type":"integer","nullable":true,"example":48213},"truncated":{"type":"boolean","description":"True when the page hit the 2 MB cap or the text hit the 100,000 character cap.","example":false},"readability":{"$ref":"#/components/schemas/ReadabilityMetrics"},"durationMs":{"type":"integer","example":198}},"required":["source","url","finalUrl","statusCode","htmlBytes","truncated","readability","durationMs"]},"RobotsResponse":{"type":"object","properties":{"domain":{"type":"string","description":"Hostname that was queried.","example":"acme.example"},"origin":{"type":"string","description":"Origin the robots.txt was fetched from.","example":"https://acme.example"},"robotsUrl":{"type":"string","example":"https://acme.example/robots.txt"},"statusCode":{"type":"integer","description":"HTTP status of /robots.txt (404 when the file does not exist).","example":200},"found":{"type":"boolean","description":"True when a robots.txt body was returned and parsed.","example":true},"https":{"type":"boolean","example":true},"contentType":{"type":"string","nullable":true,"example":"text/plain"},"bytes":{"type":"integer","example":312},"groupCount":{"type":"integer","example":2},"ruleCount":{"type":"integer","description":"Allow plus disallow rules parsed.","example":9},"groups":{"type":"array","items":{"$ref":"#/components/schemas/RobotsGroup"},"maxItems":200},"sitemaps":{"type":"array","items":{"type":"string"},"maxItems":200,"description":"Absolute sitemap URLs declared in the file.","example":["https://acme.example/sitemap.xml"]},"host":{"type":"string","nullable":true,"description":"value of the non-standard Host directive, when present.","example":null},"unknownDirectives":{"type":"array","items":{"type":"string"},"maxItems":20,"description":"Directive names that were ignored.","example":["clean-param"]},"lineCount":{"type":"integer","example":24},"truncated":{"type":"boolean","description":"True when a cap was hit (20,000 lines, 200 groups, 500 rules per group).","example":false},"looksLikeHtml":{"type":"boolean","description":"True when /robots.txt returned an HTML page instead of plain text.","example":false},"durationMs":{"type":"integer","example":143}},"required":["domain","origin","robotsUrl","statusCode","found","https","contentType","bytes","groupCount","ruleCount","groups","sitemaps","host","unknownDirectives","lineCount","truncated","looksLikeHtml","durationMs"]},"RobotsGroup":{"type":"object","properties":{"userAgents":{"type":"array","items":{"type":"string"},"maxItems":32,"description":"Lowercased user agents sharing this rule set.","example":["*"]},"allow":{"type":"array","items":{"$ref":"#/components/schemas/RobotsRule"},"maxItems":500},"disallow":{"type":"array","items":{"$ref":"#/components/schemas/RobotsRule"},"maxItems":500},"crawlDelay":{"type":"number","nullable":true,"description":"Crawl-delay in seconds, when the group declares one.","example":null}},"required":["userAgents","allow","disallow","crawlDelay"]},"RobotsRule":{"type":"object","properties":{"path":{"type":"string","description":"Path or pattern as written.","example":"/admin/"},"line":{"type":"integer","description":"1-based line number in robots.txt.","example":6}},"required":["path","line"]},"SitemapResponse":{"type":"object","properties":{"url":{"type":"string","description":"Requested sitemap URL.","example":"https://acme.example/sitemap.xml"},"finalUrl":{"type":"string","example":"https://acme.example/sitemap.xml"},"statusCode":{"type":"integer","example":200},"https":{"type":"boolean","example":true},"contentType":{"type":"string","nullable":true,"example":"application/xml"},"bytes":{"type":"integer","example":18234},"isIndex":{"type":"boolean","description":"True when the document is a <sitemapindex>.","example":false},"format":{"type":"string","enum":["xml","text","unknown"],"description":"Detected sitemap format.","example":"xml"},"sitemapCount":{"type":"integer","description":"Child sitemaps returned (index documents only).","example":0},"urlCount":{"type":"integer","description":"URLs returned (urlset documents only).","example":420},"totalEntries":{"type":"integer","description":"Total <loc> entries found before any cap.","example":420},"sitemaps":{"type":"array","items":{"$ref":"#/components/schemas/SitemapChild"},"maxItems":200,"description":"Child sitemaps, capped at 200."},"urls":{"type":"array","items":{"$ref":"#/components/schemas/SitemapUrl"},"maxItems":500,"description":"URL entries, capped at 500."},"truncatedUrls":{"type":"boolean","description":"True when more than 500 URL entries were present.","example":false},"truncatedSitemaps":{"type":"boolean","description":"True when more than 200 child sitemaps were present.","example":false},"durationMs":{"type":"integer","example":176}},"required":["url","finalUrl","statusCode","https","contentType","bytes","isIndex","format","sitemapCount","urlCount","totalEntries","sitemaps","urls","truncatedUrls","truncatedSitemaps","durationMs"]},"SitemapChild":{"type":"object","properties":{"loc":{"type":"string","example":"https://acme.example/sitemap-blog.xml"},"lastModified":{"type":"string","nullable":true,"example":"2026-11-02T10:00:00+00:00"}},"required":["loc","lastModified"]},"SitemapUrl":{"type":"object","properties":{"loc":{"type":"string","example":"https://acme.example/pricing"},"lastModified":{"type":"string","nullable":true,"example":"2026-10-01T09:12:00+00:00"},"changeFrequency":{"type":"string","nullable":true,"example":"weekly"},"priority":{"type":"number","nullable":true,"example":0.8}},"required":["loc","lastModified","changeFrequency","priority"]},"TextAnalysisResponse":{"type":"object","properties":{"charCount":{"type":"integer","description":"Characters analysed (capped at 100,000).","example":418},"wordCount":{"type":"integer","example":74},"truncated":{"type":"boolean","description":"True when the input exceeded 100,000 characters and was cut off.","example":false},"readability":{"$ref":"#/components/schemas/ReadabilityMetrics"},"keywords":{"$ref":"#/components/schemas/KeywordAnalysis"},"durationMs":{"type":"integer","example":6}},"required":["charCount","wordCount","truncated","readability","keywords","durationMs"]}},"parameters":{}},"paths":{"/v1/audit":{"get":{"tags":["Audit"],"summary":"Run a full weighted on-page audit of one URL","description":"Fetches the page (10 s timeout, 2 MB cap, redirects followed through the SSRF-safe fetcher) and returns title and meta description with length warnings, canonical, robots directives, lang, charset, viewport, H1-H6 counts with the first three headings of each level, image and alt-text counts, internal vs external link counts, word count, text-to-HTML ratio, Flesch reading ease and grade, Open Graph and Twitter completeness, JSON-LD types, hreflang entries, HTTPS, compression, timings, and a 0-100 score from 14 weighted checks that always sum to 100. Pages that return 4xx/5xx are still parsed and the status is reported.","parameters":[{"schema":{"type":"string","minLength":3,"maxLength":2048,"description":"Absolute http(s) URL of the page to audit. A bare hostname is upgraded to https://.","example":"https://acme.example/pricing"},"required":true,"description":"Absolute http(s) URL of the page to audit. A bare hostname is upgraded to https://.","name":"url","in":"query"}],"responses":{"200":{"description":"Full audit report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditResponse"}}}},"400":{"description":"Invalid request (bad parameters or unparsable input)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Target document is larger than the size limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"415":{"description":"Target is not an HTML document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Upstream dependency failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Upstream dependency timed out","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/meta":{"get":{"tags":["Metadata"],"summary":"Extract head metadata, social cards and structured data","description":"Returns only the document head: title, meta description, canonical, robots meta, lang, charset, viewport, theme-color, every og:* and twitter:* tag with a completeness summary, one parsed summary per JSON-LD block, favicon links and hreflang entries. The same 2 MB cap and 10 s timeout apply.","parameters":[{"schema":{"type":"string","minLength":3,"maxLength":2048,"description":"Page whose head metadata should be extracted.","example":"https://acme.example/pricing"},"required":true,"description":"Page whose head metadata should be extracted.","name":"url","in":"query"}],"responses":{"200":{"description":"Head metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetaResponse"}}}},"400":{"description":"Invalid request (bad parameters or unparsable input)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Target document is larger than the size limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"415":{"description":"Target is not an HTML document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Upstream dependency failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Upstream dependency timed out","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/links":{"get":{"tags":["Links"],"summary":"Extract every anchor and classify internal vs external","description":"Parses all <a href> elements, resolves them against the final URL and classifies each as internal (same registrable domain), external or other (mailto/tel/javascript). Returns total counts, rel attribute counts, an empty-anchor-text count and up to 500 links with their anchor text, rel list and target. The truncated flag is set when the page has more than 500 anchors.","parameters":[{"schema":{"type":"string","minLength":3,"maxLength":2048,"description":"Page whose anchors should be extracted. At most 500 links are returned.","example":"https://acme.example/"},"required":true,"description":"Page whose anchors should be extracted. At most 500 links are returned.","name":"url","in":"query"}],"responses":{"200":{"description":"Anchor report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinksResponse"}}}},"400":{"description":"Invalid request (bad parameters or unparsable input)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Target document is larger than the size limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"415":{"description":"Target is not an HTML document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Upstream dependency failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Upstream dependency timed out","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/keywords":{"get":{"tags":["Content"],"summary":"Rank keywords and phrases with frequency and density","description":"Accepts either ?url= (visible text is extracted from the page) or ?text= (raw text, no network). Returns single words and two word phrases after stopword removal, each with occurrences, density percentage and an IDF-style importance score, plus density percentages for the top ten. The ranking uses a bundled frequency prior, not a live corpus.","parameters":[{"schema":{"type":"string","minLength":3,"maxLength":2048,"description":"Fetch this page and analyse its visible text. Send either url or text, not both.","example":"https://acme.example/blog/post"},"required":false,"description":"Fetch this page and analyse its visible text. Send either url or text, not both.","name":"url","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":20000,"description":"Analyse this raw text instead of fetching a URL (max 20,000 characters in a query string; POST /v1/text accepts up to 100,000).","example":"Keyword research is the practice of finding the terms people search for."},"required":false,"description":"Analyse this raw text instead of fetching a URL (max 20,000 characters in a query string; POST /v1/text accepts up to 100,000).","name":"text","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"How many ranked terms to return (1-100, default 20).","example":20},"required":false,"description":"How many ranked terms to return (1-100, default 20).","name":"limit","in":"query"}],"responses":{"200":{"description":"Keyword analysis","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeywordsResponse"}}}},"400":{"description":"Invalid request (bad parameters or unparsable input)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Target document is larger than the size limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"415":{"description":"Target is not an HTML document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Upstream dependency failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Upstream dependency timed out","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/readability":{"get":{"tags":["Content"],"summary":"Score readability with Flesch, Flesch-Kincaid and Gunning Fog","description":"Accepts either ?url= or ?text=. Returns Flesch reading ease (0-100), Flesch-Kincaid grade, Gunning Fog index, word/sentence/paragraph/syllable counts, average words per sentence, the longest sentence with its position, and a passive-voice hint count. Syllables are counted heuristically, so treat grades as estimates.","parameters":[{"schema":{"type":"string","minLength":3,"maxLength":2048,"description":"Fetch this page and score its visible text. Send either url or text, not both.","example":"https://acme.example/blog/post"},"required":false,"description":"Fetch this page and score its visible text. Send either url or text, not both.","name":"url","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":20000,"description":"Score this raw text instead of fetching a URL (max 20,000 characters in a query string).","example":"The cat sat on the mat. The dog ran in the park."},"required":false,"description":"Score this raw text instead of fetching a URL (max 20,000 characters in a query string).","name":"text","in":"query"}],"responses":{"200":{"description":"Readability metrics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReadabilityResponse"}}}},"400":{"description":"Invalid request (bad parameters or unparsable input)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Target document is larger than the size limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"415":{"description":"Target is not an HTML document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Upstream dependency failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Upstream dependency timed out","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/robots":{"get":{"tags":["Crawling"],"summary":"Fetch and parse a domain's robots.txt","description":"Fetches only <origin>/robots.txt and returns the user-agent groups with their allow/disallow rules and line numbers, crawl-delay, sitemap URLs, the non-standard Host value and any directives that were ignored. A missing file returns found=false with its status code instead of an error. Gzipped or HTML responses are reported, never parsed as rules.","parameters":[{"schema":{"type":"string","minLength":3,"maxLength":2048,"description":"Domain to inspect, with or without scheme. Only /robots.txt is fetched.","example":"acme.example"},"required":true,"description":"Domain to inspect, with or without scheme. Only /robots.txt is fetched.","name":"domain","in":"query"}],"responses":{"200":{"description":"Parsed robots.txt","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RobotsResponse"}}}},"400":{"description":"Invalid request (bad parameters or unparsable input)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Upstream dependency failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Upstream dependency timed out","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/sitemap":{"get":{"tags":["Crawling"],"summary":"Parse a sitemap or sitemap index","description":"Fetches one sitemap URL and parses it as an <urlset> (up to 500 URLs with lastmod, changefreq and priority), a <sitemapindex> (up to 200 child sitemaps) or a plain text URL list. It does not follow child sitemaps. Gzipped .xml.gz files are rejected with 415; pass the decompressed XML URL.","parameters":[{"schema":{"type":"string","minLength":3,"maxLength":2048,"description":"Absolute URL of a sitemap.xml or sitemap index. Gzipped (.xml.gz) files are rejected.","example":"https://acme.example/sitemap.xml"},"required":true,"description":"Absolute URL of a sitemap.xml or sitemap index. Gzipped (.xml.gz) files are rejected.","name":"url","in":"query"}],"responses":{"200":{"description":"Parsed sitemap","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SitemapResponse"}}}},"400":{"description":"Invalid request (bad parameters or unparsable input)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"415":{"description":"Sitemap is gzipped and cannot be parsed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Upstream dependency failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Upstream dependency timed out","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/text":{"post":{"tags":["Content"],"summary":"Run readability and keyword analysis on raw text","description":"No network call. Send up to 100,000 characters of text and receive the readability metrics and keyword ranking in one response. Larger payloads are rejected with 413, and JSON bodies above 512 KB are rejected before parsing.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":500000,"description":"Raw text to analyse. Up to 100,000 characters are scored; longer input is truncated and flagged.","example":"Keyword research is the practice of finding the terms people type into search engines. Good research starts with intent."},"limit":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"How many ranked terms to return (1-100, default 20).","example":20}},"required":["text"]}}}},"responses":{"200":{"description":"Combined text analysis","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TextAnalysisResponse"}}}},"400":{"description":"Invalid request (bad parameters or unparsable input)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Text exceeds the 100,000 character limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Upstream dependency failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Upstream dependency timed out","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}