{"openapi":"3.0.3","info":{"title":"TextMind API","version":"1.0.0","description":"One API for text understanding. Six endpoints run deterministic algorithms with zero marginal cost, four call Cloudflare Workers AI when you need generation rather than measurement.\n\n**Deterministic (costClass \"free\", no model, stable output):** keyword extraction with TF-IDF over sentences and 1/2/3-grams, entity extraction with exact spans, lexicon sentiment with per-sentence breakdown, language detection across twelve languages, readability metrics and the stopword reference lists.\n\n**Neural (costClass \"neural\", Workers AI binding required):** summarisation with chunking, tone rewriting, zero-shot classification and translation. These return 503 AI_UNAVAILABLE when the binding is missing or a model call fails, never a 500.\n\n**Honest limits:** sentiment is a curated word list, so sarcasm, emoji and irony are missed. Language detection uses short built-in samples and is unreliable below about three words. Readability formulas are English-calibrated. AI output quality and factual accuracy depend on the model, and typical latency is 1-3 seconds. Plain text is expected: HTML is not stripped.\n\n**Built for:** support ticket triage, CMS and SEO content tooling, lead qualification from free text, migration audits, moderation pre-screens, and any product that needs a few text features without an OpenAI bill.","termsOfService":"https://example.com/terms","contact":{"name":"Ayam Labs","url":"https://github.com/ayam04","email":"ayamullahkhan04@gmail.com"}},"servers":[{"url":"https://textmind.ayamk.in","description":"Direct origin"},{"url":"https://rapidapi.com","description":"RapidAPI marketplace"}],"tags":[{"name":"Text analysis","description":"Deterministic, free text analysis. No model calls."},{"name":"AI text","description":"Workers AI powered rewriting, summarising, classification and translation."},{"name":"Reference","description":"Static reference data used by the analysis endpoints."}],"x-provider":"Ayam Labs","components":{"schemas":{"KeywordsResponse":{"type":"object","properties":{"keywords":{"type":"array","items":{"$ref":"#/components/schemas/Keyword"}},"stats":{"$ref":"#/components/schemas/KeywordStats"},"truncated":{"type":"boolean","description":"True when more keywords were found than the limit allowed.","example":false},"meta":{"$ref":"#/components/schemas/ResponseMeta"}},"required":["keywords","stats","truncated","meta"]},"Keyword":{"type":"object","properties":{"term":{"type":"string","description":"Term, lowercased, n-gram tokens joined by a single space.","example":"solar panels"},"ngram":{"type":"integer","minimum":1,"maximum":3,"description":"Number of tokens in the term.","example":2},"count":{"type":"integer","description":"Occurrences in the text.","example":3},"sentenceHits":{"type":"integer","description":"Number of sentences containing the term (document frequency).","example":2},"idf":{"type":"number","description":"Inverse document frequency over sentences, ln((1+S)/(1+df)) + 1.","example":1.4055},"density":{"type":"number","description":"Percentage of token positions where the term occurs.","example":4.286},"score":{"type":"number","description":"Relative relevance 0-100, where 100 is the best term in this text.","example":100}},"required":["term","ngram","count","sentenceHits","idf","density","score"]},"KeywordStats":{"type":"object","properties":{"characters":{"type":"integer","example":96},"words":{"type":"integer","description":"Token count, stopwords included.","example":14},"uniqueWords":{"type":"integer","example":11},"sentences":{"type":"integer","example":2},"stopwordCount":{"type":"integer","description":"Tokens that are stopwords in any supported language.","example":4},"stopwordRatio":{"type":"number","example":0.2857},"candidateTerms":{"type":"integer","description":"Distinct unigrams, bigrams and trigrams scored.","example":34}},"required":["characters","words","uniqueWords","sentences","stopwordCount","stopwordRatio","candidateTerms"]},"ResponseMeta":{"type":"object","properties":{"costClass":{"type":"string","enum":["free","neural"],"description":"free = deterministic algorithm, no model call, zero marginal cost. neural = one or more Cloudflare Workers AI model calls, billed per neuron and 1-3 s slower.","example":"free"},"method":{"type":"string","description":"Algorithm version for deterministic endpoints, model id for AI endpoints.","example":"tf-idf-sentences-v1"},"durationMs":{"type":"integer","description":"Server side processing time in milliseconds.","example":4},"textCharacters":{"type":"integer","description":"Characters processed after trimming the input.","example":412}},"required":["costClass","method","durationMs","textCharacters"]},"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"]},"EntitiesResponse":{"type":"object","properties":{"entities":{"type":"array","items":{"$ref":"#/components/schemas/Entity"}},"counts":{"$ref":"#/components/schemas/EntityCounts"},"total":{"type":"integer","example":5},"truncated":{"type":"boolean","description":"True when a cap was hit: 200 entities overall or 50 per type.","example":false},"label":{"type":"string","enum":["deterministic"],"description":"This endpoint is regex based, never model based.","example":"deterministic"},"meta":{"$ref":"#/components/schemas/ResponseMeta"}},"required":["entities","counts","total","truncated","label","meta"]},"Entity":{"type":"object","properties":{"type":{"type":"string","enum":["email","url","phone","date","money","percent","hashtag","mention","ipv4","iban","uuid"],"description":"Entity type.","example":"email"},"value":{"type":"string","description":"Matched text exactly as it appears in the input.","example":"billing@acme.io"},"start":{"type":"integer","description":"Span start, inclusive, in UTF-16 code units.","example":118},"end":{"type":"integer","description":"Span end, exclusive, in UTF-16 code units.","example":134},"confidence":{"type":"number","description":"Fixed confidence per pattern: uuid 0.99, email 0.98, percent 0.97, ipv4 0.97, url 0.96, hashtag 0.95, mention 0.93, iban 0.90 (also passes an ISO 13616 mod-97 checksum), money 0.90, date 0.85, phone 0.60 (pattern match only).","example":0.98}},"required":["type","value","start","end","confidence"]},"EntityCounts":{"type":"object","properties":{"email":{"type":"integer"},"url":{"type":"integer"},"phone":{"type":"integer"},"date":{"type":"integer"},"money":{"type":"integer"},"percent":{"type":"integer"},"hashtag":{"type":"integer"},"mention":{"type":"integer"},"ipv4":{"type":"integer"},"iban":{"type":"integer"},"uuid":{"type":"integer"}},"required":["email","url","phone","date","money","percent","hashtag","mention","ipv4","iban","uuid"]},"SentimentResponse":{"type":"object","properties":{"score":{"type":"number","description":"Normalised score in [-1, 1]: sum of effective valences divided by (5 x token count).","example":0.0815},"comparative":{"type":"number","description":"AFINN style comparative: sum of effective valences divided by token count, in [-5, 5].","example":0.5714},"rawScore":{"type":"number","description":"Raw sum of effective valences.","example":4},"label":{"type":"string","enum":["positive","neutral","negative"],"description":"positive when score >= 0.1, negative when score <= -0.1, otherwise neutral.","example":"positive"},"tokens":{"type":"integer","description":"Token count used for normalisation.","example":7},"matchedTokens":{"type":"integer","description":"Tokens found in the lexicon.","example":2},"negatedTokens":{"type":"integer","description":"Tokens whose valence was flipped by a negator.","example":0},"sentences":{"type":"array","items":{"$ref":"#/components/schemas/SentenceSentiment"}},"sentencesReturned":{"type":"integer","example":1},"sentencesTotal":{"type":"integer","example":1},"topPositive":{"type":"array","items":{"$ref":"#/components/schemas/SentimentToken"}},"topNegative":{"type":"array","items":{"$ref":"#/components/schemas/SentimentToken"}},"lexiconSize":{"type":"integer","description":"Number of words in the built-in lexicon.","example":397},"meta":{"$ref":"#/components/schemas/ResponseMeta"}},"required":["score","comparative","rawScore","label","tokens","matchedTokens","negatedTokens","sentences","sentencesReturned","sentencesTotal","topPositive","topNegative","lexiconSize","meta"]},"SentenceSentiment":{"type":"object","properties":{"index":{"type":"integer","description":"0-based sentence index.","example":0},"text":{"type":"string","description":"Sentence text, truncated to 280 characters.","example":"The update is great."},"truncated":{"type":"boolean","example":false},"tokens":{"type":"integer","example":4},"rawScore":{"type":"number","description":"Sum of effective valences in this sentence.","example":3},"score":{"type":"number","description":"Normalised sentence score in [-1, 1].","example":0.15},"label":{"type":"string","enum":["positive","neutral","negative"],"example":"positive"}},"required":["index","text","truncated","tokens","rawScore","score","label"]},"SentimentToken":{"type":"object","properties":{"token":{"type":"string","example":"great"},"valence":{"type":"integer","description":"Lexicon valence of the word before negation handling, -5 to 5.","example":3},"count":{"type":"integer","example":2},"contribution":{"type":"number","description":"Sum of effective valences, negated occurrences included.","example":6}},"required":["token","valence","count","contribution"]},"DetectLanguageResponse":{"type":"object","properties":{"language":{"type":"string","description":"Detected ISO 639-1 code, or \"unknown\" when no signal was found.","example":"en"},"languageName":{"type":"string","example":"English"},"confidence":{"type":"number","description":"Detector confidence in [0, 1], driven by the margin over the runner-up.","example":0.742},"isReliable":{"type":"boolean","description":"True when confidence >= 0.4 and at least 3 words were seen.","example":true},"candidates":{"type":"array","items":{"$ref":"#/components/schemas/LanguageCandidate"},"description":"Top three candidates, best first."},"scripts":{"$ref":"#/components/schemas/ScriptShares"},"words":{"type":"integer","example":12},"method":{"type":"string","enum":["unicode-script","stopword+trigram","none"],"example":"stopword+trigram"},"meta":{"$ref":"#/components/schemas/ResponseMeta"}},"required":["language","languageName","confidence","isReliable","candidates","scripts","words","method","meta"]},"LanguageCandidate":{"type":"object","properties":{"language":{"type":"string","example":"en"},"name":{"type":"string","example":"English"},"score":{"type":"number","description":"Detection score in [0, 1]; only meaningful relative to the other candidates.","example":0.4512}},"required":["language","name","score"]},"ScriptShares":{"type":"object","properties":{"latin":{"type":"number","example":1},"cyrillic":{"type":"number","example":0},"arabic":{"type":"number","example":0},"devanagari":{"type":"number","example":0},"han":{"type":"number","example":0},"other":{"type":"number","example":0}},"required":["latin","cyrillic","arabic","devanagari","han","other"]},"ReadabilityResponse":{"type":"object","properties":{"fleschReadingEase":{"type":"number","description":"Flesch reading ease. Higher is easier; 60-70 is plain English.","example":62.18},"fleschKincaidGrade":{"type":"number","description":"Flesch-Kincaid grade level (US school year).","example":8.71},"gunningFog":{"type":"number","description":"Gunning fog index, based on words with three or more syllables.","example":9.2},"gradeLevel":{"type":"string","description":"Human readable band derived from the Flesch-Kincaid grade.","example":"grade 9-12"},"counts":{"type":"object","properties":{"characters":{"type":"integer"},"letters":{"type":"integer"},"words":{"type":"integer"},"uniqueWords":{"type":"integer"},"sentences":{"type":"integer"},"syllables":{"type":"integer"},"complexWords":{"type":"integer"}},"required":["characters","letters","words","uniqueWords","sentences","syllables","complexWords"]},"averages":{"type":"object","properties":{"wordsPerSentence":{"type":"number"},"syllablesPerWord":{"type":"number"},"charactersPerWord":{"type":"number"},"readingTimeSeconds":{"type":"number","description":"Reading time at 200 words per minute.","example":8.4}},"required":["wordsPerSentence","syllablesPerWord","charactersPerWord","readingTimeSeconds"]},"longestSentence":{"$ref":"#/components/schemas/LongestSentence"},"meta":{"$ref":"#/components/schemas/ResponseMeta"}},"required":["fleschReadingEase","fleschKincaidGrade","gunningFog","gradeLevel","counts","averages","longestSentence","meta"]},"LongestSentence":{"type":"object","nullable":true,"properties":{"index":{"type":"integer","example":1},"words":{"type":"integer","example":21},"characters":{"type":"integer","example":132},"text":{"type":"string","description":"Sentence text, truncated to 240 characters.","example":"However, the second sentence is considerably longer."},"truncated":{"type":"boolean","example":false}},"required":["index","words","characters","text","truncated"]},"StopwordsResponse":{"type":"object","properties":{"languages":{"type":"array","items":{"$ref":"#/components/schemas/StopwordLanguage"}},"selected":{"type":"object","nullable":true,"properties":{"code":{"type":"string","example":"en"},"name":{"type":"string","example":"English"},"count":{"type":"integer","example":132},"words":{"type":"array","items":{"type":"string"},"example":["a","about","above"]}},"required":["code","name","count","words"],"description":"Populated only when the lang query parameter was sent."},"meta":{"$ref":"#/components/schemas/ResponseMeta"}},"required":["languages","selected","meta"]},"StopwordLanguage":{"type":"object","properties":{"code":{"type":"string","example":"en"},"name":{"type":"string","example":"English"},"count":{"type":"integer","description":"Number of stopwords in this language.","example":132}},"required":["code","name","count"]},"SummarizeResponse":{"type":"object","properties":{"summary":{"type":"string","example":"Acme posted record revenue on strong sensor demand, improved margins through renegotiated contracts, and warned of higher shipping costs and slower hiring."},"style":{"type":"string","enum":["bullets","paragraph"]},"maxWords":{"type":"integer","example":120},"inputWords":{"type":"integer","example":58},"summaryWords":{"type":"integer","example":24},"compressionRatio":{"type":"number","description":"summaryWords / inputWords. Lower means more compression.","example":0.41},"chunks":{"type":"integer","description":"How many sentence-aligned chunks the input was split into (1 when it fit in one call).","example":1},"model":{"type":"string","example":"@cf/openai/gpt-oss-20b"},"meta":{"$ref":"#/components/schemas/ResponseMeta"}},"required":["summary","style","maxWords","inputWords","summaryWords","compressionRatio","chunks","model","meta"]},"RewriteResponse":{"type":"object","properties":{"rewrittenText":{"type":"string","example":"The configuration typo is fixed and the change is ready to ship tomorrow, assuming no further issues."},"notes":{"type":"array","items":{"type":"string"},"description":"Up to five short notes the model returned after NOTES:. Empty when the model did not use the requested format.","example":["Removed filler and slang","Kept the original meaning"]},"tone":{"type":"string","enum":["professional","casual","concise","friendly"]},"inputWords":{"type":"integer","example":19},"outputWords":{"type":"integer","example":16},"model":{"type":"string","example":"@cf/openai/gpt-oss-20b"},"meta":{"$ref":"#/components/schemas/ResponseMeta"}},"required":["rewrittenText","notes","tone","inputWords","outputWords","model","meta"]},"ClassifyResponse":{"type":"object","properties":{"scores":{"type":"array","items":{"$ref":"#/components/schemas/ClassificationScore"},"description":"Every requested label, best first."},"choice":{"type":"string","description":"The label the model picked. Always one of the labels you sent.","example":"billing"},"confidence":{"type":"number","description":"Score of the chosen label after normalisation.","example":0.71},"scoreSource":{"type":"string","enum":["model","choice-only"],"description":"\"model\" when the model returned numeric scores for the labels, \"choice-only\" when it only named a winner (the winner then scores 1 and the rest 0).","example":"model"},"model":{"type":"string","example":"@cf/openai/gpt-oss-20b"},"meta":{"$ref":"#/components/schemas/ResponseMeta"}},"required":["scores","choice","confidence","scoreSource","model","meta"]},"ClassificationScore":{"type":"object","properties":{"label":{"type":"string","example":"billing"},"score":{"type":"number","description":"Normalised relevance in [0, 1]; scores sum to 1 when the model returned numbers.","example":0.71}},"required":["label","score"]},"TranslateResponse":{"type":"object","properties":{"translatedText":{"type":"string","example":"Su factura está adjunta. Páguela en un plazo de 14 días."},"sourceLanguage":{"type":"string","description":"Language used as the source. Detected when you omitted source.","example":"en"},"sourceLanguageDetected":{"type":"boolean","description":"True when the source language came from the built-in detector.","example":false},"targetLanguage":{"type":"string","example":"es"},"characters":{"type":"integer","example":54},"model":{"type":"string","example":"@cf/meta/m2m100-1.2b"},"meta":{"$ref":"#/components/schemas/ResponseMeta"}},"required":["translatedText","sourceLanguage","sourceLanguageDetected","targetLanguage","characters","model","meta"]}},"parameters":{}},"paths":{"/v1/keywords":{"get":{"tags":["Text analysis"],"summary":"Rank keywords and key phrases from plain text","description":"Single-document TF-IDF: sentences are documents, terms are 1/2/3-grams built from contiguous tokens. Stopwords in twelve languages are removed, dense and repeated phrases rank first. The GET variant accepts up to 8,000 characters because of URL length limits; use POST /v1/keywords for up to 100,000.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":8000,"description":"Plain text to analyse. The GET variant accepts up to 8,000 characters because of URL length limits; POST /v1/keywords accepts up to 100,000.","example":"Solar panels convert sunlight into electricity. Solar panels are cheaper than ever, and solar adoption keeps growing."},"required":true,"description":"Plain text to analyse. The GET variant accepts up to 8,000 characters because of URL length limits; POST /v1/keywords accepts up to 100,000.","name":"text","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Maximum number of keywords to return (1-100).","example":10},"required":false,"description":"Maximum number of keywords to return (1-100).","name":"limit","in":"query"}],"responses":{"200":{"description":"Ranked keywords with density and IDF","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"}}}},"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"}}}}}},"post":{"tags":["Text analysis"],"summary":"Rank keywords from a JSON body (up to 100,000 characters)","description":"Same scoring as the GET variant with a larger input limit. Returns the ranked keyword list, document statistics and a truncated flag.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":100000,"description":"Plain text to analyse. HTML is not stripped: send plain text.","example":"Solar panels convert sunlight into electricity. Solar panels are cheaper than ever, and solar adoption keeps growing."},"limit":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Maximum number of keywords to return (1-100).","example":20}},"required":["text"]}}}},"responses":{"200":{"description":"Ranked keywords with density and IDF","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"}}}},"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/entities":{"post":{"tags":["Text analysis"],"summary":"Extract emails, URLs, phones, dates, money and more","description":"Deterministic regex extraction of eleven entity types with exact [start, end) UTF-16 spans and a confidence per type. No model, no network call. Overlaps are resolved by type priority, so a URL wins over an email embedded in it and a date wins over a phone number shaped like a date. At most 200 entities are returned per request, and at most 50 of any one type, so a wall of URLs cannot crowd out emails.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":100000,"description":"Plain text to analyse (up to 100,000 characters). HTML tags are not stripped, so send plain text.","example":"We shipped the new billing page on January 12, 2024 and support tickets dropped 38%. Contact billing@acme.io or call +1 415 555 2671. Our IBAN is DE89370400440532013000."}},"required":["text"]}}}},"responses":{"200":{"description":"Entity list, per-type counts and spans","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntitiesResponse"}}}},"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/sentiment":{"post":{"tags":["Text analysis"],"summary":"Score sentiment with a curated lexicon (free, deterministic)","description":"Sums word valences from a built-in AFINN-style lexicon and normalises them to [-1, 1]. Negators within two tokens flip and halve a word's valence. Returns per-sentence scores for the first 20 sentences plus the strongest positive and negative tokens. Word lists do not understand sarcasm, irony, emoji or non-English text.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":100000,"description":"Plain text to analyse (up to 100,000 characters). HTML tags are not stripped, so send plain text.","example":"We shipped the new billing page on January 12, 2024 and support tickets dropped 38%. Contact billing@acme.io or call +1 415 555 2671. Our IBAN is DE89370400440532013000."}},"required":["text"]}}}},"responses":{"200":{"description":"Normalised score, label, per-sentence breakdown","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SentimentResponse"}}}},"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/detect-language":{"post":{"tags":["Text analysis"],"summary":"Detect one of twelve languages with a confidence score","description":"Combines written-script detection (Cyrillic, Arabic, Devanagari, Han) with stopword coverage and character-trigram similarity for the eight Latin-script languages. Returns the best language, a confidence in [0, 1], the top three candidates and the script mix. Short inputs (under about three words) are often unreliable; check isReliable.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":100000,"description":"Plain text to analyse (up to 100,000 characters). HTML tags are not stripped, so send plain text.","example":"We shipped the new billing page on January 12, 2024 and support tickets dropped 38%. Contact billing@acme.io or call +1 415 555 2671. Our IBAN is DE89370400440532013000."}},"required":["text"]}}}},"responses":{"200":{"description":"Language, confidence, candidates and script shares","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetectLanguageResponse"}}}},"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/readability":{"post":{"tags":["Text analysis"],"summary":"Flesch, Flesch-Kincaid and Gunning fog readability scores","description":"Standard English readability formulas with an estimated syllable count (vowel-group heuristic, no dictionary). Returns Flesch reading ease, Flesch-Kincaid grade, Gunning fog, word/sentence/syllable counts, averages and the longest sentence. Formulas are English-calibrated, so treat other languages as indicative only.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":100000,"description":"Plain text to analyse (up to 100,000 characters). HTML tags are not stripped, so send plain text.","example":"We shipped the new billing page on January 12, 2024 and support tickets dropped 38%. Contact billing@acme.io or call +1 415 555 2671. Our IBAN is DE89370400440532013000."}},"required":["text"]}}}},"responses":{"200":{"description":"Readability scores, counts and averages","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"}}}},"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/stopwords":{"get":{"tags":["Reference"],"summary":"List supported stopword lists, or fetch one language","description":"Without lang, returns every supported language with its stopword count. With lang, also returns the full curated list for that language. These are the lists used by keyword extraction and language detection.","parameters":[{"schema":{"type":"string","enum":["en","es","fr","de","it","pt","nl","sv","ru","ar","hi","zh"],"description":"Return the stopword list for this language. Omit it to list every supported language with its stopword count.","example":"en"},"required":false,"description":"Return the stopword list for this language. Omit it to list every supported language with its stopword count.","name":"lang","in":"query"}],"responses":{"200":{"description":"Supported languages and optional word list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StopwordsResponse"}}}},"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/summarize":{"post":{"tags":["AI text"],"summary":"Summarise up to 12,000 characters with Llama 3.1 8B","description":"Calls Cloudflare Workers AI. Input is trimmed, split into sentence-aligned chunks of 4,000 characters and summarised; when there is more than one chunk the partial summaries are merged in a final call, so a 12,000 character request uses at most four model calls. Returns the summary, the compression ratio and the model id. Latency is typically 1-3 s and quality depends on the model. Returns 503 AI_UNAVAILABLE when the binding is missing or the model fails.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":12000,"description":"Text to summarise (up to 12,000 characters). Long input is split into sentence-aligned chunks and the partial summaries are merged.","example":"Acme reported record revenue in the third quarter, driven by strong demand for its industrial sensors. Margins improved because the company renegotiated component contracts. Management warned that shipping costs may rise next year, and that hiring will slow until the new factory in Ohio opens."},"maxWords":{"type":"integer","minimum":30,"maximum":500,"default":120,"description":"Target summary length in words (30-500). This is a prompt instruction, not a hard truncation.","example":80},"style":{"type":"string","enum":["bullets","paragraph"],"default":"paragraph","description":"Output shape requested from the model.","example":"paragraph"}},"required":["text"]}}}},"responses":{"200":{"description":"Summary, compression ratio and model id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SummarizeResponse"}}}},"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"}}}},"503":{"description":"Workers AI binding unavailable or the model call failed (code AI_UNAVAILABLE)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Upstream dependency timed out","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/rewrite":{"post":{"tags":["AI text"],"summary":"Rewrite text in a chosen tone and return the model's notes","description":"Calls Cloudflare Workers AI (Llama 3.1 8B) and asks for the rewritten text followed by a NOTES section. The notes are the model's own, capped at five lines; if the model ignores the format the notes array is empty and the whole answer is returned as the rewritten text. One model call per request. Returns 503 AI_UNAVAILABLE when the binding is missing or the model fails.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":12000,"description":"Text to rewrite (up to 12,000 characters). Meaning is preserved; nothing is translated.","example":"we got the thing working lol, it was a config typo. gonna ship it tomorrow if nothing explodes"},"tone":{"type":"string","enum":["professional","casual","concise","friendly"],"default":"professional","description":"Tone the model is asked to use.","example":"professional"}},"required":["text"]}}}},"responses":{"200":{"description":"Rewritten text, model notes and model id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RewriteResponse"}}}},"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"}}}},"503":{"description":"Workers AI binding unavailable or the model call failed (code AI_UNAVAILABLE)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Upstream dependency timed out","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/classify":{"post":{"tags":["AI text"],"summary":"Zero-shot classification into 2-20 labels you supply","description":"Calls Cloudflare Workers AI and asks the model for one label plus a score per label, in JSON. Scores are normalised relevance values, not calibrated probabilities: when the model returns no numbers the winning label scores 1 and the rest 0 and scoreSource says \"choice-only\". Labels the model invents are dropped. Returns 503 AI_UNAVAILABLE when the binding is missing or the model fails.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":12000,"description":"Text to classify (up to 12,000 characters).","example":"My card was charged twice and nobody answered my emails for a week."},"labels":{"type":"array","items":{"type":"string","minLength":1,"maxLength":60,"description":"One candidate label.","example":"billing"},"minItems":2,"maxItems":20,"description":"Candidate labels, 2-20, each at most 60 characters. The model picks exactly one; scores for every label are returned.","example":["billing","shipping","product defect","account access","other"]}},"required":["text","labels"]}}}},"responses":{"200":{"description":"Sorted label scores, chosen label and model id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClassifyResponse"}}}},"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"}}}},"503":{"description":"Workers AI binding unavailable or the model call failed (code AI_UNAVAILABLE)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Upstream dependency timed out","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/translate":{"post":{"tags":["AI text"],"summary":"Translate up to 2,000 characters between twelve languages","description":"Calls Cloudflare Workers AI with M2M100 (1.2B parameters). Source language is optional: when omitted the built-in detector runs first and the request fails with 400 instead of guessing if the detection is unreliable. One model call per request, typically 1-3 s. Returns 503 AI_UNAVAILABLE when the binding is missing or the model fails.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":2000,"description":"Text to translate (up to 2,000 characters). Plain text only: markup is translated as text.","example":"Your invoice is attached. Please pay it within 14 days."},"target":{"type":"string","enum":["en","es","fr","de","it","pt","nl","sv","ru","ar","hi","zh"],"description":"Target language code. M2M100 supports many more, but this API validates this twelve-language set.","example":"es"},"source":{"type":"string","enum":["en","es","fr","de","it","pt","nl","sv","ru","ar","hi","zh"],"description":"Source language code. Omit it and the built-in detector guesses; if the guess is unreliable the request fails with 400 instead of guessing wrong.","example":"en"}},"required":["text","target"]}}}},"responses":{"200":{"description":"Translated text and both language codes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranslateResponse"}}}},"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"}}}},"503":{"description":"Workers AI binding unavailable or the model call failed (code AI_UNAVAILABLE)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Upstream dependency timed out","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}