Начало работы

Авторизация и лимиты

Ключ API

Ключ передается в каждом запросе одним из двух заголовков:

HTTP

X-Api-Key: lx_...

HTTP

Authorization: Bearer lx_...

Ключ выпускается в кабинете app.lexaai.ru, раздел «Свой агент». Формат – lx_ и случайная строка из 43 символов.
Полностью ключ показывается один раз, при выпуске. Сервис хранит только хеш ключа и восстановить его не может: утерянный ключ отзовите и выпустите новый. В кабинете ключ виден по первым 11 символам (lx_ и восемь знаков).
Ключ действует до отзыва или до срока, если срок задан при выпуске.
Ограничение частоты относится к учетной записи, а не к ключу: все ключи учетной записи делят одно минутное окно. Число активных ключей ограничено планом.

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

Запросы без ключа

Без ключа доступны GET /v1/tools, GET /v1/playbook и GET /v1/health. Запрос к остальным эндпоинтам без ключа или с недействительным ключом получает 401 с заголовком WWW-Authenticate: ApiKey.

Запросы без действующего ключа – к GET /v1/tools, GET /v1/playbook и с неверным ключом – ограничены по IP-адресу: не более 60 в минуту. Сверх лимита – 429 с detail Слишком много запросов без действующего API-ключа и заголовком Retry-After. GET /v1/health этим лимитом не ограничен.

Отзыв ключа

Ключ отзывается в кабинете, раздел «Свой агент». Отзыв вступает в силу в течение 60 секунд: шлюз кэширует результат проверки ключа на это время. После этого запросы с отозванным ключом получают 401.

Что недоступно по ключу API

Ключ API дает доступ к данным – законодательству, разъяснениям и судебной практике – без ИИ-агента LexaAI. Ответы ИИ-агента LexaAI и режимы с ним по ключу недоступны: шлюз отвечает 403.

Запрос	`detail` ответа 403
`POST /v1/answer`	`Ответы ИИ-агента LexaAI недоступны по ключу API. Для своего агента используйте /v1/research, /v1/search и /v1/practice/*; ответы ИИ-агента LexaAI доступны в чате app.lexaai.ru`
`POST /v1/research` с `agent_search: true` или `research_mode: "loop"`	`Режимы с ИИ-агентом LexaAI (agent_search, research_mode=loop) недоступны по ключу API`

Для своего агента используйте /v1/research в режиме по умолчанию, /v1/search и /v1/practice/*. Ответы ИИ-агента LexaAI доступны в чате app.lexaai.ru. Повторять запрос, получивший 403, бесполезно: измените эндпоинт или режим.

Планы и ограничение частоты

Месячных лимитов нет: число запросов по ключу не ограничено, действует только ограничение частоты. Новая учетная запись получает план free – «Бесплатный (бета)»: до 60 запросов в минуту и до 3 активных ключей.

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

Единицы

Шлюз учитывает запросы в единицах: по ним считаются ограничение частоты и статистика в кабинете.

Запрос	Единицы
`/v1/search`, `/v1/practice/*`	1
`/v1/research` в режиме по умолчанию	1
`GET /v1/progress/{id}`, `GET /v1/usage`, `GET /v1/tools`, `GET /v1/playbook`, `GET /v1/health`	—

Ограничение частоты считается в единицах в скользящем окне 60 секунд.
Единицы списываются при приеме запроса, до его выполнения. Запрос, который затем завершился ошибкой, тоже учитывается.
Запрос, отклоненный по ограничению частоты, единиц не списывает.
Единицы – учетная величина, а не квота: потолка числа единиц нет.

Таблица по всем эндпоинтам – в справочнике Эндпоинты и инструменты.

Превышение ограничения частоты

HTTP

HTTP/1.1 429 Too Many Requests
Retry-After: 17
Content-Type: application/json

{"detail": "Превышен лимит запросов в минуту"}

Retry-After – через сколько секунд повторить запрос. Ответ 429 бывает только по минутному окну; поле detail называет, какое ограничение сработало:

`detail`	Что сработало	Когда повторять
`Превышен лимит запросов в минуту`	ограничение частоты плана	через `Retry-After` секунд
`Слишком много запросов без действующего API-ключа`	лимит по IP-адресу для запросов без ключа	через `Retry-After` секунд

Заголовки X-RateLimit

Ответы на запросы с ключом, списывающие единицы, и ответы GET /v1/usage содержат заголовки минутного окна:

HTTP

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59

X-RateLimit-Limit – ограничение частоты плана: единиц в минуту.
X-RateLimit-Remaining – сколько единиц осталось в текущем минутном окне.

Использование: GET /v1/usage

Эндпоинт возвращает план ключа, остаток минутного окна и число единиц с начала текущего месяца. Он требует ключ и не списывает единиц, поэтому агент может вызывать его перед сериями запросов. Частота опроса – не выше ограничения частоты плана, сверх него – 429.

curl

curl -sS https://api.lexaai.ru/v1/usage -H "X-Api-Key: $LEXAAI_API_KEY"

JSON

{
  "plan": {"id": "free", "title": "Бесплатный (бета)"},
  "minute": {"limit": 60, "remaining": 59},
  "month": {
    "start": "2026-10-01",
    "unitsLimit": null,
    "unitsUsed": 42,
    "answerUnitsLimit": 0,
    "answerUnitsUsed": 0
  }
}

month.start – первое число текущего месяца по UTC; month.unitsUsed – единицы с этой даты.
unitsLimit равно null: потолка числа единиц нет.
answerUnitsLimit равно 0: ответы ИИ-агента LexaAI по ключу недоступны.
minute.remaining равно null, если остаток временно неизвестен.

Хранилище ключей недоступно

Если хранилище ключей временно недоступно, шлюз не пропускает запросы с ключами lx_, которые не проверялись в последнюю минуту, и отвечает:

HTTP

HTTP/1.1 503 Service Unavailable
Content-Type: application/json

{"detail": "Хранилище ключей временно недоступно"}

Это не признак отзыва ключа. Повторите запрос позже с паузой.

Где смотреть использование

В кабинете, раздел «Использование»: запросы, единицы и ошибки по дням, эндпоинтам и ключам. Тексты вопросов шлюз в учете не хранит: учитываются время, эндпоинт, код ответа, единицы, режим, признак деградации, число вызовов модели и токенов, длительность.