API CasusLegal

Подключение

Это REST-API. Подключается к вашему приложению на основе любой LLM или к любому HTTP-клиенту как внешний инструмент, который ваша модель вызывает для поиска по судебной практике.

Base URL: https://app.casus.legal

Аутентификация: заголовок Authorization: Bearer cl_live_…

Формат: JSON по HTTPS.

1. Получить ключ

1. Откройте Личный кабинет, раздел «API»Вход через Telegram или по почте и паролю, тот же аккаунт, что у бота и веб-чата.
   app.casus.legal/account
2. Нажмите «Выпустить ключ»Ключ показывается один раз, начинается с cl_live_…. Сохраните сразу: восстановить нельзя, только перевыпустить.
3. Проверьте балансНа старте бесплатный триал: 300 запросов на 10 дней, лимит 20 запросов в минуту на ключ. Дальше докупка пакетов в том же кабинете.

2. Первый запрос

curl -X POST https://app.casus.legal/v1/search \
  -H "Authorization: Bearer $CASUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "договор энергоснабжения, фактическое потребление", "limit": 15}'

import os, httpx

client = httpx.Client(
    base_url="https://app.casus.legal",
    headers={"Authorization": f"Bearer {os.environ['CASUS_API_KEY']}"},
    timeout=60,
)

r = client.post("/v1/search", json={
    "query": "снижение неустойки по статье 333 ГК",
    "limit": 15,
    "mode": "hybrid",
})
r.raise_for_status()
data = r.json()
for hit in data["results"]:
    print(hit["court"], hit["date"], hit["case_number"], hit["url"])

3. Эндпоинты

POST /v1/searchсписывает 1 запрос

Гибридный поиск. Списывает 1 запрос только при успешном ответе.

Структура ответа отдаёт готовые блоки по иерархии судов. Собирайте ответ из них, не делая отдельный запрос на каждый суд.

{
  "_response_format_hint": "…директива формата ответа…",
  "constitutional_context": { "items": [ … ] },   // КС
  "vs_guidance":            { "items": [ … ] },   // Пленумы и обзоры ВС
  "latest_practice":        { "items": [ … ] },   // свежие определения коллегий ВС
  "vas_history":            [ … ],                // история: практика ВАС
  "results": [
    {
      "id": 12345, "court": "СКЭС", "date": "10.05.2024",
      "case_number": "305-ЭС24-12345", "title": "…", "snippet": "…",
      "score": 0.87,
      "url": "https://app.casus.legal/case/12345?t=<токен>"
    }
  ],
  "_supersession_alert": "…",   // при наличии отменённого и действующего акта
  "expansion": { … }
}

GET /v1/cases/{id}бесплатно

Карточка акта: реквизиты, sections (текст по разделам), articles, hashtags и ссылки url / url_md / url_docx. Используйте для дословных цитат у ключевых актов. Квоту не тратит.

curl https://app.casus.legal/v1/cases/12345 \
  -H "Authorization: Bearer $CASUS_API_KEY"

4. Ошибки и лимиты

Все ошибки приходят как JSON {"error": "<код>", "message": "…"}.

5. Лучшие практики

• Ключ только на бэкенде. Храните в переменных окружения или секретах, не в коде, не в гите, не на клиенте.
• Ретраи с экспонентой. На 429 и 5xx повторяйте с возрастающей паузой: 2с, 4с, 8с.
• Кешируйте карточки. Содержимое GET /v1/cases/{id} стабильно, а вызов бесплатный.
• Не модифицируйте ссылки. Поле url подписано токеном со сроком около 30 дней. Передавайте его как есть.

Настройка вашей LLM

API отдаёт сырьё: карточки актов, тематические блоки и подсказку формата _response_format_hint. Качество итогового ответа определяет системная инструкция вашей LLM. Ниже принципы для двух сценариев, не готовые промпты.

Сценарий A. Ответ в чате (обзор практики)

1. Один поиск, широкий limit. Достаточно одного вызова /v1/search с осмысленным запросом и limit 15–20: иерархия судов уже приходит блоками. Не дробите тему на запросы по каждому суду.
2. Передавайте модели _response_format_hint. Это встроенная директива формата, её учёт заметно приближает ответ к эталонному обзору.
3. Роль «справочник, а не советчик». Перечислять все релевантные акты по иерархии (приоритет КС, свежесть ВС, ВАС как история), без итоговой рекомендации и без выбора «единственно верной» позиции за пользователя.
4. Ссылки строго из поля url. Запретите конструировать адрес из id и удалять токен ?t=: без него ссылка не откроет текст.
5. Цитаты экономно. Дословные цитаты тяните через /v1/cases/{id} только у 3–5 ключевых актов. У КС нужная цитата уже в инлайн-поле position. Это главный источник лишних токенов.
6. Только из выдачи. Запретите достраивать практику по памяти: чего нет в ответе API, того «в базе нет».

Сценарий B. Составление каталога практики

Цель: подборка или список дел для выгрузки, без правового анализа.

1. Сначала сузьте фильтрами. Пусть модель уточнит тему и применит фильтры court / act_type / tag / article / year_from–year_to: каталог станет релевантным и компактным.
2. Сбор без анализа. Берите по каждому акту id, реквизиты (суд, тип, дата, № дела) и url. Не пересказывайте и не цитируйте акты в этом режиме.
3. Полнота через несколько запросов. Для широкой темы сделайте несколько /v1/search по подтемам, годам или судам и объедините результаты, отбросив дубли по id.
4. Отдавайте список, а не вывод. Результат режима: таблица или перечень со ссылками url, который пользователь отфильтрует сам.
5. Чёткое разделение режимов. Явно отделите этот режим от сценария A, чтобы модель не «съезжала» в развёрнутый анализ, когда просили подборку.