https://developer.gemini.com/rest-api/rest-api

агентам (да и людям, впервые попавшим на сайт) нужен единый предсказуемый указатель того, где лежит документация. /llms.txt — это соглашение, предложенное Anthropic и сообществом llmstxt.org: один файл в формате Markdown в корне хоста с картой документации.

Оценка. 2 = H1 + ≥1 H2 + ≥3 ссылок, и все они открываются · 1 = любой файл с H1 (понижен с 2, если ссылки не открываются) · 0 = файл отсутствует или это HTML-обёртка.

Исправление. Опубликуйте /llms.txt в корне хоста с заголовком `# H1`, заголовками разделов `## H2` и как минимум тремя Markdown-ссылками, ведущими на конкретные страницы документации. Спецификация — на https://llmstxt.org.

Подтверждение. https://developer.gemini.com/llms.txt

/rubric#a1 · статья

/llms-full.txt — это полнотекстовый дамп вашей документации в одном месте; агенты на больших языковых моделях предпочитают его обходу 200 HTML-страниц. Посекционные варианты (/llms-api.txt и т. п.) тоже подходят.

Оценка. 3 = /llms-full.txt в корне хоста, >1 КБ · 2 = посекционный агрегат, найденный через llms.txt · 0 = ни того ни другого, либо SPA-обёртка по адресу /llms-full.txt.

Исправление. Генерируйте /llms-full.txt на этапе сборки (для mkdocs/docusaurus есть плагины) и отдавайте его как text/plain. Держите размер в пределах 100 МБ, чтобы агенты могли скачать файл без потоковой передачи.

Подтверждение. https://developer.gemini.com/llms-full.txt — HTML shell response — site serves SPA fallback at /llms-full.txt

/rubric#a2 · статья

каждый AI-краулер (GPTBot, ClaudeBot, Google-Extended, PerplexityBot, CCBot) читает /robots.txt перед обходом. Явные Allow/Disallow для каждого UA плюс абсолютная директива `Sitemap:` снимают неоднозначность как насчёт индексирования, так и насчёт того, что именно индексировать.

Оценка. 3 = явная директива для UA AI-бота И строка с абсолютным Sitemap: · 2 = только директива для AI-бота · 1 = только абсолютный Sitemap · 0 = ни того ни другого, либо 404.

Исправление. Добавьте `User-agent: GPTBot\nAllow: /` (или Disallow, если того требует политика) для каждого крупного LLM-бота, а также строку `Sitemap: https://example.com/sitemap.xml`. Директива `Content-Signal:` от Cloudflare тоже засчитывается.

Подтверждение. https://developer.gemini.com/robots.txt

/rubric#a3 · статья

карты сайта сообщают краулерам, что индексировать и как часто это меняется. Корректный `<urlset>` с абсолютными URL в `<loc>` по множеству разных страниц сигнализирует о реальном покрытии; заглушка с одним URL (или картой, где 70%+ — шум вроде /tag/ и /category/) не даёт никакого сигнала.

Оценка. 3 = корректный формат + ≥3 различных путей + <30% таксономического мусора · 2 = слишком скудный (<3 путей) или 30–70% мусора · 1 = только корректный формат · 0 = 404 или ошибка разбора.

Исправление. Генерируйте /sitemap.xml на этапе сборки, включайте каждую страницу документации с абсолютным URL в `<loc>` и исключайте варианты /tag/, /category/, /author/, /page=. Ссылайтесь на него из robots.txt абсолютной строкой `Sitemap:`.

Подтверждение. https://developer.gemini.com/sitemap.xml

/rubric#a4 · статья

теги обнаружения позволяют агентам найти Markdown-версию страницы без отдельного запроса, а OpenGraph превращает опубликованные ссылки на документацию в расширенные превью в Slack/Discord/Twitter. И то и другое говорит об осведомлённости о машинных потребителях.

Оценка. 2 = `<link rel=alternate type=text/markdown>` + ≥3 различных свойств `og:` · 1 = только альтернатива в Markdown ИЛИ только OpenGraph · 0 = ни того ни другого.

Исправление. Добавьте `<link rel="alternate" type="text/markdown" href="/page.md">` рядом с вашей canonical-ссылкой и убедитесь, что на главной заданы `og:title`, `og:description`, `og:image` (минимум 3 свойства).

