Referência da Citare API

Toda requisição leva a sua chave no header X-API-Key. Gere chaves no painel — ck_live_… para produção, ck_test_… para desenvolvimento (mesma conta e saldo, tráfego separado nos relatórios).

A chave é exibida uma única vez na criação. Guarde-a em variável de ambiente; nunca a exponha em código de navegador.

# URL base
https://justia-ia-production.up.railway.app

# Header obrigatório em toda chamada
X-API-Key: ck_live_SEU_SEGREDO

A cobrança é por consumo, em créditos pré-pagos que não expiram:

Requisições que falham por validação (422), documento inexistente (404) ou saldo insuficiente (402) não debitam créditos. Erro interno nosso (500) estorna automaticamente.

Busca semântica: descreva a tese em linguagem natural. Filtros opcionais estreitam o resultado; a ementa vem resumida (até 400 caracteres) — o documento completo sai pelo endpoint de documento.

curl -X POST https://justia-ia-production.up.railway.app/v1/juris/busca \
  -H "X-API-Key: ck_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "consulta": "dano moral por inscrição indevida em cadastro de inadimplentes",
    "tribunais": ["STJ", "TJSP"],
    "materias": ["Direito do Consumidor"],
    "dispositivo": "provido",
    "limite": 10
  }'

Resposta 200:

{
  "creditosDebitados": 1,
  "creditosRestantes": 9999,
  "total": 10,
  "resultados": [
    {
      "id": "8f1c9e2a-4b7d-4e2f-9c1a-…",
      "tribunal": "STJ",
      "classe": "AgInt no AREsp",
      "numero": "2104531/SP",
      "relator": "Min. Nancy Andrighi",
      "dataJulgamento": "2024-03-12",
      "materia": "Direito do Consumidor",
      "dispositivo": "provido",
      "ementaResumo": "AGRAVO INTERNO… (resumo de até 400 caracteres)",
      "similaridade": 0.9123
    }
  ]
}

Um acórdão pelo id retornado na busca: metadados completos, a ementa integral e o link do inteiro teor no portal oficial do tribunal.

curl https://justia-ia-production.up.railway.app/v1/juris/documento/8f1c9e2a-4b7d-4e2f-9c1a-… \
  -H "X-API-Key: ck_live_…"

Resposta 200:

{
  "creditosDebitados": 2,
  "creditosRestantes": 9997,
  "documento": {
    "id": "8f1c9e2a-…",
    "tribunal": "STJ",
    "classe": "AgInt no AREsp",
    "numero": "2104531/SP",
    "relator": "Min. Nancy Andrighi",
    "dataJulgamento": "2024-03-12",
    "materia": "Direito do Consumidor",
    "dispositivo": "provido",
    "ementa": "… (ementa integral)",
    "urlFonte": "https://processo.stj.jus.br/…"
  }
}

id inválido ou inexistente → 404, sem débito.

Jurimetria agregada da base inteira: volume por tribunal, composição do resultado (providos/parciais/improvidos), matérias mais frequentes e relatores com mais acórdãos. Só agregados — nenhum documento individual. Ideal para dashboards e análises de mercado. ?tribunal=TJSP filtra um tribunal.

curl "https://justia-ia-production.up.railway.app/v1/juris/estatisticas?tribunal=TJSP" \
  -H "X-API-Key: ck_live_…"

{
  "creditosDebitados": 1,
  "creditosRestantes": 9996,
  "atualizadoEm": "2026-07-19T18:00:00.000Z",
  "totalAcordaos": 3120450,
  "tribunais": [
    {
      "tribunal": "TJSP",
      "total": 41200,
      "provido": 14800, "parcial": 6100, "improvido": 17300,
      "extinto": 900, "outros": 2100,
      "topMaterias": [{ "materia": "Direito do Consumidor", "total": 9800 }],
      "topRelatores": [{ "relator": "Des. …", "total": 1250, "providos": 480 }]
    }
  ]
}

Os agregados são recalculados a cada ~6 horas. Sem o filtro, a resposta traz todos os tribunais da base.

curl https://justia-ia-production.up.railway.app/v1/juris/saldo -H "X-API-Key: ck_live_…"

{
  "creditosRestantes": 9997,
  "ambiente": "live",
  "escopo": "juris"
}

Erros vêm como JSON com erro (código estável) e mensagem (texto em português):

Cada chave tem dois limites, visíveis no painel: 60 req/min e 10.000 req/dia (padrão — ajustável para contratos de volume). Excedeu → 429; espere e tente de novo. O teto protege a plataforma e o seu próprio custo contra loops acidentais.

• Cache do seu lado. O mesmo id devolve o mesmo documento — guarde e não pague duas vezes.
• Busque primeiro, detalhe depois. Mostre os resumos da busca ao seu usuário e só busque o documento (2 créditos) quando ele abrir o item.
• Trate 402 no fluxo. Monitore creditosRestantes nas respostas e avise seu time antes do saldo zerar.
• Uma chave por ambiente. ck_test_ em dev/homolog, ck_live_ em produção — revogar uma não afeta a outra.
• Respeite a fonte. O link do inteiro teor aponta o portal oficial do tribunal; exiba-o ao usuário final como referência verificável.