Документация API

Поиск и экстракция страниц в Markdown для ИИ-агентов. Base URL: api.lynceus.ru

Аутентификация

Bearer-токен в заголовке Authorization. Ключ sk_live_… выдаётся в кабинете сразу после регистрации; до трёх живых ключей одновременно, старые отзываются там же.

Authorization: Bearer sk_live_...

Биллинг

Одной строкой: поиск 1 кр · страница 1 кр · картинки 2 кр · капча-солв 25 кр · research-прогон 300 кр. Кэш везде бесплатный.

300 стартовых кредитов = 300 поисков, или 300 страниц, или 150 запросов картинок — после подтверждения аккаунта в Telegram.

Каждый ответ несёт X-Credits-Charged и X-Credits-Remaining. Баланс: GET /v1/usage.

POST /v1/search

Веб-поиск; RU-фокус. Возвращает до 20 результатов со сниппетами.

curl -s api.lynceus.ru/v1/search \
  -H "Authorization: Bearer $LYNCEUS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "лучшие llm 2026", "max_results": 8}'

Ответ: {results: [{rank, title, url, snippet, published_date}], cache, degraded, widened, credits_charged}. Пустая выдача честно платная (1 кредит). Если окно свежести пустое, выдача честно расширяется и помечается widened: true.

POST /v1/answer

Мгновенный ответ по источникам: поиск → Markdown верхних страниц → короткий синтез с цитатами [N]. Синхронный, секунды. Глубокая версия — /v1/research.

curl -s api.lynceus.ru/v1/answer \
  -H "Authorization: Bearer $LYNCEUS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "чем postgres 18 лучше 17", "depth": "advanced"}'

Ответ: {answer, sources: [{n, title, url}], credits_charged, credits_remaining}. Сбой поиска или синтеза — полный возврат кредитов.

POST /v1/search/batch

До 5 запросов одним вызовом. Те же поля, что у /v1/search (кроме extract_top), плюс общий language/freshness. Биллинг построчный: 1 кредит за каждый некэшированный запрос; при исчерпании кредитов оставшиеся пункты возвращаются с error.code = insufficient_credits, а не валят весь батч.

POST /v1/images

Картинки по текстовому запросу; RU-фокус. В каждом результате — прямая ссылка на изображение, его размеры и страница-источник: агенту не нужно открывать страницу и разбирать HTML в поисках <img>.

curl -s api.lynceus.ru/v1/images \
  -H "Authorization: Bearer $LYNCEUS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "горный пейзаж осень", "max_results": 4}'

Ответ: {results: [{title, image_url, thumb_url, page_url, width, height, domain, mime_type}], cached, credits_charged}. Кэш-хит бесплатный; ошибка движка — возврат кредита.

POST /v1/extract

Страницы → чистый Markdown. JS-сайты рендерятся реальным браузером, упёртые стены проходятся премиум-солвом (25 кредитов за решённую, только по факту решения). Экстракция работает «из коробки»: обе ступени включены по умолчанию — allow_browser и allow_captcha можно выключить флагами false.

curl -s api.lynceus.ru/v1/extract \
  -H "Authorization: Bearer $LYNCEUS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["example.com/post/42"], "size_hint": "l"}'

Ответ: {results: [{url, status, http_code, markdown, chars, truncated, fetch_method, cached}], credits_charged, credits_remaining}. Ошибочный URL — status:"error" + code (http_404, dns_error, blocked, paywall, timeout), 0 кредитов.

POST /v1/extract/async + GET /v1/extract/jobs/:job_id

Тот же экстракт, но асинхронно: до 10 URL в джобу, ответ 202 {job_id, status:"queued", poll_url}, статус и результаты — поллингом. Джоба живёт 24 часа. Поддерживает Idempotency-Key. Биллинг тот же, что у синхронного вызова.

POST /v1/research

Глубокое исследование под ключ: Lynceus сам составляет план поиска, прогоняет запросы, читает страницы через экстракцию и синтезирует отчёт с цитатами [N]. Асинхронно: 300 кредитов холдятся на старте, ответ — job_id. Статус и прогресс (какие запросы уже отработаны, какие страницы прочитаны) — поллингом. Если синтез не собрался — отчёт-фолбэк с собранным материалом доставляется, но кредиты возвращаются полностью.

curl -s api.lynceus.ru/v1/research \
  -H "Authorization: Bearer $LYNCEUS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "сравни sqlite и postgresql для мелких сервисов"}'
# {"job_id":"95b6…","status":"queued","credits_held":300,
#  "poll_url":"/v1/research/jobs/95b6…"}

curl -s api.lynceus.ru/v1/research/jobs/95b6… \
  -H "Authorization: Bearer $LYNCEUS_KEY"
# {"status":"done","result":{"report":{"complete":true,
#  "markdown":"# Отчёт…","queries_used":4,"urls_read":12,
#  "prompt_tokens":10027,"completion_tokens":5553},
#  "credits_charged":300,"credits_remaining":…}}

Ограничения прогона: ≤12 поисков, ≤12 страниц, ≤70k символов контекста синтеза, ≤10 минут. Доступен и как MCP-тул research в lynceus-mcp (поллит джобу за агента).

GET /v1/usage

curl -s api.lynceus.ru/v1/usage -H "Authorization: Bearer $LYNCEUS_KEY"
# {"balance": 293, "plan": "free", ...}

GET /v1/status

Здоровье поискового движка: {"degraded": false}. Бесплатный, без лимитов — годится для health-check в вашем коде.

Совместимость с Tavily

Миграция за минуту: те же /search, /extract, /usage в корне — смените base_url и оставьте остальной код как есть. Поддержаны topic, time_range, include_raw_content, include/exclude_domains, extract_depth, format. Ключ можно передавать и так, и так: Authorization: Bearer или полем api_key в теле запроса — Tavily SDK делают второе, им ничего менять не надо.

Уже используете tavily-python или tavily-js? Смените один параметр — и клиентский код работает с Lynceus:

pip install tavily-python

from tavily import TavilyClient
client = TavilyClient(
    api_key="sk_live_...",
    api_base_url="https://api.lynceus.ru",  # единственная правка
)
client.search("что нового в postgres 18")

Идемпотентность

Заголовок Idempotency-Key: <любая строка> на /v1/search, /v1/extract, /v1/images и /v1/research: повтор запроса с тем же ключом в течение 24 ч (для research — 48 ч, как срок жизни джобы) возвращает сохранённый ответ без повторного списания. Реплей помечается X-Idempotent-Replay: true.

Лимиты

Каждый ответ несёт X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset (секунды до сброса окна); при 429 добавляется Retry-After.

При превышении — 429 с retry_after_s в теле.

Формат ошибок

Единый JSON во всех случаях:

{"error": {"code": "insufficient_credits", "message": "no credits left", "retryable": false}}

MCP для ИИ-агентов

Пакет lynceus-mcp подключает поиск, картинки, экстракцию и research к Claude Code, Codex, Cursor, Hermes и любому MCP-клиенту: github.com/DenSul/lynceus-mcp

Поддержка

Telegram: @LynceusVerifyBot — напишите сообщение, бот передаст его нам; там же подтверждение аккаунта. Покупка пакетов и коды пополнения — тоже через поддержку, отвечаем в течение дня.