Подтверждение. https://developer.gemini.com/rest-api/rest-api

/rubric#a5 · статья

просмотр 200 HTML-страниц для чтения документации нормален для людей; для агентов это затраты на токенизацию на порядок выше. Markdown-двойник на каждую страницу позволяет агентам вытаскивать только текст.

Оценка. 7 = у 3 из 3 выбранных страниц есть работающий .md-двойник · 4 = у 2 из 3 · 2 = у 1 из 3 · 0 = у 0 из 3.

Исправление. Отдавайте `{page}.md` (или `{page}/index.md`) рядом с каждой HTML-страницей ЛИБО поддерживайте согласование содержимого по `Accept: text/markdown`, возвращающее `Content-Type: text/markdown`. У mkdocs-material и docusaurus для этого есть плагины.

Подтверждение. https://developer.gemini.com/account-admin-endpoints.md

/rubric#b1 · статья

JSON-LD — это совместимый со schema.org способ объявить «эта страница — статья» / «этот продукт — SoftwareApplication». На него ориентируются и поисковики, и агенты, и экстракторы структурированных данных.

Оценка. 4 = разбираемый JSON-LD с `@type` И на главной, И на выбранной странице документации · 3 = на одной из двух · 0 = ни на одной.

Исправление. Встройте `<script type="application/ld+json">{"@context":"https://schema.org","@type":"TechArticle",...}</script>` на каждую страницу документации. Для главной хорошо подходит тип `WebApplication`.

Подтверждение. https://developer.gemini.com/rest-api/rest-api

/rubric#b2 · статья

canonical-ссылки детерминированно решают вопрос «это http- или https-версия, со слешем в конце или без, с query-параметрами или без?». Без них агенты могут проиндексировать один и тот же контент под несколькими URL.

Оценка. 3 = абсолютный canonical И на главной, И на выбранной странице · 2 = только на главной · 1 = присутствует, но относительный · 0 = отсутствует.

Исправление. Добавьте `<link rel="canonical" href="https://example.com/page">` в `<head>` каждой страницы. URL должен включать схему и хост (относительные canonical-ссылки — валидный HTML, но для межхостовых агентов теряют смысл).

Подтверждение. https://developer.gemini.com/rest-api/rest-api

/rubric#b3 · статья

агенты (и поисковики) меньше доверяют документации, которая не сообщает, когда её обновляли в последний раз. Страница документации 2019 года без сигнала свежести неотличима от обновлённой вчера.

Оценка. 2 = присутствует `dateModified` в JSON-LD ИЛИ HTTP-заголовок `Last-Modified` · 0 = ни того ни другого.

Исправление. Либо добавьте `"dateModified": "2026-05-28"` в блок JSON-LD, либо настройте CDN/сервер на выдачу HTTP-заголовка `Last-Modified`. В большинстве генераторов статических сайтов шаблонизация на этапе сборки делает это бесплатно.

Подтверждение. https://developer.gemini.com/rest-api/rest-api

/rubric#b4 · статья

размеченная тегами документация помогает агентам фильтровать («покажи мне страницы по аутентификации») без разбора всего текста. Засчитываются `<meta name="keywords">`, `keywords` в JSON-LD или URL вида `/tags/`.

Оценка. 2 = присутствует хотя бы один таксономический сигнал (meta keywords, keywords в JSON-LD или ссылки вида /tags|/categories|/topics/) · 0 = ни одного.

Исправление. Добавьте `<meta name="keywords" content="api,auth,oauth">` на каждую страницу, ЛИБО включите массив `keywords` в JSON-LD, ЛИБО организуйте контент под URL-префиксами `/topics/` или `/tags/`.

Подтверждение. https://developer.gemini.com/rest-api/rest-api

/rubric#b5 · статья

семантические обёртки HTML5 позволяют агентам (и программам чтения с экрана) отбросить навигацию, подвал и боковые панели и читать только текст документации. Страница, где тело — сплошные `<div>`, заставляет действовать наугад.

Оценка. 2 = текст в `<main>` >200 символов И текст в `<article>` >100 символов · 1 = только `<main>` ИЛИ только `<article>` · 0 = ни того ни другого.

Исправление. Оборачивайте основной текст страницы в `<main>` (или в `<article>` для отдельных страниц документации). Не используйте их для боковых панелей и навигации — они предназначены для самого контента.

