POST /api/v1/analyze

Analisa um texto em busca de sinais de condutas irregulares. O endpoint é stateless: cada requisição é independente e não armazena o texto enviado. O resultado é uma avaliação de risco que o chamador pode usar para tomar decisões de triagem ou escalonar para revisão jurídica.

Autenticação

Requer uma API key ativa com o escopo analyze:run.

Authorization: Bearer vario_SUA_API_KEY

A API key é gerada no portal de desenvolvedores. Para gerar ou rotacionar uma key, consulte Autenticação e API keys.

Rate limit

Consulte Erros e rate limits para os limites por tier e o comportamento do header Retry-After.

Corpo da requisição

Content-Type: application/json

Resposta

Content-Type: application/json · HTTP 200 OK

processing_path — comportamento do pipeline

O pipeline aplica gates de saída antecipada para evitar invocações desnecessárias. O campo processing_path identifica qual etapa produziu a resposta.

Resposta no modo screening

Quando mode é "screening", a resposta tem um schema diferente dos modos fast e full. Inclui apenas resultados da camada L1 (keyword + embedding). Os campos L2/L3 (combined_score, should_alert, severity, reasoning, etc.) não estão presentes.

Exemplo de resposta no modo screening:

{
  "mode_used": "screening",
  "l1_score": 0.82,
  "l1_keyword_score": 0.75,
  "l1_embedding_score": 0.82,
  "l1_matched_terms": ["combinamos não mexer no preço", "preço"],
  "l1_embedding_available": true,
  "playbook": "price_fixing",
  "playbook_version": "1.0",
  "pipeline_version": "1.0",
  "analyzed_at": "2026-06-04T10:15:00Z",
  "external_id": "email-msg-00842"
}

Comportamento em degradação

Se o serviço de análise profunda não estiver disponível, o endpoint responde com HTTP 200 e bedrock_available: false. Nesse caso, reasoning pode estar vazio e combined_score reflete apenas a análise local.

Se preferir receber um erro explícito em vez de uma resposta parcial, adicione o header:

Prefer: deep-analysis-required

Com esse header, o endpoint responde 503 DEEP_ANALYSIS_UNAVAILABLE quando a análise profunda não estiver disponível.

Exemplo completo

Requisição

curl -X POST https://api.vario.lat/v1/analyze \
  -H "Authorization: Bearer vario_SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Acordamos no bajar de $450 la unidad. Los demás van a hacer lo mismo esta semana.",
    "language": "es",
    "playbook": "price_fixing",
    "mode": "full",
    "thread_context": [
      "La reunión de ayer salió bien, creo que todos están alineados.",
      "Confirmo que el acuerdo sigue en pie para el trimestre."
    ],
    "external_id": "email-msg-00842"
  }'

Resposta

{
  "combined_score": 7.7,
  "should_alert": true,
  "severity": "critical",
  "reasoning": "El mensaje contiene una referencia directa a un precio acordado entre partes que actúan como competidores, con indicios de coordinación horizontal. El contexto del hilo refuerza la señal al mostrar continuidad de un acuerdo previo.",
  "key_phrases": [
    "no bajar de $450 la unidad",
    "los demás van a hacer lo mismo"
  ],
  "regulatory_frameworks": [
    "Lei 12.529/2011 Art. 36",
    "DL 211 Art. 3",
    "COFECE Lineamientos de colusión"
  ],
  "recommended_action": "legal_review",
  "confidence": "high",
  "mode_used": "full",
  "analyzed_at": "2026-06-02T18:45:00Z",
  "pipeline_version": "1.0",
  "bedrock_available": true,
  "external_id": "email-msg-00842"
}

Erros específicos deste endpoint

Para a referência completa de códigos de erro e rate limits, consulte Erros e rate limits.

Notas de uso

• Chunking: Para textos que excedam 8.000 caracteres, divida o conteúdo em fragmentos e envie uma requisição por fragmento. Use thread_context para passar o contexto do thread, não para fragmentar o campo text.
• Funil de três etapas: Quando o volume é alto, use mode: "screening" para descartar texto sem sinal L1 (1 crédito), mode: "fast" para os que superaram o limiar (2 créditos), e mode: "full" para os alertas reais (3 créditos). Veja Créditos e modos.
• Rastreabilidade: Use external_id para correlacionar cada resposta com o registro correspondente no seu sistema sem precisar armazenar o texto.
• O resultado não é uma determinação legal. O vario detecta sinais de risco; o CCO e a equipe jurídica avaliam e decidem.