POST /api/v1/analyze

Analiza un texto en busca de señales de conductas irregulares. El endpoint es stateless: cada request es independiente y no almacena el texto enviado. El resultado es una evaluación de riesgo que el caller puede usar para tomar decisiones de triage o escalar a revisión legal.

Autenticación

Requiere una API key activa con el scope analyze:run.

Authorization: Bearer vario_TU_API_KEY

La API key se genera desde el portal de developers. Para generar o rotar una key, consulta Autenticación y API keys.

Rate limit

Ver Errores y rate limits para los límites por tier y el comportamiento del header Retry-After.

Request body

Content-Type: application/json

Response

Content-Type: application/json · HTTP 200 OK

processing_path — comportamiento del pipeline

El pipeline aplica gates de salida temprana para evitar invocaciones innecesarias. El campo processing_path identifica qué etapa produjo la respuesta.

Response en modo screening

Cuando mode es "screening", el response tiene un schema distinto al de los modos fast y full. Solo incluye los resultados de la capa L1 (keyword + embedding). Los campos L2/L3 (combined_score, should_alert, severity, reasoning, etc.) no están presentes.

Ejemplo de response en modo screening:

{
  "mode_used": "screening",
  "l1_score": 0.82,
  "l1_keyword_score": 0.75,
  "l1_embedding_score": 0.82,
  "l1_matched_terms": ["acordamos no movernos del precio", "precio"],
  "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"
}

Comportamiento en degradación

Si el servicio de análisis profundo no está disponible, el endpoint responde con HTTP 200 y bedrock_available: false. En ese caso, reasoning puede ser vacío y combined_score refleja únicamente el análisis local.

Si prefieres recibir un error explícito en lugar de un response parcial, agrega el header:

Prefer: deep-analysis-required

Con este header, el endpoint responde 503 DEEP_ANALYSIS_UNAVAILABLE cuando el análisis profundo no está disponible.

Ejemplo completo

Request

curl -X POST https://api.vario.lat/v1/analyze \
  -H "Authorization: Bearer vario_TU_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"
  }'

Response

{
  "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"
}

Errores específicos de este endpoint

Para la referencia completa de códigos de error y rate limits, consulta Errores y rate limits.

Notas de uso

• Chunking: Para textos que superen 8.000 caracteres, divide el contenido en fragmentos y envía un request por fragmento. Usa thread_context para pasar el contexto del hilo, no para fragmentar el campo text.
• Funnel de tres etapas: Cuando el volumen es alto, usa mode: "screening" para descartar texto sin señal L1 (1 crédito), mode: "fast" sobre los que superaron el umbral (2 créditos), y mode: "full" para las alertas reales (3 créditos). Ver Créditos y modos.
• Trazabilidad: Usa external_id para correlacionar cada response con el registro correspondiente en tu sistema sin necesidad de almacenar el texto.
• El resultado no es una determinación legal. vario detecta señales de riesgo; el CCO y el equipo legal evalúan y deciden.