Подтверждение. https://developer.gemini.com/rest-api/rest-api

/rubric#b6 · статья

спецификация OpenAPI — это ГЛАВНЫЙ машиночитаемый контракт REST API. Агенты, которые её находят, могут генерировать клиентов, тест-кейсы и точную документацию, не читая ни единой строки HTML.

Оценка. 8 = найдена по одному из стандартных путей-зондов (/openapi.json, /swagger.yaml, /v1/openapi.json и т. д.) · 5 = найдена только через ссылку в HTML · 0 = ничего не найдено.

Исправление. Опубликуйте спецификацию по адресу `/openapi.json` или `/openapi.yaml` в корне хоста (или под путём документации — на этапе 53 проверяются оба). В OpenAPI-first проектах сборочный инструмент уже её генерирует — просто выставьте её наружу.

Подтверждение. https://developer.gemini.com/rest-api/rest-api

/rubric#c1a · статья

найти спецификацию (C1a) — это полдела; она ещё должна быть валидной версии 3.x И описывать схемы ответов, чтобы агенты знали, что получат назад. Спецификация, перечисляющая пути без форматов ответов, — это половина контракта.

Оценка. 7 = OpenAPI 3.x + валидный info + paths + у ≥30% операций есть схемы содержимого ответов · 6 = есть paths, но схем мало · 3 = откат к Swagger 2.0 · 0 = ошибка разбора.

Исправление. Поднимите спецификацию до OpenAPI 3.0 или 3.1, если вы всё ещё на Swagger 2.0. Добавьте `responses: { '200': { content: { 'application/json': { schema: ... } } } }` к каждой операции — именно схемы делают спецификацию полезной для клиентов.

Подтверждение. https://developer.gemini.com/rest-api/rest-api — C1a did not find a spec body

/rubric#c1b · статья

спецификация OpenAPI позволяет агентам сгенерировать клиента; готовая коллекция Postman или собранный SDK позволяет ЛЮДЯМ попробовать API за 30 секунд. И то и другое говорит о вложениях в опыт разработчика.

Оценка. 4 = ссылка на коллекцию Postman И ≥1 ссылка на реестр SDK · 3 = Postman ИЛИ ≥2 ссылки на SDK · 2 = 1 ссылка на SDK · 0 = ничего.

Исправление. Опубликуйте кнопку «Run in Postman», ведущую на god.gw.postman.com/run-collection, и сошлитесь хотя бы на один официальный SDK из npm/PyPI/RubyGems и т. п. прямо с главной страницы документации.

Подтверждение. https://developer.gemini.com/rest-api/rest-api

/rubric#c2 · статья

страница документации, которая просто говорит «вызовите /users», бесполезна без метода, типов параметров, обязательных полей и примера запроса/ответа. Агентам (и людям) нужны все пять элементов, чтобы сделать рабочий вызов.

Оценка. 5 = большинство выбранных страниц классифицированы ML-моделью как `complete` · 3 = большинство `partial` (или 2 complete + 1 absent) · 1 = большинство `absent` · 0 = страниц-кандидатов не найдено.

Исправление. На каждой странице эндпоинта приводите: HTTP-метод и путь, таблицу параметров с типами и флагами обязательности, пример с curl и пример JSON-ответа с кодом статуса. Таблицы параметров в стиле Markdown и блоки `<pre>` с JSON классифицируются уверенно.

Подтверждение. https://developer.gemini.com/rest/account-administration — ml: majority=partial

/rubric#c3 · статья

примеры с curl можно проверить где угодно; примеры на SDK показывают идиоматичное использование. Вместе они закрывают и потребность «можно быстро попробовать?», и «как мне это интегрировать?».

Оценка. 4 = curl И блок SDK на каком-либо языке хотя бы на 1 странице · 2 = только curl · 1 = только SDK · 0 = ни того ни другого.

Исправление. Добавьте к каждому эндпоинту блок кода с вкладками, как минимум с curl + вашим самым используемым языком SDK (Python или JavaScript). Используйте `<code class="language-python">` или `language-bash`, чтобы и подсветка синтаксиса, и наш классификатор это распознали.

Подтверждение. https://developer.gemini.com/rest-api/trading/market-data/get-ticker

/rubric#d1 · статья

