Quickstart — getting started with the vario API

This guide takes you from zero to your first text analysis in under 5 minutes. By the end you will have registered an account, queried the available playbooks, sent an analysis request, and interpreted the response.

Base URL: https://api.vario.lat/v1 Authentication: Authorization: Bearer vario_YOUR_API_KEY

Step 1 — Register an API account

Create an API-only account with welcome credits. No credit card required.

curl -X POST https://api.vario.lat/api/public/api-signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "name": "Your Name",
    "organization": "Your Organization"
  }'

Response 201:

{
  "key": "vario_xbGhABC123...WXYZ",
  "warning": "Store this key immediately. It cannot be recovered — only revoked and replaced.",
  "free_credits": 250,
  "call_cost_screening": 1,
  "call_cost_fast": 2,
  "call_cost_full": 3,
  "docs_note": "$0.150 per credit. Pricing is subject to change."
}

The initial balance is 250 free credits, enough to explore all modes and playbooks.

Common errors at this step:

Step 2 — Query available playbooks

List the conduct types you can detect and the languages supported by each one.

curl https://api.vario.lat/v1/playbooks \
  -H "Authorization: Bearer vario_YOUR_API_KEY"

Response 200:

{
  "playbooks": [
    {
      "conduct_type": "price_fixing",
      "languages": ["es", "pt"],
      "version": "1.0"
    },
    {
      "conduct_type": "bid_rigging",
      "languages": ["es"],
      "version": "1.0"
    },
    {
      "conduct_type": "bribery",
      "languages": ["es", "pt"],
      "version": "1.0"
    },
    {
      "conduct_type": "market_manipulation",
      "languages": ["es"],
      "version": "1.0"
    }
  ]
}

Use the conduct_type value in the playbook field of the next step. The language field accepts the ISO 639-1 codes listed by each playbook.

Step 3 — Analyze a text

Send a text for analysis. vario does not store or retain the analyzed text — each request is stateless.

curl -X POST https://api.vario.lat/v1/analyze \
  -H "Authorization: Bearer vario_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Acordamos mantener los precios en $X este trimestre",
    "language": "es",
    "playbook": "price_fixing",
    "mode": "fast"
  }'

Request parameters:

Response 200:

{
  "combined_score": 6.8,
  "should_alert": true,
  "severity": "high",
  "reasoning": "El mensaje contiene una referencia explícita a un acuerdo de precios entre competidores. El uso de 'acordamos' en primera persona plural y la mención de un precio fijo para un período específico son señales consistentes con coordinación de precios.",
  "key_phrases": [
    "Acordamos mantener los precios",
    "$X este trimestre"
  ],
  "regulatory_frameworks": [
    "Ley de Defensa de la Competencia (Chile, DL 211)",
    "Lei 12.529/2011 (CADE, Brasil)",
    "COFECE — Ley Federal de Competencia Económica (México)"
  ],
  "recommended_action": "legal_review",
  "confidence": "high",
  "mode_used": "fast",
  "analyzed_at": "2026-06-02T14:32:00Z",
  "pipeline_version": "1.0",
  "bedrock_available": true
}

Step 4 — Interpret the result

combined_score

A number on a scale from 0 to 10. The higher the value, the greater the detected risk. Use it to prioritize when processing high volumes of text.

should_alert

Boolean. true indicates the analysis exceeded the risk threshold configured for the playbook. In most workflows, this field is the primary trigger for your escalation logic.

severity

Categorical with four levels:

reasoning

Explanatory text describing the risk factors identified in the message. Useful for a human reviewer to understand why the system generated the alert without needing to go back to the original text.

recommended_action

Suggested action for the compliance team. Available values depend on the analysis mode:

bedrock_available

If this field returns false, the analysis was partial: the assisted analysis layer was not available at that moment. You can retry the request or add the header Prefer: deep-analysis-required to receive an explicit 503 error instead of a partial response.

Tip — free playground

Before integrating the API into your system, you can test requests directly from the portal. The playground includes 5 free analyses per day that do not consume production credits, with immediate visualization of the complete response.

Next steps

• POST /analyze — complete reference for the analysis endpoint.
• GET /playbooks — list of available conducts.
• Credits & modes — three-stage funnel (screening → fast → full) to optimize costs.
• screening mode — for mass corpus sweep, use "mode": "screening" (1 credit, different L1 schema).
• full mode — for deeper analysis, use "mode": "full" (3 credits, full reasoning).
• thread_context — if you have access to the email thread, pass the previous messages in the thread_context array to improve analysis accuracy (only effective in fast and full modes).