Федеративный поиск

POST /v1/search ищет одновременно в слое законодательства (нормы в редакции на дату) и в слое судебной практики. Слои возвращаются раздельно, без общего ранжирования: оценки релевантности двух слоев рассчитаны разными системами и между собой не сравнимы. Выдача – дословные фрагменты с провенансом; шлюз ничего не генерирует. Запрос списывает одну единицу.

Для исследования правового вопроса удобнее /v1/research: он сам строит запросы ко всем слоям и собирает досье. Федеративный поиск подходит агенту, который ведет поиск сам.

Тело запроса

Слой законодательства принимает запрос как свободный текст: операторы языка запросов к нему не применяются. Если запрос написан на языке операторов, ограничьте поиск слоем практики – "layers": ["practice"] – или используйте /v1/practice/search. Слою законодательства лучше подходят слова из заголовка статьи или названия института.

Неизвестные ключи filters слой практики игнорирует без ошибки; какие фильтры применены, видно по полю filters_applied выдачи практики.

Ответ

{
  "query": "налоговая база земельный налог кадастровая стоимость",
  "extractive": true,
  "as_of": "2026-10-07",
  "layers": {
    "norms": {
      "available": true,
      "found": true,
      "count": 10,
      "total_candidates": 37,
      "truncated": true,
      "results": [
        {"ok": true, "status": "ok", "address": "…", "text": "…", "text_sha256": "…", "source_url": "…", "snippet": "…", "score": 12.4}
      ]
    },
    "practice": {
      "available": true,
      "total": 214,
      "shown": 10,
      "results": [
        {"chunk_id": "…", "text": "…", "sha256_text": "…", "score": 0.031, "document": {"doc_key": "…", "title": "…", "court": "…", "decision_date": "2025-03-14"}, "provenance": {"extractive": true, "sha256_raw_segment": "…", "sha256_clean_html": "…"}}
      ],
      "semantic_degraded": false,
      "corpus_max_date": "…",
      "filters_applied": {}
    }
  },
  "disclaimer": "Справочная информация на основе дословных выдержек из правовых источников; ..."
}

Слой законодательства: layers.norms

• results – нормы в редакции на дату as_of: ok, status, address, дословный text, text_sha256, source_url, редакция (edition_valid_from, edition_valid_to), а также snippet – дословный фрагмент вокруг найденных слов – и score.
• Действующие нормы идут первыми. Если найденная статья на дату не действует как норма, у нее ok: false, а status объясняет причину: repealed, not_in_force, history_not_loaded, no_norm_on_date и другие. Такие результаты нельзя считать действующими нормами.
• found – есть ли среди найденного хотя бы одна действующая норма; total_candidates и truncated – сколько кандидатов найдено и усечена ли выдача; note – пояснение для человека.
• Запрос вне предметной области слоя дает found: false и пустой results: слой не подбирает норму по случайному совпадению слов.

Слой практики: layers.practice

• results – фрагменты актов: chunk_id, дословный text, sha256_text, score, реквизиты документа в document и провенанс в provenance.
• total и shown – сколько найдено и сколько показано.
• semantic_degraded: true – смысловая часть поиска недоступна, выдача построена только по совпадению слов.
• corpus_max_date – дата самого позднего акта в корпусе: более поздней практики слой не знает.

Если слой недоступен, вместо выдачи приходит {"available": false, "error": "…"}, а другой слой отвечает как обычно; код ответа – 200. Пустая выдача при валидном запросе – ответ «в корпусе нет», а не ошибка.

Ошибки

• 422 – неизвестный слой в layers, недопустимое значение фильтра, синтаксическая ошибка запроса при "advanced", нарушение ограничений тела.
• 401, 429 – ключ и лимиты, см. Авторизация и лимиты.

Примеры

Свободный запрос к обоим слоям на дату:

curl -sS https://api.lexaai.ru/v1/search \
  -H "X-Api-Key: $LEXAAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "установление кадастровой стоимости в размере рыночной", "as_of": "2025-01-01", "top_k": 5}'

Язык запросов и фильтры – только слой практики:

curl -sS https://api.lexaai.ru/v1/search \
  -H "X-Api-Key: $LEXAAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "\"судебные расходы\" /8 \"кадастровой стоимости\"",
    "layers": ["practice"],
    "syntax": "advanced",
    "filters": {"segment": "Разъяснения судов"},
    "top_k": 10
  }'