`/users/{id}` с `id = 1` и `email = [email protected]` заставляет читателя домысливать, как выглядят реальные данные. Реалистичные заглушки (`[email protected]`, `org_2N5x...`) упрощают работу и предотвращают случайную вставку из документации.

Оценка. 4 = ML-модель говорит, что <20% блоков кода перегружены заглушками · 3 = 20–40% · 2 = 40–60% · 1 = 60–80% · 0 = >80% либо блоков кода нет.

Исправление. Замените `foo`/`bar`/`example.com`/`your_api_key`/`<string>` на реалистично выглядящие значения (`pk_test_51N5...` у Stripe, `+14155552671` у Twilio). Не используйте реальные данные клиентов — но имитируйте их форму.

Подтверждение. https://developer.gemini.com/rest — ml: P(placeholder)>0.6 per block

/rubric#d2 · статья

когда интеграция ломается в 3 часа ночи, разработчику нужно понять, что на самом деле означает `403 - resource_not_owned`, не заводя тикет. Отдельная справочная страница по ошибкам — это разница между пятиминутным исправлением и получасовой отладкой.

Оценка. 3 = отдельная страница ошибок (≥3 кодов с пояснениями) · 1 = коды ошибок описаны по тексту на разных страницах · 0 = нет ничего.

Исправление. Опубликуйте `/errors` (или `/reference/errors`) со списком каждого возвращаемого HTTP-статуса + кодов ошибок уровня приложения + одной фразой о причине каждой. Хорошо подходят таблицы; подойдут и списки определений `<dl>`.

Подтверждение. https://developer.gemini.com/rest-api/rest-api

/rubric#d3 · статья

аутентификация — это база; ограничения частоты запросов — то, по чему разработчик понимает, переживёт ли его интеграция нагрузку прода. И то и другое должно быть на странице верхнего уровня, обнаруживаемой с главной.

Оценка. 3 = документированы и аутентификация, и ограничения частоты · 2 = только аутентификация · 1 = только ограничения частоты · 0 = ни того ни другого.

Исправление. Добавьте страницы `/authentication` (потоки bearer / API-ключ / OAuth) и `/rate-limits` (запросов в минуту, заголовки вроде `X-RateLimit-Remaining`, семантика повтора при 429). На каждой нужно хотя бы 200 символов контекста — а не просто сниппет кода.

Подтверждение. https://developer.gemini.com/account-admin-endpoints

/rubric#d4 · статья

это «workspace», «team» или «organisation»? Выбрать один термин и держаться его во всей документации — значит предотвратить целый класс тикетов «что здесь значит X?». Лучше всего отдельный глоссарий; согласованное употребление приемлемо.

Оценка. 3 = отдельный /glossary с ≥3 структурированными парами термин/определение · 2 = глоссария нет, но терминология остаётся согласованной между страницами (≥80% преобладающего варианта) · 1 = ссылка на глоссарий есть, но содержимое скудное · 0 = ни того ни другого.

Исправление. Опубликуйте `/glossary` в виде `<dl>` с парами `<dt>термин</dt><dd>определение</dd>` (или таблицу из 2 столбцов с определениями ≥50 символов). Используйте одинаковый регистр и написание каждого термина на всех страницах.

Подтверждение. https://developer.gemini.com/rest-api/rest-api/glossary

/rubric#d5 · статья

разработчик, вставляющий ваш пример кода 2022 года в проект 2026 года, не должен узнавать об устаревании эндпоинта во время выполнения. Явные пометки `deprecated` / `beta` / `sunset` в документации избавляют от головной боли при миграции.

Оценка. 2 = `deprecated` в спецификации OpenAPI ИЛИ на ≥2 выбранных страницах рядом с заголовками эндпоинтов · 1 = найдены ключевые слова beta/experimental, но нет признаков устаревания · 0 = нет ничего.

Исправление. Помечайте каждый устаревший эндпоинт через `deprecated: true` в OpenAPI И видимым бейджем или предупреждением в HTML-документации (`<Warning>` у Mintlify, синтаксис admonition у Docusaurus и т. п.). То же для бета-эндпоинтов — видимо в тексте, а не только в спецификации.

Подтверждение. https://developer.gemini.com/rest

/rubric#d6 · статья

