API Reference
Base path: /v1. Interactive schema: /docs (Swagger) and /openapi.json.
Every endpoint below is checked by
backend/tests/test_docs.py. Adding a route without documenting it here fails the test suite.
Auth: none in local mode. Set API_KEYS=key1,key2 and review routes require X-API-Key. All endpoints are rate limited (RATE_LIMIT_REQUESTS per RATE_LIMIT_WINDOW_SECONDS, per key or client IP) and return 429 when exceeded.
Analysis
POST /v1/analyze/message
Analyze one message through the full pipeline.
// request
{
"text": "URGENT: Your bank account is locked, verify at http://fake.top",
"source_type": "sms", // sms | email | chat | call_transcript | social | other
"source_app": "ios",
"sender": "+971501234567", // optional
"locale": "ar-AE", // optional; text wins if it contradicts
"user_consent_online_checks": false // opt in to third-party lookups
}
// response (abridged)
{
"analysis_id": "uuid",
"risk_score": 0.92, // RISK INDEX, not a probability
"risk_level": "scam", // safe | suspicious | likely_scam | scam
"category": "bank_impersonation",
"explanation": "Matched 2 scam patterns: …",
"recommended_action": "This is almost certainly a scam. …",
"matched_rules": [{ "id": "otp-share-request", "description": "…", "weight": 0.9 }],
"urls": [{ "domain": "fake.top", "suspicious": true, "reasons": ["high-abuse TLD .top"] }],
"verification": { "claims": [{ "status": "contradicted", "is_claim": true, "evidence": ["…"] }] },
"detected_language": "en",
"coverage": "full", // full | limited | none
"coverage_note": null, // non-null => the verdict has known blind spots
"processing": {
"local_stages": ["redaction", "rule engine", "URL heuristics", "identity checks (local registry)"],
"external_stages": [],
"external_consented": false
},
"review_status": "auto"
}
Client contract: if coverage != "full", a low risk_score is not evidence of safety — surface coverage_note prominently. Never render risk_score as a percentage likelihood; it is an uncalibrated index.
POST /v1/analyze/batch
Up to 50 messages in one round trip (mobile SMS-filter queues). Items are independent; a failure returns error for that index without failing the batch.
{ "messages": [ { "text": "…", "source_type": "sms", "source_app": "ios" } ] }
// → { "results": [ { "index": 0, "analysis": {…}, "error": null } ] }
POST /v1/analyze/voice
multipart/form-data: file (audio), optional sender, locale. Transcribes locally with faster-whisper, deletes the audio immediately, then analyzes.
Returns { "transcript": "...", "analysis": {…} }.
Errors: 503 transcription not installed · 415 unsupported type · 413 too large or too long · 504 transcription timeout · 422 no speech detected.
Live call
Real-time analysis of an in-progress call. See architecture.md for the interim/final design.
POST /v1/call/start
{ "caller_id": "+971501234567", "locale": "en-US", "online_checks": false } → { "call_id": "uuid" }
caller_id starts the caller check at once — the number's kind, the registry and community reports. online_checks: true also lets it search the web for the number (only where the operator set WEB_INTEL_ENABLED=true; see features.caller_web_check). Off by default: it sends the number to a search engine.
POST /v1/call/{call_id}/chunk
{ "text": "…", "commit": true }
commit: false = interim STT hypothesis while the caller is still speaking: analyzed for instant alerts, not appended to the transcript.
Returns LiveCallStatus:
{
"risk_score": 0.98, "risk_level": "scam",
"should_warn": true,
"alert_level": "critical", // what fired NEW on this response (deduplicated)
"severity": "critical", // none | warn | critical — the CURRENT state, on every response
"alerts": ["HANG UP: this number is not verified as Emirates NBD AND …"],
"claims": [ { "entity_name": "Emirates NBD", "status": "contradicted", "is_claim": true } ],
"matched_rules": [...], "transcript_chars": 142,
"coverage": "full", "coverage_note": null,
"caller_check": {
"status": "done", // running while web agents are still out
"number": "+971 52 999 0000", "number_kind": "uae_mobile",
"claimed_entity": "First Abu Dhabi Bank",
"verdict": "wrong_kind", // reported | not_official | wrong_kind | official | unverified | no_record | no_number
"headline": "The caller says they are First Abu Dhabi Bank, but this is a UAE personal mobile number.",
"evidence": [ { "source": "number_format", "outcome": "contradicts", "detail": "…", "url": null } ],
"external_lookups": [] // what left this machine, and to whom
}
}
caller_check.verdict == "official" is information, never reassurance: it does not lower the score (caller ID can be faked).
Each indicator fires once per session: should_warn and alert_level describe only what is new on this response. Don't build the alarm on them alone — if that one response is lost or arrives late, nothing later repeats it, and the warning is never shown. Instead, keep every alert line you have seen this call, alarm when a new one appears, and take the intensity from severity, which reports the current state on every response. The web client does this (updateCall in clients/web/index.html); should_warn remains for older clients.
POST /v1/call/{call_id}/assess
Runs the LLM over a trailing window of the transcript. Seconds, not milliseconds — throttle it and never block /chunk on it. Returns LiveCallStatus with llm_score and llm_reasoning.
POST /v1/call/{call_id}/cancel
Abandon without analysis and purge the transcript immediately. Call this on app background / page unload so raw speech is never retained.
POST /v1/call/{call_id}/end
Ends the session and runs the full pipeline over the whole transcript. Returns an AnalyzeMessageResponse.
GET /v1/call/{call_id}/status
The current LiveCallStatus without new speech. The caller check's web agents finish in the background; poll this (the web client uses 1.2 s) while caller_check.status is "running", so the result — and any alarm — arrives even when nobody is talking.
POST /v1/call/{call_id}/caller
{ "caller_id": "050 999 0000", "online_checks": false } → LiveCallStatus. Type or correct the number mid-call; the caller check restarts for it.
Caller check
POST /v1/caller/check
Check a number outside a call, optionally against the organisation the caller claimed (an id from rules/known_entities.yaml):
{ "caller_id": "0501234567", "claimed_entity": "emirates_nbd", "online_checks": false }
Returns the caller_check object above. 422 for an unknown organisation id. Web lookups need both online_checks and the operator's switch. Design, safety and the evidence store: caller-check.md.
Sync (on-device)
GET /v1/rules/pack
The deterministic tier, for offline evaluation in contexts with no network (iOS ILMessageFilterExtension).
Send If-None-Match: <etag> or ?since_version=<rules_version> → 304 when unchanged. Response includes rules, entities, and scoring (floors and level thresholds) so on-device scores match the server exactly.
Query region=AE to receive only globally-applicable plus AE-scoped indicators.
The response carries a serial (monotonic) and, when the deployment signs packs, a signature envelope. Clients that require signing must verify before activating and fail closed to the previously trusted pack — see intelligence-sync.md.
Do not hand-write rules on the client. Everything comes from this endpoint; that is what keeps the platforms from drifting.
Call-only rules are not in the pack. Rules with channels: [call] judge live calls and call transcripts on the server; the pack feeds the on-device SMS engines, where they would fire on every genuine bank text that mentions an OTP. Message analysis with source_type: "call_transcript" is judged as a call.
GET /v1/rules/delta?since_serial=41®ion=AE
Incremental update for a device that already holds a pack. Threat indicators change hourly; rules rarely do, so sending the whole pack every time wastes mobile bandwidth and battery.
{
"from_serial": 41, "to_serial": 57,
"full_resync_required": false, // true => rules/scoring changed, fetch the full pack
"added_indicators": [ { "id": "…", "kind": "domain", "value": "enbd-secure.top",
"source": "human_verified", "confidence": 1.0,
"regions": ["AE"], "expires_at": "2027-01-01T00:00:00Z" } ],
"removed_indicator_ids": ["ind_123"],
"rules_changed": false, "entities_changed": false, "scoring_changed": false
}
An expired indicator is not silently dropped — it stops contributing to the score but remains visible for explanation and audit, so a device never becomes quietly less protective without a signal.
Community
POST /v1/report
Anonymous scam report. Only description is required — a real reporter rarely has every detail, and a form that demands them collects nothing.
{
"description": "Called claiming to be my bank, asked for the code they texted me", // required
"website": "http://enbd-verify.top", // all optional below here
"person_name": "…", "organisation": "…",
"email": "…", "phone": "+9715…",
"bank_sort_code": "…", "bank_account": "…", // the SCAMMER's details
"occurred_on": "2026-08-28", "location": "Dubai",
"channel": "call", "amount_lost": "0"
}
// → { "report_id": "uuid", "received": true, "message": "…",
// "analysis_preview": { "risk_level": "scam", "risk_score": 0.92, "explanation": "…" } }
The description is redacted before storage — reporters routinely paste their own card numbers while explaining what happened. If the report contains anything checkable, the engine's verdict comes back in analysis_preview so the reporter gets an answer rather than only a thank-you.
The scammer's banking details are collected deliberately: that is the part a bank or police force can act on.
GET /v1/alerts?limit=20®ion=AE
Current scam campaigns, newest first.
{
"alerts": [{
"id": "alert-otp-callback",
"title": "Callers posing as bank fraud teams asking for one-time codes",
"summary": "…",
"category": "otp_phishing", "severity": "high",
"regions": ["AE"],
"source_name": "UAE Central Bank consumer guidance",
"source_url": "https://…",
"published_at": "2026-08-28T…"
}],
"count": 1
}
is_fixture_feed: true means the feed is still placeholder content — clients must not present it as live campaigns. Each item carries is_fixture too.
Every alert cites a primary source. An unsourced warning is a rumour, and this product's value is being the thing a worried person can trust — the store rejects an alert without a source_url.
Chat
POST /v1/chat
Scam-advisor Q&A. Verdict context is optional — users can describe any incident they remember.
{
"question": "Was this a scam?",
"message_text": "", // optional analyzed text
"verdict_summary": "", // optional engine verdict
"history": [{ "role": "user", "content": "…" }]
}
// → { "answer": "…", "llm_used": true }
// response
{
"answer": "…",
"llm_used": true,
"llm_state": "ready", // ready | disabled | unreachable | model_missing | error
"grounded": true, // false => model spoke from general knowledge
"citations": [{ "name": "UAE Central Bank consumer guidance", "url": "https://…" }]
}
Grounded, not free-associating. Before the model sees a question, the server retrieves facts that bear on it from sources it controls: the verified entity registry (official domains, sender IDs, phone numbers), the alerts feed (each carrying a primary-source URL), and community-report corroboration counts. The model explains those facts; it does not supply them.
This matters because a confabulated "official" bank phone number is the worst failure this product could produce — the user would call it. If the question asks for an authoritative contact detail and nothing verified backs it, the answer is explicitly qualified.
All user text is redacted before reaching the model. When AI is unavailable, llm_used: false and llm_state says which of the five states applies, with an actionable remedy in answer — clients must still show the deterministic explanation from the analysis response.
GET /v1/llm/status
Exactly why AI features are or are not available.
{
"state": "model_missing", "ready": false,
"model": "qwen3:8b",
"detail": "Ollama is running, but 'qwen3:8b' is not installed. Installed: llama3.2:3b.",
"remedy": "Run `ollama pull qwen3:8b` — or set OLLAMA_MODEL to one you already have.",
"models_present": ["llama3.2:3b"],
"is_local": true, // false => the 'processed on this machine' claim is untrue
"last_error": null
}
Exists because "the server answered" was being reported as "the AI works": with Ollama up but the model never pulled, the UI promised explanations and then failed on every request.
POST /v1/feedback
Anonymous "this verdict looks wrong".
{ "analysis_id": "uuid", "expected": "scam" | "legitimate" | "unsure", "note": "…",
"shared_text": "…", // optional: the message itself, only with consent
"share_consent": false } // must be true or shared_text is discarded unread
// → { "received": true, "message": "…" }
Why shared_text exists. Checks never store message text, so a "you missed this scam" report says that the engine missed but not what — there is nothing to write a rule from. The reporter may opt in, per submission, to share the message. It is redacted before storage like everything else, and the server ignores it unless share_consent is true.
Deliberately separate from POST /v1/review/{analysis_id}/label. That endpoint sets ground truth and is authenticated. The web UI used to post directly into it, which meant anonymous visitors could write ground truth whenever auth was off, and the button broke outright when auth was on. Public feedback is a signal that something deserves a reviewer's attention — not the verdict itself. Notes are redacted before storage.
Review (human tier)
GET /v1/review/queue?limit=50
Gray-zone verdicts (score 0.40–0.75) awaiting a human label. Metadata only — never message content. limit is 1–200. Requires X-API-Key when configured.
POST /v1/review/{analysis_id}/label
{ "label": "scam" | "legitimate" | "unsure", "notes": "…" }
These labels are the ground truth for tuning rules and weights. Requires X-API-Key when configured; each call is audit-logged without message content.
System
GET /v1/capabilities
features.caller_web_check is true when the caller check may search the web (the operator enabled it and a search back end is configured); clients show the per-call consent box only then.
Feature detection for clients — call on launch instead of assuming.
{
"api_version": "v1", "rules_version": "2026.11.12-1",
"features": { "voice_upload": true, "ai_explanations": false,
"online_reputation_checks": false, "rules_pack_sync": true, … },
"language_coverage": { "en": "full", "ar": "full" },
"limits": { "max_text_chars": 20000, "max_batch_messages": 50, … },
"auth_required": false,
"contact_email": "hello@example.org" // PUBLIC_CONTACT_EMAIL, or null
}
contact_email is what the web client's Privacy and Terms pages display. It is null until PUBLIC_CONTACT_EMAIL is set — and python -m app.ops check fails until it is.
GET /v1/health
Liveness plus runtime state: rules_loaded, llm_available, stt_available, external_checks_enabled, auth_required, active_sessions (aggregate only).