POST /api/v1/analyze

Analyzes a text for signals of irregular conduct. The endpoint is stateless: each request is independent and does not store the submitted text. The result is a risk assessment that the caller can use to make triage decisions or escalate to legal review.

Authentication

Requires an active API key with the analyze:run scope.

Authorization: Bearer vario_YOUR_API_KEY

The API key is generated from the developer portal. To generate or rotate a key, see Authentication & API keys.

Rate limit

See Errors & rate limits for per-tier limits and the behavior of the Retry-After header.

Request body

Content-Type: application/json

Response

Content-Type: application/json · HTTP 200 OK

processing_path — pipeline behavior

The pipeline applies early-exit gates to avoid unnecessary invocations. The processing_path field identifies which stage produced the response.

Response in screening mode

When mode is "screening", the response has a different schema from fast and full modes. It only includes L1 layer results (keyword + embedding). The L2/L3 fields (combined_score, should_alert, severity, reasoning, etc.) are not present.

Example response in screening mode:

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

Degradation behavior

If the deep analysis service is not available, the endpoint responds with HTTP 200 and bedrock_available: false. In that case, reasoning may be empty and combined_score reflects only the local analysis.

If you prefer to receive an explicit error instead of a partial response, add the header:

Prefer: deep-analysis-required

With this header, the endpoint responds 503 DEEP_ANALYSIS_UNAVAILABLE when deep analysis is not available.

Complete example

Request

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

Errors specific to this endpoint

For the complete reference of error codes and rate limits, see Errors & rate limits.

Usage notes

• Chunking: For texts exceeding 8,000 characters, split the content into fragments and send one request per fragment. Use thread_context to pass thread context, not to fragment the text field.
• Three-stage funnel: When volume is high, use mode: "screening" to discard text without L1 signal (1 credit), mode: "fast" for those that pass the threshold (2 credits), and mode: "full" for real alerts (3 credits). See Credits & modes.
• Traceability: Use external_id to correlate each response with the corresponding record in your system without needing to store the text.
• The result is not a legal determination. vario detects risk signals; the CCO and legal team evaluate and decide.