{"openapi":"3.1.0","info":{"title":"Ukrainian lemmatizer","version":"0.1.0","summary":"Lemmas, parts of speech and morphological tags for Ukrainian text, in the convention the Ukrainian Frequency list was built with.","description":"A hosted lemmatization endpoint matched to the Ukrainian Frequency top-12,000 list (VESUM headword convention). Analysis: LanguageTool Ukrainian tokenizer, VESUM tagger and rule-based disambiguator (the core nlp_uk's TagText wraps; nlp_uk's statistical and semantic extras are not applied). Dictionary: ua.net.nlp:morfologik-ukrainian-lt:6.8.0, LanguageTool 6.8. Every request is normalized (NFC, stress marks stripped, apostrophe glyphs folded) before it is hashed; responses are cached by that hash; no input text is retained or logged. VESUM is CC BY-NC-SA and stays server-side: the endpoint returns analyses of your own text and never the dictionary.","license":{"name":"Service terms: analyses of your text are yours; the endpoint is rate-limited and offered as is","url":"https://uavocab.org/research/lemmatizer"},"contact":{"url":"https://uavocab.org/research/lemmatizer"}},"servers":[{"url":"https://uavocab.org"}],"paths":{"/api/lemmatize":{"post":{"operationId":"lemmatize","summary":"Analyze a text or a list of tokens","description":"Send either text (up to 10,000 characters; the service tokenizes and disambiguates in context) or tokens (up to 2,000 strings; each is analyzed on its own, which is what a word-list join wants). Rate limit: 30 requests per minute and 300 per hour per IP; a 429 carries Retry-After in seconds. CORS is open: every response, errors included, carries Access-Control-Allow-Origin: *, and the preflight is answered, so a browser can call it directly.","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["text"],"properties":{"text":{"type":"string","maxLength":10000}}},{"type":"object","required":["tokens"],"properties":{"tokens":{"type":"array","maxItems":2000,"items":{"type":"string"}}}}]},"examples":{"text":{"value":{"text":"Вона повідомила про це вчора."}},"tokens":{"value":{"tokens":["ім'я","кав'ярня","під'їзд","м'ясо","п'ять"]}}}}}},"responses":{"200":{"description":"The analysis.","headers":{"X-Cache":{"schema":{"type":"string","enum":["hit","miss"]},"description":"Whether the answer came from the content-hash cache."},"X-Content-Hash":{"schema":{"type":"string"},"description":"SHA-256 of the normalized request payload (first 16 hex digits); the cache key."}},"content":{"application/json":{"schema":{"type":"object","required":["tokens","meta"],"properties":{"tokens":{"type":"array","items":{"type":"object","required":["token","lemma","pos","ud","tags","known","ambiguous","alternatives"],"properties":{"token":{"type":"string","description":"The token as analyzed, after normalization (NFC, stress marks stripped, apostrophe as U+0027)."},"lemma":{"type":["string","null"],"description":"The VESUM headword of the primary reading, apostrophe written U+2019 to match the frequency list. For an unknown word, the token itself; null only for an empty token."},"pos":{"type":["string","null"],"description":"VESUM coarse part of speech: noun, verb, adj, adv, advp, numr, prep, conj, part, intj, noninfl, onomat, number, punct, symb. null when unknown."},"ud":{"type":["string","null"],"description":"A best-effort Universal Dependencies tag derived from the VESUM tag (NOUN, PROPN, VERB, ADJ, DET, PRON, ADV, NUM, ADP, CCONJ, SCONJ, PART, INTJ, PUNCT, SYM, X). Approximate; the full tag is beside it."},"tags":{"type":["string","null"],"description":"The full VESUM morphological tag of the primary reading, e.g. noun:inanim:n:v_naz."},"known":{"type":"boolean","description":"Whether the dictionary knows the word at all."},"ambiguous":{"type":"boolean","description":"True when more than one distinct lemma survived disambiguation."},"alternatives":{"type":"array","items":{"type":"object","properties":{"lemma":{"type":"string"},"pos":{"type":"string"},"ud":{"type":["string","null"]},"tags":{"type":"string"}}},"description":"Every other (lemma, tag) reading the disambiguator left standing, in its order."},"start":{"type":"integer","description":"Text mode only: where the token starts in the text as you sent it (UTF-16 code units, what JavaScript string indexes count), so text.slice(start, end) is the token's original surface, stress marks included. The token field is the normalized form."},"end":{"type":"integer","description":"Text mode only: end offset (exclusive), in the same units."},"pieces":{"type":"array","description":"Tokens mode only: when a caller's token tokenizes into several pieces (a phrase, trailing punctuation), the pieces' analyses; the token itself is then reported as unknown rather than guessed."}}}},"meta":{"type":"object","required":["service","tagger","vesum","dictionaryArtifact","pipeline","lemmaConvention","retention","mode","chars","tokens","ms","cache","hash"],"properties":{"service":{"type":"string"},"tagger":{"type":"string","description":"The tagger and its version, e.g. LanguageTool Ukrainian 6.8."},"vesum":{"type":"string","description":"The VESUM dictionary version (the morfologik-ukrainian-lt artifact version)."},"dictionaryArtifact":{"type":"string"},"pipeline":{"type":"string"},"lemmaConvention":{"type":"string"},"retention":{"type":"string"},"mode":{"type":"string","enum":["text","tokens"]},"chars":{"type":"integer"},"tokens":{"type":"integer"},"ms":{"type":"integer","description":"Analysis time in the service, milliseconds (0 on a cache hit)."},"cache":{"type":"string","enum":["hit","miss"]},"hash":{"type":"string"},"roundTripMs":{"type":"integer","description":"Proxy to service and back, milliseconds, measured when the analysis was made (kept on a cache hit)."}}}}}}}},"400":{"description":"Malformed body: neither text nor tokens, both, an empty text, or a non-string token. The error names what to change."},"413":{"description":"Over the size limit (10,000 characters or 2,000 tokens). Split the request."},"429":{"description":"Rate limited. Retry-After (seconds) says when a slot frees.","headers":{"Retry-After":{"schema":{"type":"integer"}}}},"503":{"description":"The analysis service is not configured, not reachable, or refused this deployment's credentials. Nothing was analyzed; try later. The body carries `error` (a sentence) and `reason`: not-configured, unreachable, refused-credentials or upstream-error."}}}},"/api/lemmatize/openapi.json":{"get":{"operationId":"openapi","summary":"This document","responses":{"200":{"description":"The OpenAPI 3.1 document."}}}}},"components":{"schemas":{"Token":{"type":"object","required":["token","lemma","pos","ud","tags","known","ambiguous","alternatives"],"properties":{"token":{"type":"string","description":"The token as analyzed, after normalization (NFC, stress marks stripped, apostrophe as U+0027)."},"lemma":{"type":["string","null"],"description":"The VESUM headword of the primary reading, apostrophe written U+2019 to match the frequency list. For an unknown word, the token itself; null only for an empty token."},"pos":{"type":["string","null"],"description":"VESUM coarse part of speech: noun, verb, adj, adv, advp, numr, prep, conj, part, intj, noninfl, onomat, number, punct, symb. null when unknown."},"ud":{"type":["string","null"],"description":"A best-effort Universal Dependencies tag derived from the VESUM tag (NOUN, PROPN, VERB, ADJ, DET, PRON, ADV, NUM, ADP, CCONJ, SCONJ, PART, INTJ, PUNCT, SYM, X). Approximate; the full tag is beside it."},"tags":{"type":["string","null"],"description":"The full VESUM morphological tag of the primary reading, e.g. noun:inanim:n:v_naz."},"known":{"type":"boolean","description":"Whether the dictionary knows the word at all."},"ambiguous":{"type":"boolean","description":"True when more than one distinct lemma survived disambiguation."},"alternatives":{"type":"array","items":{"type":"object","properties":{"lemma":{"type":"string"},"pos":{"type":"string"},"ud":{"type":["string","null"]},"tags":{"type":"string"}}},"description":"Every other (lemma, tag) reading the disambiguator left standing, in its order."},"start":{"type":"integer","description":"Text mode only: where the token starts in the text as you sent it (UTF-16 code units, what JavaScript string indexes count), so text.slice(start, end) is the token's original surface, stress marks included. The token field is the normalized form."},"end":{"type":"integer","description":"Text mode only: end offset (exclusive), in the same units."},"pieces":{"type":"array","description":"Tokens mode only: when a caller's token tokenizes into several pieces (a phrase, trailing punctuation), the pieces' analyses; the token itself is then reported as unknown rather than guessed."}}}}}}