API

Веб-поиск

Живой поиск по русскоязычному и глобальному вебу. Возвращает очищенные результаты без рекламы и навигации, инфобоксы, готовые ответы и подсказки — плюс метаданные о размере и времени.

POSThttps://srezai.ru/api/v1/search

Пример запроса#

curl -X POST https://srezai.ru/api/v1/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer srz_live_ВАШ_КЛЮЧ" \
  -d '{
    "query": "квантовые вычисления обзор 2026",
    "category": "science",
    "timeRange": "year",
    "language": "ru",
    "num": 10,
    "excerpts": true
  }'

Параметры тела#

Тело запроса — JSON. Обязателен только query; неизвестные или недопустимые значения остальных полей мягко заменяются значением по умолчанию.

querystringrequired

Поисковый запрос. Пробелы схлопываются, обрезается до 300 символов. Пустой запрос вернёт ошибку 400.

categorystringoptional

Набор поисковых движков. Одно из: general (по умолчанию), news, it, science. См. ниже.

timeRangestringoptional

Ограничение по свежести: "" (без ограничения, по умолчанию), day, week, month, year.

languagestringoptional

Язык выдачи: auto (по умолчанию), ru, en.

numnumberoptional

Желаемое число результатов, от 1 до 30. Фактическое количество зависит от ответов движков.

excerptsbooleanoptional

Если true, для топовых результатов подтягивается реальный фрагмент текста страницы под запрос (поле excerpt) — готовый контекст для ответа без перехода на сайт. По умолчанию false; добавляет пару секунд к запросу. Если страница недоступна, поле остаётся пустым (мягкая деградация — остаётся content).

includeDomainsstring[]optional

Искать только на этих сайтах, включая поддомены: до 10 доменов, ["habr.com", "vc.ru"]. См. раздел Фильтр по доменам.

excludeDomainsstring[]optional

Исключить эти сайты и их поддомены: до 10 доменов, ["pinterest.com"]. Можно комбинировать с includeDomains.

Категории

Каждая категория опрашивает свой набор движков. Один источник не занимает больше половины выдачи — результаты диверсифицируются, чтобы вы видели несколько независимых источников, а не один разговорчивый.

  • general — универсальный поиск (Yandex, DuckDuckGo, Bing, Startpage, Mojeek, Википедия).
  • news — новости (Yandex, Google News, Bing, DuckDuckGo).
  • it — разработка (GitHub, Stack Overflow, MDN, DuckDuckGo).
  • science — научные публикации (PubMed, DuckDuckGo, Bing).

Фильтр по доменам#

includeDomains ограничивает выдачу перечисленными сайтами, excludeDomains — убирает их. Оба списка принимают до 10 доменов и работают вместе.

json
{
  "query": "next.js app router роутинг",
  "category": "it",
  "includeDomains": ["habr.com", "vc.ru"],
  "excludeDomains": ["pinterest.com"]
}
  • Поддомены попадают под правило автоматически: habr.com включает и habr.com, и blog.habr.com.
  • Формат — домен: example.com. Полный URL (https://www.example.com/blog) тоже принимается — из него берётся хост. www. отбрасывается, регистр не важен, кириллические домены (хабр.рф) поддерживаются.
  • Домены применяются дважды: как оператор в запросе к движкам и как фильтр по хосту результата. Поэтому в выдаче гарантированно нет посторонних сайтов, даже если движок оператор проигнорировал.
  • Под фильтром выдача может быть пустой — это нормальный ответ 200 с results: [], а не ошибка. Проверьте домены или снимите ограничение.
  • Если список непустой, но ни одна строка не распознана как домен, вернётся 400 — фильтр не применяется молча.

Ответ#

json
{
  "query": "квантовые вычисления обзор 2026",
  "results": [
    {
      "title": "Обзор квантовых вычислений",
      "url": "https://example.ru/quantum",
      "content": "Краткое описание страницы без разметки…",
      "engine": "pubmed",
      "category": "science",
      "source": "example.ru",
      "score": 1.42,
      "relevance": 0.87,
      "publishedDate": "2026-03-11T00:00:00",
      "excerpt": "Реальный фрагмент текста страницы под запрос (при excerpts: true)…"
    }
  ],
  "infoboxes": [
    {
      "title": "Квантовый компьютер",
      "content": "Устройство для вычислений…",
      "urls": [{ "title": "Википедия", "url": "https://ru.wikipedia.org/…" }]
    }
  ],
  "answers": [],
  "suggestions": ["квантовая запутанность", "кубит"],
  "unresponsiveEngines": [],
  "meta": {
    "total": 12,
    "tookMs": 640,
    "rawBytes": 84210,
    "cleanBytes": 5120
  }
}

Поля ответа#

resultsarrayoptional

Результаты поиска (количество задаётся num), пересортированы по релевантности запросу. Каждый содержит title, url (кириллица декодирована для читаемости), content, engine, category, source (домен без www), score (агрегация движка), relevance (лексическая близость запросу, 0…1, по ней и отсортировано), publishedDate (или null) и excerpt (реальный текст страницы при excerpts: true, иначе пустая строка).

infoboxesarrayoptional

До 3 инфобоксов (краткая справка с ссылками), если движок их вернул.

answersstring[]optional

Прямые ответы от источников (например, калькуляторы, определения).

suggestionsstring[]optional

Похожие запросы для уточнения поиска.

unresponsiveEnginesarrayoptional

Движки, не ответившие вовремя. Выдача мягко деградирует — остальные движки всё равно возвращают результаты. Если не ответил ни один, приходит 503 с кодом search_unavailable, а не пустая выдача.

metaobjectoptional

total — число результатов, tookMs — время запроса, rawBytes/cleanBytes — размер сырого и очищенного ответа (наглядно показывает экономию токенов).

Остаток лимита приходит в заголовках X-RateLimit-*, а не в теле ответа — см. Лимиты и квоты.

Заголовки лимитов

В каждом ответе приходят X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset. Подробнее — Лимиты и квоты.

Пустая выдача и сбой — разные вещи

200 с results: [] означает «по запросу ничего не нашлось». Если все движки не ответили, вернётся 503 с кодом search_unavailable — это временный сбой апстрима, на него стоит повторить запрос. См. Ошибки.

Только POST

Эндпоинт принимает только POST. Запрос методом GET вернёт 405 Method Not Allowed.