FalaAI API — Usage manual: fields and flows

Overview

The FalaAI API is a set of independent APIs. You do not need to transcribe with FalaAI to diagnose or audit: if you already have the text, send it straight to the analysis (BYOT).

• Key: all routes require Authorization: Bearer fai_<your_key>, except GET/HEAD /v1/health and GET /api/version.
• Zero-storage (LGPD): audio/text/result are processed in memory and discarded.
• Languages: transcription in 31 languages; diagnosis in 21 locales; audit and HTML report in 3 (pt/en/es).

Authentication

What it is for: how to prove who you are on each call.

• Key: every route requires the header Authorization: Bearer fai_<your_key> — except GET/HEAD /v1/health and GET /api/version (public, no key).
• How to get it: create the account and generate the API Key in the Dashboard. The key is shown only once (show-once) — store it safely.
• Scopes: each key has scopes — transcribe, diagnostic, auditoria, whatsapp, alerts, billing, invoices (or * for all). A route without the required scope → 403 insufficient_scope.
• JWT: besides the fai_ key, the API accepts a session JWT on the same routes.

Authentication errors

Required fields — quick summary

If you just want it to work, these are the fields the API requires on each endpoint:

GET /v1/health public

What it is for: only to say whether the server is up and the version/uptime/database status. It analyzes nothing.

flowchart LR
  A[Monitor / uptime / curl] -->|GET /v1/health| B{{FalaAI API}}
  B -->|200| C[status, version, uptime, database]
  A2[Light check] -->|HEAD /v1/health| B
  B -->|200 without body| D[only the HTTP code]
  classDef pub fill:#dcfce7,stroke:#16a34a,color:#14532d
  classDef api fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
  class A,A2,C,D pub
  class B api

Fields

None.

Request (cURL example)

loading...

Response — fields

HEAD /v1/health = same 200 without body.

Example response (JSON)

loading...

Possible flows

• Uptime/monitoring (every 1 min) with an alert if != 200.
• Deploy health check (cheaper): HEAD.
• Read the API version for logging.

GET /api/version public

What it is for: identify the contract version in use (pin your client compatibility).

flowchart LR
  A[Your client / CI] -->|GET /api/version| B{{FalaAI API}}
  B --> C[contract version]
  C --> D[Pin/validate compatibility]
  classDef pub fill:#dcfce7,stroke:#16a34a,color:#14532d
  classDef api fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
  class A,C,D pub
  class B api

Fields

None.

Response

POST /v1/audio/transcriptions multipart/form-data

What it is for: turn audio into text with speaker separation (diarization), timestamps and audio events.

Fields

Request (cURL example)

loading...

Response — fields

Example response (JSON)

loading...

Flow

flowchart TD
  S([Do you have the audio?]) -->|yes| U[Choose the file: mp3, mp4, m4a, wav, flac, ogg, opus, webm, aac... up to 1GB / 3h]
  U --> T[POST /v1/audio/transcriptions + file]
  T --> R[Response: text, dialog, audio_events, duration_seconds, usage]
  R --> D1[Use in Diagnostic]
  R --> A1[Use in Risk Audit]
  R --> DB[(Your database / CRM / BI)]
  S -->|no, I already have text| B[Skip: go straight to Diagnostic or Risk Audit]
  classDef in fill:#e0f2fe,stroke:#0284c7,color:#0c4a6e
  classDef api fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
  classDef out fill:#f3e8ff,stroke:#7c3aed,color:#4c1d95
  class S,U,B in
  class T api
  class R,D1,A1,DB out

Possible flows

• Audio → transcription → diagnosis (summary, reason, action, topic, sentiment).
• Audio → transcription → risk audit (score + violations + report).
• Audio → transcription → (diagnosis + audit) on the same conversation.
• Batch: repeat per file in a queue and consolidate per account/team.

POST /v1/analyze/diagnostic application/json

What it is for: diagnose the conversation — 5 analyses in one call.

Fields

Request (cURL example)

loading...

Response — fields

Example response (JSON)

loading...

Flow

flowchart TD
  I{How do you have the conversation?} -->|plain transcription| X[text = running transcription + language]
  I -->|with who spoke| Y[dialog = turns with speaker and timestamps + language + duration_seconds]
  X --> P[POST /v1/analyze/diagnostic]
  Y --> P
  P --> R[summary, contact_reason, action_taken, topic, sentiment]
  R --> O1[Quality / CX dashboard]
  R --> O2[CRM / ticket / ERP]
  R --> O3[BI / warehouse]
  classDef in fill:#e0f2fe,stroke:#0284c7,color:#0c4a6e
  classDef api fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
  classDef out fill:#f3e8ff,stroke:#7c3aed,color:#4c1d95
  class I,X,Y in
  class P api
  class R,O1,O2,O3 out

Possible flows

• I already have a transcription (Whisper/Deepgram/own) → just diagnose (BYOT).
• Audio → transcription → diagnosis (full pipeline).
• Diagnosis + audit on the same conversation.
• Batch per conversation and aggregation by period/team (client_reference_id for tracking).

POST /v1/analyze/riskAudit application/json

What it is for: audit risk/compliance (COPC CX, ISO 18295-1, LGPD): score, detections/violations, evidence and an auditable HTML report.

Fields

Request (cURL example)

loading...

Response — fields (inside response)

