Документация API
Поиск и экстракция страниц в Markdown для ИИ-агентов. Base URL: api.lynceus.ru
Аутентификация
Bearer-токен в заголовке Authorization. Ключ sk_live_… выдаётся в кабинете сразу после регистрации.
Authorization: Bearer sk_live_...Биллинг
| Операция | Стоимость |
|---|---|
| POST /v1/search | 1 кредит (кэш-хит — 0) |
| POST /v1/extract, 1 URL | 1 кредит за свежую страницу (кэш-хит и ошибка — 0) |
| Капча-солв | 25 кредитов, только с явным allow_captcha |
Каждый ответ несёт 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}'| Поле | Тип | Описание |
|---|---|---|
| query | string | обязательное |
| max_results | int 1–20 | по умолчанию 8 |
| extract_top | int 1–5 | добавить markdown верхним N результатам (1 кредит за страницу) |
| freshness | string | "day" | "week" (новизна) |
| lang | string | "ru" | "en", по умолчанию авто |
Ответ: {results: [{rank, title, url, snippet, published_date}], cache, degraded, credits_charged}. Пустая выдача честно платная (1 кредит).
POST /v1/extract
Страницы → чистый Markdown. JS-сайты рендерятся реальным браузером, упёртые стены проходятся премиум-солвом (по явному разрешению).
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"}'| Поле | Тип | Описание |
|---|---|---|
| urls | []string | до 10 URL за запрос |
| allow_browser | bool | разрешить браузерный рендер JS-сайтов (по умолчанию true) |
| allow_captcha | bool | разрешить капчу-солв (25 кредитов за решённую) |
| max_chars | int | лимит символов на страницу |
| size_hint | string | "s" | "m" | "l" — подсказка кэша |
Ответ: {results: [{url, status, http_code, markdown, chars, truncated, fetch_method, cached}], credits_charged, credits_remaining}. Ошибочный URL — status:"error" + error_code, 0 кредитов.
GET /v1/usage
curl -s api.lynceus.ru/v1/usage -H "Authorization: Bearer $LYNCEUS_KEY"
# {"balance": 293, "plan": "free", ...}Совместимость с Tavily
Миграция за минуту: те же /search, /extract, /usage в корне — смените base_url и оставьте остальной код как есть. Поддержаны topic, time_range, include_raw_content, include/exclude_domains, extract_depth, format.
Идемпотентность
Заголовок Idempotency-Key: <любая строка> на /v1/search и /v1/extract: повтор запроса с тем же ключом в течение 24 ч возвращает сохранённый ответ без повторного списания. Реплей помечается X-Idempotent-Replay: true.
Лимиты
| Лимит | Значение |
|---|---|
| По IP | 120 запросов/мин |
| По ключу | 60 запросов/мин |
Каждый ответ несёт X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset (секунды до сброса окна); при 429 добавляется Retry-After.
| urls за extract | 10 |
| queries за batch | 5 |
При превышении — 429 с retry_after_s в теле.
Формат ошибок
Единый JSON во всех случаях:
{"error": {"code": "insufficient_credits", "message": "no credits left", "retryable": false}}| code | HTTP | Смысл |
|---|---|---|
| unauthorized | 401 | нет/кривой ключ |
| insufficient_credits | 402 | закончились кредиты |
| rate_limited | 429 | лимит запросов, см. retry_after_s |
| engine_timeout | 504 | поисковый движок, повторите |
MCP для ИИ-агентов
Пакет lynceus-mcp подключает поиск и экстракцию к Claude Code, Codex, Cursor, Hermes и любому MCP-клиенту: github.com/DenSul/lynceus-mcp
Поддержка
Письма: support@lynceus.ru · Telegram: @LynceusVerifyBot (он же канал верификации аккаунта).