{"openapi":"3.1.0","info":{"title":"API ГосСловарь для анализа текстов","description":"\n## О ГосСловарь API\n\nAPI позволяет найти в тексте слова, которых нет в нормативных словарях РАН.\n\nДля использования API вам потребуется **APIKEY** — как его получить читайте [в статье на gosslovar.ru](https://gosslovar.ru/blog/gosslovar-api-vstroyte-proverku-tekstov-na-zapreshchennye-inostrannye-slova-v-vashi-protsessy).\n\n---\n\n## Проверка одного слова — `POST /api/v1/check/word`\n\nСинхронная проверка одного слова (не более 100 символов). Результат возвращается немедленно, в отличие от асинхронного API для проверки текста.\n\nС помощью параметра `result_fields` можно запросить дополнительные поля: описание, нормальные формы, похожие слова, варианты исправления и аналоги.\n\n**Пример запроса:**\n```bash\ncurl -X POST 'https://gosslovar.ru/api/v1/check/word'\n  -H 'ApiKey: GS-...'\n  -H 'Content-Type: application/json'\n  -d '{\"word\": \"кэшбек\"}'\n```\n\n**Ответ:**\n```json\n{\n  \"status\": \"done\",\n  \"result\": {\n    \"word\": \"кэшбек\",\n    \"status\": \"forbidden\",\n    \"type\": \"UNKNOWN_FORBIDDEN_WORD\"\n  }\n}\n```\n\n---\n\n## Проверка текста — `POST /api/v1/check/text`\n\nАсинхронная проверка текста. Отправляет текст на анализ и возвращает ID задачи. Результат нужно получить через `GET /api/v1/results/text`.\n\nДля каждого слова возвращается подробный отчёт: тип слова (иностранное, несловарное, сокращение и т.д.), список возможных замен и др.\n\nПри создании задачи можно указать:\n- `check_mode` — режим проверки (`missing_words` — только несловарные слова, `all_words` — все слова).\n- `result_fields` — какие дополнительные поля вернуть для каждого слова.\n\nЧем больше информации включено в отчёт, тем медленнее он формируется. Если вам нужно только подсветить несловарные слова — используйте легковесный режим (без `result_fields`).\n\n**Пример запроса:**\n```bash\ncurl -X POST 'https://gosslovar.ru/api/v1/check/text'\n  -H 'ApiKey: GS-...'\n  -H 'Content-Type: application/json'\n  -d '{\"text\": \"проверка слова кэшбек\"}'\n```\n\n**Ответ:**\n```json\n{\n  \"id\": \"54cae751-1e1a-4be9-8513-7d285e4b649a\"\n}\n```\n\n**Получение результата:**\n```bash\ncurl -X GET 'https://gosslovar.ru/api/v1/results/text?id=54cae751-1e1a-4be9-8513-7d285e4b649a'\n  -H 'ApiKey: GS-...'\n```\n\n**Ответ:**\n```json\n{\n  \"status\": \"done\",\n  \"request\": {\n    \"text\": \"проверка слова кэшбек\"\n  },\n  \"result\": {\n    \"status\": \"not-found\",\n    \"missing_words\": [\n      { \"word\": \"кэшбек\", \"position\": 14, \"length\": 6, \"type\": \"UNKNOWN_FORBIDDEN_WORD\", \"status\": \"forbidden\" }\n    ]\n  }\n}\n```\n","version":"0.1.0"},"servers":[{"url":"https://gosslovar.ru/","description":"Production-сервер"}],"paths":{"/api/v1/check/word":{"post":{"summary":"Проверить одно слово","description":"Синхронно проверяет одно слово и возвращает результат.\n\nВозвращает статус слова (permitted, maybe, forbidden) и его тип.\nС помощью параметра `result_fields` можно запросить дополнительные поля:\nописание, нормальные формы, похожие слова, варианты исправления и аналоги.","operationId":"check_word_api_v1_check_word_post","parameters":[{"name":"ApiKey","in":"header","required":true,"schema":{"type":"string","title":"Ваш ключ API","examples":["GS-..."]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckWordRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckWordResponse"}}}},"400":{"description":"Некорректное тело запроса (пустое слово или длиннее 100 символов)"},"401":{"description":"Некорректный или отсутствующий APIKEY"},"422":{"description":"Некорректный запрос - не прислан APIKEY или другой обязательный параметр"},"429":{"description":"Превышено количество запросов в минуту, повторите запрос позднее"}}}},"/api/v1/check/text":{"post":{"summary":"Проверить текст","description":"Отправляет текст на проверку и возвращает ID задачи. Результат проверки надо получить асинхронно через `/api/v1/results/text`.\nПодбробное описание результата проверки см. в ручке `/api/v1/results/text`.","operationId":"check_text_api_v1_check_text_post","parameters":[{"name":"ApiKey","in":"header","required":true,"schema":{"type":"string","title":"Ваш ключ API","examples":["GS-..."]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckTextRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckTextResponse"}}}},"400":{"description":"Некорректное тело запроса"},"401":{"description":"Некорректный или отсутствующий APIKEY"},"422":{"description":"Некорректный запрос - не прислан APIKEY или другой обязательный параметр, использован GET вместо POST"},"429":{"description":"Превышено количество запросов в минуту, повторите запрос позднее"}}}},"/api/v1/results/text":{"get":{"summary":"Получить результат проверки текста","description":"Возвращает результаты проверки текста по ID задачи.\n\nРучка возвращает поле `status`, которое может принимать одно из значений:\n- `done` — проверка завершена успешно, результат доступен в поле `result`.\n- `running` — проверка все еще выполняется, результат пока недоступен. Повторите запрос позднее.\n- `error` — при выполнении проверки произошла ошибка, текст ошибки доступен в поле `error`.\n\nЕсли анализ завершился успешно (`status=done`), то `/api/v1/results/text` вернет в объекте `result` одно из полей:\n- либо информация о каждом найденном в тексте слове в поле `all_words` (в режиме `check_mode = all_words`),\n- либо информация только о несловарных словах в поле `missing_words` (в режиме `check_mode = missing_words`),\n\nВ любом случае, для каждого слова возвращается объект с его позицией в тексте и прочей информацией, о чем рассказывается далее.\n\n## Результат анализа отдельного слова\n\nДалее разбираются поля, которые возвращаются для каждого слова.\n\n### Поле `word`\nСлово в исходной форме (как оно написано в тексте)\n\n### Поле `position`\nПозиция слова в тексте (индекс символа) в codepoint'ах unicode\n\n### Поле `length`\nДлина слова в символах (codepoint'ах unicode)\n\n### Поле `status`\nТип поля:\n- `permitted` — слово является разрешенным: либо найдено в нормативных словарях, либо является служебной частицей/именем собственным/топонимом.\n- `maybe` — в словарях слово не найдено, но допустимо при некоторых условиях. Например, так размечаются email, url и т.д.\n- `forbidden` — слово не найдено в нормативных словарях. Его использование может быть разрешено законами РФ, например, если это зарегистрированный товарный знак.\n\n### Поле `type`\n\nТип слова:\n- `NOT_WORD` — символьный набор/пунктуация.\n- `NORMAL` — слово найдено в словарях.\n- `URL` — корректный интернет-адрес страницы (со схемой http[s]://).\n- `MAYBE_URL` — возможно, интернет-адрес, но не содержит полной сигнатуры (обычно нет схемы http[s]://)\n- `EMAIL` — адрес электронной почты.\n- `NAME` — имя собственное: Сергей, Илья и т.д.\n- `GEO` — топоним: Москва, Омск и т.д.\n- `PREP` — служебная часть речи: предлог, союз и т.д.\n- `ABBRIV` — вероятно, аббревиатура. Определяется эвристически: небольшая длина и преимущественно заглавные буквы.\n- `SHORT` — вероятно, сокращение: кг, мл, пн и т.д.\n- `ADDRESS` — часть адреса/идентификатор/техническая информация.\n- `COMPLEX` — составное слово. Например, \"нормативно-правовой\"\n- `USER_EXCEPTION` — слово из списка исключений аккаунта, к которому привязан APIKEY.\n- `UNKNOWN_FORBIDDEN_WORD` — слова нет в нормативных словарях, скорее всего, оно не является корректным словом русского языка.\n- `KNOWN_FORBIDDEN_WORD` — слова нет в нормативных словарях, но, вероятно, оно встречается в русском языке.\n- `FOREIGN_LETTERS` — смесь кириллицы и латиницы.\n- `FOREIGN_WORD` — иностранное слово (полностью не содержит кириллицу).\n\n#### Про тип слова `COMPLEX`\nВ некоторых случаях сервис может эвристически распознать, что слово состоит из нескольких допустимых слов. В этом случае тип возвращаемого слова - `COMPLEX`.\nНапример: \"полуготовый\" - приставка \"полу\" + прилагательное \"готовый\".\nКаждое из этих слов есть в нормативных словарях и целое слово соответствует нормам русского языка, но слова \"полуготовый\" в словарях нет.\n\nЭвристики, используемые для определения сложных слов, в редких случаях могут давать неправильный результат.\nНапример, если слово состоит из двух допустимых словарных слов, которые при совместном написании не имеют смысла.\n\nТакже важно, что многие сложные слова есть в словарях, например, \"полураспад\" и \"нормативно-правовой\".\nДля таких слов тип слова будет определен как `NORMAL`, а не `COMPLEX`.\n\n### Поле `description`\nСодержит человекочитаемое описание типа слова (на русском языке), например, \"Иностранное слово\".\n\n### Поле `normal_forms`\nНормальные (начальные) формы слова. Может содержать несколько значений т.к. слово может быть омонимом.\n\nВ зависимости от части речи это:\n- существительное: именительный падеж, единственное число (например: стулья - стул).\n- глагол: инфинитив (неопределенная форма: -ть, -ти, -чь) (например: бежал - бежать).\n- прилагательное: именительный падеж, единственное число, мужской род (например: красивая - красивый).\n\nВ поле `pos` содержится часть речи:\n- `NOUN` - существительное\n- `ADJF` - прилагательное (полное)\n- `ADJS` - прилагательное (краткое)\n- `COMP` - компаратив\n- `VERB` - глагол (личная форма)\n- `INFN` - глагол (инфинитив)\n- `PRTF` - причастие (полное)\n- `PRTS` - причастие (краткое)\n- `GRND` - деепричастие\n- `NUMR` - числительное\n- `ADVB` - наречие\n- `NPRO` - местоимение\n- `PRED` - предикатив\n- `PREP` - предлог\n- `CONJ` - союз\n- `PRCL` - частица\n- `INTJ` - междометие\n- `LATN` - латиница\n- `UNKN` - неизвестная часть речи\n\n### Поле `similar_words`\nСлова, имеющие такой же префикс или постфикс.\nЭто удобно чтобы искать допустимые слова, имеющие такой же или более узкий смысл.\nНапример, для слова \"велнес\" результат будет содержать \"велнес-центр\", \"велнес-клуб\", \"велнес-программа\".\n\n### Поле `spell_words`\nРезультаты проверки слова корректором грамматики (спеллчекером).\nСодержит слова из нормативных словарей, отличающиеся от исходного слова на несколько букв.\nПозволяет найти грамматически корректную замену некоторым словам: \"кэшбек\" - \"кешбэк\".\n\n### Поле `analog_words`\nСодержит допустимые слова-аналоги (или фразы-аналоги): синонимы, допустимые кальки и т.д.\nНапример, для иностранного слова \"email\" может содержать \"электронная почта\", \"имейл\" и т.д.\nПозволяет подобрать замену для несловарного слова.\nВ справочнике аналогов содержатся замены для тысяч популярных слов, справочник постоянно пополняется.","operationId":"results_text_api_v1_results_text_get","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","title":"Id"}},{"name":"ApiKey","in":"header","required":true,"schema":{"type":"string","title":"Ваш ключ API","examples":["GS-..."]}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResultsTextResponse"}}}},"400":{"description":"Некорректный запрос"},"401":{"description":"Некорректный или отсутствующий APIKEY"},"404":{"description":"Проверка с указанным ID не найдена"},"422":{"description":"Некорректный запрос - не прислан APIKEY или другой обязательный параметр, использован POST вместо GET"},"429":{"description":"Превышено количество запросов в минуту, повторите запрос позднее"}}}}},"components":{"schemas":{"CheckMode":{"type":"string","enum":["missing_words","all_words"],"title":"CheckMode","description":"Режим проверки текста."},"CheckStatus":{"type":"string","enum":["done","running","error"],"title":"CheckStatus","description":"Статус проверки"},"CheckTextRequest":{"properties":{"text":{"type":"string","maxLength":20000,"minLength":1,"title":"Text","description":"Текст для проверки на наличие слов из нормативных словарей","examples":["проверка слова \"кэшбек\""]},"check_mode":{"anyOf":[{"$ref":"#/components/schemas/CheckMode"},{"type":"null"}],"description":"Режим проверки текста. `missing_words` (по умолчанию) — вернуть только слова со статусом != permitted (несловарные слова). `all_words` — вернуть все слова (и словарные, и несловарные).","examples":["missing_words"]},"result_fields":{"anyOf":[{"items":{"type":"string","enum":["description","normal_forms","similar_words","spell_words","analog_words"]},"type":"array"},{"type":"null"}],"title":"Result Fields","description":"Список флагов для указания, какие дополнительные поля вернуть для каждого слова. Доступные флаги: - 'description' — описание класса слова, - 'normal_forms' — нормальные формы слова с частями речи, - 'similar_words' — похожие слова из словарей, - 'spell_words' — варианты исправления опечаток, - 'analog_words' — слова-аналоги для замены. ","examples":[["description","normal_forms","similar_words","spell_words","analog_words"]]}},"type":"object","required":["text"],"title":"CheckTextRequest","description":"Запрос на проверку текста.\n\nПараметр check_mode определяет режим проверки:\n- `missing_words` (по умолчанию) — вернуть только несловарные слова (со статусом != permitted).\n- `all_words` — вернуть все слова (разрешённые и запрещённые).\n\nРежим `all_words` существенно увеличивает размер ответа для больших текстов,\nтакже несколько увеличивает время обработки запроса.\n\nПараметр result_fields позволяет указать, какие дополнительные поля вернуть для каждого \nслова. По умолчанию возвращаются только базовые поля (word, position, length, type, status)."},"CheckTextResponse":{"properties":{"id":{"type":"string","title":"Id","description":"Уникальный идентификатор задачи для получения результатов проверки"}},"type":"object","required":["id"],"title":"CheckTextResponse","description":"Ответ при создании задачи на проверку текста. Содержит ID задачи для получения результатов."},"CheckWordRequest":{"properties":{"word":{"type":"string","title":"Word","description":"Слово для проверки (не более 100 символов)","examples":["кэшбек"]},"result_fields":{"anyOf":[{"items":{"type":"string","enum":["description","normal_forms","similar_words","spell_words","analog_words"]},"type":"array"},{"type":"null"}],"title":"Result Fields","description":"Список флагов для указания, какие дополнительные поля вернуть. Доступные флаги: - 'description' — описание класса слова, - 'normal_forms' — нормальные формы слова с частями речи, - 'similar_words' — похожие слова из словарей, - 'spell_words' — варианты исправления опечаток, - 'analog_words' — слова-аналоги для замены. ","examples":[["description","normal_forms","similar_words","spell_words","analog_words"]]}},"type":"object","required":["word"],"title":"CheckWordRequest","description":"Запрос на проверку одного слова."},"CheckWordResponse":{"properties":{"status":{"$ref":"#/components/schemas/CheckStatus","description":"Статус проверки: всегда 'done'"},"result":{"$ref":"#/components/schemas/WordCheckResult","description":"Результат проверки слова"}},"type":"object","required":["status","result"],"title":"CheckWordResponse","description":"Ответ при проверке одного слова."},"PartOfSpeech":{"type":"string","enum":["NOUN","ADJF","ADJS","COMP","VERB","INFN","PRTF","PRTS","GRND","NUMR","ADVB","NPRO","PRED","PREP","CONJ","PRCL","INTJ","LATN","UNKN"],"title":"PartOfSpeech","description":"Часть речи"},"ResultsTextResponse":{"properties":{"status":{"$ref":"#/components/schemas/CheckStatus","description":"Статус задачи: 'running', 'done', 'error'"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Текст ошибки, если status = 'error'"},"request":{"$ref":"#/components/schemas/CheckTextRequest","description":"Исходный запрос на проверку"},"result":{"anyOf":[{"$ref":"#/components/schemas/TextCheckResult"},{"type":"null"}],"description":"Результат проверки (заполнен при статусе 'done')"}},"type":"object","required":["status","request"],"title":"ResultsTextResponse","description":"Ответ при получении результатов проверки текста."},"Statistics":{"properties":{"lines_total":{"type":"integer","title":"Lines Total","default":0},"symbols_total":{"type":"integer","title":"Symbols Total","default":0},"symbols_checked":{"type":"integer","title":"Symbols Checked","default":0},"words_checked":{"type":"integer","title":"Words Checked","default":0},"words_left":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Words Left"},"words_due":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Words Due"},"permitted_words_found":{"type":"integer","title":"Permitted Words Found","default":0},"bad_words_found":{"type":"integer","title":"Bad Words Found","default":0},"is_word_limit_reached":{"type":"boolean","title":"Is Word Limit Reached","default":false},"file_size":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"File Size"},"file_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"File Type"}},"type":"object","title":"Statistics","description":"Модель статистики документа/текста."},"TextCheckResult":{"properties":{"status":{"type":"string","title":"Status","description":"Статус проверки: 'ok' — все слова найдены,'not-found' — есть слова не из словарей"},"missing_words":{"anyOf":[{"items":{"$ref":"#/components/schemas/TextWordEntry"},"type":"array"},{"type":"null"}],"title":"Missing Words","description":"Список слов, не найденных в словарях (возвращается при check_mode='missing_words'). Взаимоисключающее с полем all_words."},"all_words":{"anyOf":[{"items":{"$ref":"#/components/schemas/TextWordEntry"},"type":"array"},{"type":"null"}],"title":"All Words","description":"Список всех проверенных слов (возвращается при check_mode='all_words'). Содержит как словарные, так и несловарные слова. Взаимоисключающее с полем missing_words."},"statistics":{"$ref":"#/components/schemas/Statistics","description":"Статистика проверки"}},"type":"object","required":["status","statistics"],"title":"TextCheckResult","description":"Результат проверки текста на наличие слов из нормативных словарей."},"TextWordEntry":{"properties":{"word":{"type":"string","title":"Word","description":"Слово в исходной форме (как оно написано в тексте)"},"position":{"type":"integer","title":"Position","description":"Позиция слова в тексте (индекс символа) в codepoint'ах unicode"},"length":{"type":"integer","title":"Length","description":"Длина слова в символах"},"status":{"type":"string","title":"Status","description":"Статус слова: permitted — разрешено, maybe — допустимо в некотором контексте, forbidden — запрещено"},"type":{"type":"string","title":"Type","description":"Тип слова: NOT_WORD, NORMAL, URL, EMAIL, NAME, GEO, PREP, ABBRIV, SHORT, ADDRESS, COMPLEX, USER_EXCEPTION, UNKNOWN_FORBIDDEN_WORD, KNOWN_FORBIDDEN_WORD, FOREIGN_LETTERS, FOREIGN_WORD, MAYBE_URL, NOT_SURE"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Человекочитаемое описание класса слова. Возвращается только если в запросе включен флаг 'description'"},"normal_forms":{"anyOf":[{"items":{"$ref":"#/components/schemas/WordNormalForm"},"type":"array"},{"type":"null"}],"title":"Normal Forms","description":"Массив нормальных (начальных) форм слова с частями речи. Возвращается только если в запросе включен флаг 'normal_forms'"},"similar_words":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Similar Words","description":"Список похожих слов из словарей (имеют схожий префикс/постфикс). Возвращается только если в запросе включен флаг 'similar_words'"},"spell_words":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Spell Words","description":"Варианты исправления опечаток от спеллчекера. Возвращается только если в запросе включен флаг 'spell_words'"},"analog_words":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Analog Words","description":"Слова- и фразы-аналоги, которыми можно заменить слово. Возвращается только если в запросе включен флаг 'analog_words'"}},"type":"object","required":["word","position","length"],"title":"TextWordEntry","description":"Информация о слове, встреченном в тексте, включая его позицию.\n\nПоля type и status возвращаются всегда. Остальные поля возвращаются только если \nсоответствующий флаг указан в параметре result_fields запроса."},"WordCheckResult":{"properties":{"word":{"type":"string","title":"Word","description":"Слово в исходной форме (как оно передано в запросе)"},"status":{"type":"string","title":"Status","description":"Статус слова: permitted — разрешено, maybe — допустимо в некотором контексте, forbidden — запрещено"},"type":{"type":"string","title":"Type","description":"Тип слова: NOT_WORD, NORMAL, URL, EMAIL, NAME, GEO, PREP, ABBRIV, SHORT, ADDRESS, COMPLEX, USER_EXCEPTION, UNKNOWN_FORBIDDEN_WORD, KNOWN_FORBIDDEN_WORD, FOREIGN_LETTERS, FOREIGN_WORD, MAYBE_URL, NOT_SURE"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Человекочитаемое описание класса слова. Возвращается только если в запросе включен флаг 'description'"},"normal_forms":{"anyOf":[{"items":{"$ref":"#/components/schemas/WordNormalForm"},"type":"array"},{"type":"null"}],"title":"Normal Forms","description":"Массив нормальных (начальных) форм слова с частями речи. Возвращается только если в запросе включен флаг 'normal_forms'"},"similar_words":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Similar Words","description":"Список похожих слов из словарей (имеют схожий префикс/постфикс). Возвращается только если в запросе включен флаг 'similar_words'"},"spell_words":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Spell Words","description":"Варианты исправления опечаток от спеллчекера. Возвращается только если в запросе включен флаг 'spell_words'"},"analog_words":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Analog Words","description":"Слова- и фразы-аналоги, которыми можно заменить слово. Возвращается только если в запросе включен флаг 'analog_words'"}},"type":"object","required":["word"],"title":"WordCheckResult","description":"Результат проверки одного слова.\n\nПоля type и status возвращаются всегда. Остальные поля возвращаются только если \nсоответствующий флаг указан в параметре result_fields запроса."},"WordNormalForm":{"properties":{"word":{"type":"string","title":"Word","description":"Нормальная (начальная) форма слова"},"pos":{"$ref":"#/components/schemas/PartOfSpeech","description":"Часть речи (обозначение pymorphy)"}},"type":"object","required":["word","pos"],"title":"WordNormalForm","description":"Нормальная форма слова с частью речи."}}}}