Example response (JSON)

loading...

Flow

flowchart TD
  A{Do I already have the dialog?} -->|yes| P[POST /v1/analyze/riskAudit + dialog + duration_seconds + language + response_language]
  A -->|audio only| T[POST /v1/audio/transcriptions] --> P
  P --> R[risk score, detections, verdict, summary, usage]
  R --> V1[Auditable HTML report]
  R --> V2[Audit 100% of the conversations]
  R --> V3[Evidence for legal / dispute]
  R --> V4[Action plan per team]
  classDef in fill:#e0f2fe,stroke:#0284c7,color:#0c4a6e
  classDef api fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
  classDef out fill:#f3e8ff,stroke:#7c3aed,color:#4c1d95
  class A,T in
  class P api
  class R,V1,V2,V3,V4 out

Possible flows

• One-off audit: one conversation → score + violations + report.
• Batch audit (100%): all conversations of the day/week → ranking by risk.
• Audit + diagnosis for context (reason/action) together with the risk.
• Re-check after training (compare score before/after).

POST /v1/whatsapp/extractConversations multipart/form-data

What it is for: extract and segment conversations from a WhatsApp export (.zip/.txt) to then diagnose or audit.

Fields

Request (cURL example, per variant)

Preview (free)

loading...

Single window (extraction)

loading...

Multiple windows (extraction)

loading...

Response — fields

Example response (JSON, per variant)

Preview (free)

loading...

Single window (extraction)

loading...

Multiple windows (extraction)

loading...

Flow (with the 3 variants)

flowchart TD
  U[WhatsApp export: .zip or .txt] --> V{Choose the variant}
  V -->|free preview| P1[dry_run=true: returns LABELS and previews - does not extract the conversation]
  V -->|single window| P2[start + end define 1 window]
  V -->|multiple windows| P3[windows = JSON with several windows]
  P2 --> C[conversations: dialog, participants, messages, duration]
  P3 --> C
  C --> J[Use as JSON transcription in the Playground]
  C --> D[POST /v1/analyze/diagnostic]
  C --> A[POST /v1/analyze/riskAudit]
  P1 --> L[Check volume/labels before spending credits]
  L --> V
  classDef in fill:#e0f2fe,stroke:#0284c7,color:#0c4a6e
  classDef api fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
  classDef prev fill:#fef9c3,stroke:#ca8a04,color:#713f12
  classDef out fill:#f3e8ff,stroke:#7c3aed,color:#4c1d95
  class U,V in
  class P1,P2,P3 api
  class L prev
  class C,J,D,A out

Possible flows

• Check first (free): run dry_run=true to see how many conversations/labels exist and the credit estimate.
• Extract the whole conversation (start+end) → diagnose/audit.
• Extract multiple windows (windows) → diagnose/audit in batch.
• WhatsApp support → conversa extraida → auditoria de risco (compliance).

Combined flows (decision tree)

flowchart TD
  S([What do you have at hand?]) --> A{Audio?}
  A -->|yes| T[Transcription] --> Q{What do you want to know?}
  A -->|no, I have text| Q
  A -->|no, I have the WhatsApp export| W[Extract WhatsApp] --> Q
  Q -->|summary/reason/action/sentiment| D[Diagnostic]
  Q -->|risk/compliance/report| R[Risk Audit]
  Q -->|both| D2[Diagnostic + Risk Audit]
  D --> FIM([Typed JSON for your system])
  R --> FIM
  D2 --> FIM
  classDef in fill:#e0f2fe,stroke:#0284c7,color:#0c4a6e
  classDef api fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
  classDef out fill:#dcfce7,stroke:#16a34a,color:#14532d
  class S,W in
  class T,D,R,D2 api
  class Q,FIM out

Ready-made recipes

Alert webhooks

What it is for: receive subscription/billing/credit notices on your own HTTPS endpoint, without polling the API.

Endpoints

Events (10)

• subscription.created · avulso.completed · subscription.upgraded · subscription.downgraded · subscription.canceled
• credits.low · credits.exhausted · subscription.renewed · subscription.expired · payment.failed

Payload (example)

{
  "event": "credits.low",
  "data": { "balance_monthly": 12, "balance_avulso": 0, "total": 12, "plan": "starter_api", "plan_name": "Starter API - 90K" },
  "timestamp": 1725470000.123
}

Delivery and security

• Signature: every delivery carries the header FalaAI-Signature: t=<unix>,v0=<hmac_sha256(secret, "<t>.<raw body>")>. Validate by recomputing the HMAC with your secret and comparing it with v0; reject if t is outside the tolerance window (anti-replay).
• Retry: retry_enabled=false = 1 attempt; true = up to 5 (backoff 2^attempt: 1s, 2s, 4s, 8s). HTTP timeout of 10s per delivery; a response < 500 counts as delivered; after 5 consecutive failures the subscription is auto-disabled (active=false).

Errors

Limits and common errors

• 401: key missing/invalid (Authorization: Bearer fai_...).
• 402 / credits: insufficient balance for the operation.
• 413 / limit: file above 1 GB (or audio above 3 h).
• 422: required field missing or invalid format (e.g. audit without dialog; WhatsApp without timezone/date_format).
• Public without key: only GET/HEAD /v1/health and GET /api/version.

Full contract: Swagger · openapi.json · Quickstart · Playground