это ОТСЕКАЮЩИЙ критерий. Если ваша документация отрисовывается только после выполнения JavaScript (обёртка single-page-app), агенты, скачивающие сырой HTML, не видят ничего. Веб-краулеры, скраперы, curl и большинство AI-загрузчиков не выполняют JS.

Оценка. 6 = текст тела >500 символов хотя бы на одной из главной или 2 подстраниц во всех режимах UA · 3 = главная проходит, но подстраницы — SPA · 0 = SPA-обёртка везде, либо VK-ловушка (3+ URL возвращают идентичное тело).

Исправление. Отдавайте предварительно отрисованный HTML по статическим URL. Если вы используете Next.js/Nuxt/SvelteKit, включите SSG или SSR для раздела документации. Обёртки single-page-app (React SPA, Vue SPA без SSR) не проходят этот критерий и каскадно обнуляют многие другие.

Подтверждение. https://developer.gemini.com/rest-api/rest-api

/rubric#e1 · статья

когда вы реорганизуете документацию, старые ссылки не должны отдавать 404 — они должны делать 301 на новый URL. Стабильные URL — это то, благодаря чему ссылки из блогов, Stack Overflow и закладок переживают вашу перестройку.

Оценка. 2 = стабильный редирект 301/308 хотя бы на 1 из 2 выбранных вариантов URL · 1 = шаблон canonical-алиаса (200 с `<link rel=canonical>`) · 0 = 302 (временный), 404 или редиректа нет.

Исправление. Меняя URL документа, добавляйте редирект 301 со старого пути на новый. Генераторы статических сайтов делают это через конфиги `_redirects` (Netlify) или `redirects:` в `vercel.json` (Vercel).

Подтверждение. https://developer.gemini.com/account-admin-endpoints/

/rubric#e2 · статья

`/v1/users` против `/v2/users` — это дешёвый способ версионировать API И сделать это очевидным для агентов. Метаданные версии, находящиеся только в HTTP-заголовке (а не в пути URL или заголовке страницы документации), для краулеров невидимы.

Оценка. 2 = версия в собственной структуре URL документации (URL карты сайта или спецификации OpenAPI: `/v1/`, `/2024-01-15/`) · 1 = версия в URL документируемого эндпоинта (примеры curl/кода), в `info.version` OpenAPI или в заголовке `<h1>`/`<h2>`/футере · 0 = нет нигде.

Исправление. Добавьте к путям API префикс `/v1/`, `/v2/` и показывайте их в примерах curl/кода; ЛИБО задайте непустой `info.version` в спецификации OpenAPI. API с версионированием по дате (`/2024-01-15/users`) тоже засчитываются.

Подтверждение. https://developer.gemini.com/websocket/archived/v2

/rubric#e3 · статья

битые внутренние ссылки — самый частый сбой документации после лет изменений. Выборочная проверка 5 ссылок ловит худшие случаи (4xx/5xx по ссылкам прямо на главной), не пытаясь обойти каждую ссылку.

Оценка. 2 = 5 из 5 выбранных ссылок на тот же хост возвращают 200 · 1 = 4 из 5 · 0 = ≤3 из 5 ЛИБО на главной найдено меньше 5 различных ссылок на тот же хост.

Исправление. Запускайте проверку ссылок в составе CI (lychee, htmltest, linkinator). Для самых посещаемых ссылок на главной исправляйте любые 404 перед выпуском. Пять рабочих ссылок с посадочной страницы — это абсолютный минимум.

Подтверждение. https://developer.gemini.com/

/rubric#e4 · статья

без явного TOS или политики AI-использования каждый LLM-скрапер вынужден угадывать вашу позицию. Содержательная страница `/terms` или `/license` — особенно с ключевыми словами про AI/ML — делает политику машиночитаемой.

Оценка. 2 = страница TOS найдена И содержит ключевые слова AI/ML-политики в основном контенте · 1 = TOS найдена (содержательная, но без AI-ключевых слов, либо ссылка есть, но страница 404/скудная) · 0 = ссылки на TOS нет.

Исправление. Опубликуйте `/terms` (или `/legal`, `/license`) минимум с 1000 символами текста политики. Включите явные формулировки про AI-скрапинг, обучение моделей и автоматический доступ — даже если вы всё разрешаете, прямо сказать об этом и есть сигнал.

Подтверждение. https://developer.gemini.com/rest-api/rest-api/terms

/rubric#e5 · статья