Исследование

POST /v1/research собирает досье по правовому вопросу. Конвейер последовательно проходит закон, разъяснения и практику; порядок и обязательность этапов заданы кодом шлюза. Ответ – дословные выдержки с реквизитами и провенансом. Текст ответа языковая модель здесь не пишет: эндпоинт подходит, когда вывод формулирует сам агент клиента или когда нужен проверяемый перечень источников.

Этапы конвейера

1. Разбор вопроса. Нормы, упомянутые в тексте вопроса, извлекаются регулярными выражениями, без языковой модели.
2. Закон. По каждой распознанной норме – дословный текст в редакции на дату as_of; кроме того, тематический поиск по слою законодательства. Если редакции на дату нет, в досье попадает действующий текст с отметкой edition_mismatch и записью в gaps.
3. Разъяснения. Тематический поиск по сегментам «Разъяснения судов» и «Разъяснения госорганов» и обратный поиск документов, применяющих нормы вопроса.
4. Практика. Тематический поиск по сегменту «Судебные акты» и обратный поиск актов, применяющих нормы вопроса.

Слои не смешиваются в общем ранжировании: судебный акт не вытесняет постановление Пленума Верховного Суда Российской Федерации, они лежат в разных разделах досье. Каждому фрагменту разъяснений и практики шлюз проставляет силу источника – поле authority, при необходимости и оговорку о применимости – applicability_note.

Тело запроса

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

Фильтры filters передаются в тематический поиск всех трех сегментов – и судебных актов, и разъяснений. Ограничения по суду, периоду и инстанции рассчитаны на судебные акты и могут отсечь разъяснения высших судов. Если нужны и разъяснения, и практика за период, выполните два запроса или запросите практику отдельно через /v1/practice/search. Обратный поиск по нормам (by_norm) фильтры не учитывает.

Поля ответа

Фрагмент тематической выдачи практики или разъяснений содержит chunk_id, дословный text, context_text – тот же фрагмент с соседними, sha256_text, score, реквизиты документа в document (doc_key, title, court, decision_date, number, case_number, uid, instance, act_type, status, review_outcome) и провенанс в provenance (sha256_raw_segment, sha256_clean_html). Оценки score разных слоев между собой не сравнимы.

Поля, не описанные в таблице (например, constraint_calls), служебные: используйте их для журналирования, а не для логики клиента. Состав agent_plan зависит от режима и может расширяться.

Режимы

По ключу API работает режим по умолчанию – конвейер без агента. Агентный веер и цикл – режимы с ИИ-агентом LexaAI: по ключу API шлюз отвечает 403 с detail Режимы с ИИ-агентом LexaAI (agent_search, research_mode=loop) недоступны по ключу API, см. Что недоступно по ключу API.

Значение research_mode: "fanout" без agent_search: true агентную фазу не включает. Если планировщик веера недоступен, фаза пропускается, а досье конвейера возвращается как есть; причина видна в agent_plan.

Перечень дел

Вопросы вида «все дела по статье за период» решает перечень, а не поиск: у поиска – ограниченное число результатов и релевантность, у перечня – полный total и постраничный обход. В /v1/research перечень строится только по явному объявлению: клиента – полем enumeration или агента – в агентных режимах.

{
  "question": "Какие дела об оспаривании кадастровой стоимости рассмотрены апелляцией в 2025 году?",
  "enumeration": {
    "needed": true,
    "query": "\"кадастровая стоимость\"",
    "filters": {"instance": "апелляция", "date_from": "2025-01-01", "date_to": "2025-12-31"}
  }
}

Блок enumeration ответа строится без языковой модели: total, first_page (до 50 карточек дел), facets, page.cursor для продолжения через /v1/practice/list, признаки delivered и complete. Если текстовое сужение не применилось, query_applied равно false, а при отказе слоя в нем – поле query_error. Поле enumeration_intent показывает, кто объявил перечень: sources – client, agent или оба.

Неполнота и ошибки

• Сбой слоя не прерывает конвейер: слой помечается available: false с причиной в error, в gaps добавляется запись, остальные этапы выполняются. Код ответа – 200.
• В gaps попадают: недоступные слои, нормы вне корпуса законодательства, отсутствие редакции на дату, устаревший срез корпуса практики, пустая выдача по объявленным фильтрам, недоступность справочника судов, ошибки агентной фазы.
• В /v1/research нет поля degraded: признаки неполноты – gaps и available: false.
• 403 – режим с ИИ-агентом LexaAI по ключу API; 422 – недопустимые значения фильтров или тела запроса; 429 – ограничение частоты; подробнее – в разделе Ошибки и деградация.

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

Досье на дату редакции норм, с расширенной выдачей в каждом слое:

curl -sS --max-time 600 https://api.lexaai.ru/v1/research \
  -H "X-Api-Key: $LEXAAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Возмещаются ли расходы на отчет об оценке при оспаривании кадастровой стоимости?",
    "as_of": "2026-01-01",
    "top_k": 12
  }'