---
title: "Busca textual (BM25) ou híbrida (BM25 + kNN e5 + rerank)"
method: GET
path: "/api/v1/busca"
tags: ["Busca"]
---

# Busca textual (BM25) ou híbrida (BM25 + kNN e5 + rerank)

`GET /api/v1/busca`

## Request

- Base URL: `https://api.ragjur.ai`
- URL: `https://api.ragjur.ai/api/v1/busca`
- Auth: one of:
  - API key in header `x-api-key`
  - OAuth 2 (authorization code, authorization URL `https://mcp.ragjur.ai/oauth/authorize`, token URL `https://mcp.ragjur.ai/oauth/token`, scopes: `ragjur:read`)

Busca em ~62M julgados. 50 resultados por página. Por padrão exclui decisões-stub (`word_count < 10`) e deduplica ementas quase idênticas.

`modo=hibrido` funde BM25 com kNN sobre `embedding_e5` (RRF) e reordena o topo com cross-encoder; se o serviço de embeddings estiver indisponível, responde só BM25 com `embedding_fallback: "bm25"`.

Correção ortográfica automática: `sugestao` traz a query corrigida quando aplicável.

Se `q` inteira for um número de processo — CNJ (`0703333-12.2026.8.07.0009`, com ou sem máscara) ou sigla de superior + número (`REsp 1842871`, `HC 773186`) — a busca vira filtro exato em `numero_processo` (`busca_processo: "cnj" | "superior"`); zero acertos recai na busca textual (número citado em ementa).

## Query parameters

- `q` string, required
- `fonte` string
- `tribunal` string
- `turma` string
- `relator` string
- `classe` string
- `dataInicio` string, date
- `dataFim` string, date
- `data_julg_de` string, date
- `data_julg_ate` string, date
- `pagina` integer
- `modo` 'hibrido'
- `dedup` 'true' | 'false'
- `incluir_stubs` 'true' | 'false'

## Response `200`

Página de resultados

- object
  - `total` integer, required: Total de documentos que casam (antes da paginação)
  - `pagina` integer, required
  - `totalPaginas` integer, required
  - `resultados` Julgado[], required
    - `score` number
    - `rrf_score` number: Só em `modo=hibrido`
    - `rerank_score` number: Só em `modo=hibrido` com rerank ativo
    - `vector_similarity` number: Só em `modo=hibrido` (0–100)
    - `fonte` string
    - `tribunal` string
    - `numero_processo` string
    - `classe` string
    - `relator` string
    - `orgao_julgador` string
    - `data_julgamento` string, date
    - `data_publicacao` string, date
    - `titulo` string
    - `ementa` string
    - `url` string, uri
    - `highlight` object
      - `ementa` string[]
  - `relaxed` boolean: Consulta relaxada (menos termos obrigatórios) por escassez de resultados
  - `busca_processo` 'cnj' | 'superior': `q` interpretada como número de processo — filtro exato em `numero_processo`
  - `modo` 'hibrido'
  - `rerank` boolean
  - `embedding_fallback` 'bm25'
  - `incluir_stubs` boolean
  - `deduplicados` integer
  - `sugestao` string: Correção ortográfica sugerida/aplicada
  - `turmas` Contagem[]
    - `key` string
    - `count` integer
  - `relatores` Contagem[]
    - `key` string
    - `count` integer
  - `tribunais` Contagem[]
    - `key` string
    - `count` integer

## Other responses

- `400`: Parâmetro obrigatório ausente ou inválido
- `401`: Sem `x-api-key` ou chave inválida
- `403`: Chave desativada
- `429`: Rate limit excedido (janela deslizante por chave). Ver `Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`.
- `500`: Erro interno

---

[API](https://skmtc.dev/ragjur/apis/ragjur-api.md) · [All operations](https://skmtc.dev/ragjur/apis/ragjur-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ragjur/apis/ragjur-api/revisions/448e3f75cc15?raw)