Cuvark

API docs

Cuvark accepts workflow context, extracts evidence, runs cheap checks first, and returns a schema-valid scam risk verdict.

Getting started

Choose direct scoring, case enrichment, or shadow mode.

Open
API guide

Direct scans, case flow, async mode, and auth scopes.

Open
Security model

Dashboard auth, machine API auth, hostile evidence, and retention.

Open
Simple scan API
POST /v1/scans
Content-Type: application/json

{
  "submission": { "type": "booking", "source": "custom_integration" },
  "scanned_actor": { "name": "John", "email": "support-dhl@gmail.com" },
  "evidence": {
    "message": "Please verify your account here before our call.",
    "links": ["https://example.com"],
    "attachments": []
  },
  "context": { "expected_payment": false, "known_customer": false },
  "processing": { "mode": "sync", "decision_mode": "enforce", "inspection": "auto" }
}
Advanced case flow
POST /v1/cases
POST /v1/cases/{case_id}/evidence-items
POST /v1/cases/{case_id}/scans
GET  /v1/cases/{case_id}
POST /v1/cases/{case_id}/feedback
DELETE /v1/cases/{case_id}
Queued scoring
POST /v1/scans
{
  "submission": { "type": "booking", "source": "custom_integration" },
  "scanned_actor": {},
  "evidence": { "message": "...", "links": [] },
  "processing": { "mode": "async", "lane": "browser", "inspection": "auto" }
}

GET /v1/scans/{scan_id}

With Redis, lane: "score" is processed by the score worker and lane: "browser" is processed by the browser-worker service. Without Redis, the job API falls back to inline local scoring.

Machine auth and webhooks
Authorization: Bearer ck_dev_...

X-Cuvark-Signature: t=1781700000,v1=<hmac_sha256(timestamp + "." + payload)>

Webhook event:
{
  "event": "case.scored",
  "case_id": "case_...",
  "verdict": {
    "trust_score": 18,
    "verdict": "block",
    "reason_codes": ["credential_harvesting"]
  }
}

API keys carry explicit scopes: score:write, cases:read, cases:write, cases:delete, and feedback:write.

Output contract
{
  "case_id": "case_...",
  "trust_score": 18,
  "risk_level": "high",
  "verdict": "block",
  "confidence": "high",
  "reason_codes": ["brand_impersonation", "credential_harvesting"],
  "recommended_action": "hold_for_review",
  "decision_mode": "enforce",
  "effective_action": "hold_for_review",
  "would_have_recommended_action": null,
  "evidence_summary": "...",
  "evidence": {},
  "processing": {
    "latency_ms": 740,
    "cost_tier": "medium",
    "estimated_cost_units": 5
  }
}
Shadow mode
{
  "options": {
    "decision_mode": "shadow"
  }
}

Shadow mode computes and stores the verdict but sets effective_action to allow, moving the enforcement recommendation to would_have_recommended_action.

Context fields with highest impact

FieldImpactWhy it matters
submission.typeHighBooking, form, chat, and URL-only scans have different risk expectations.
scanned_actor.emailHighEnables sender-domain and brand-claim mismatch detection.
messageHighExposes urgency, payment, credential, off-platform, and prompt-injection signals.
conversation.messagesHighPreserves chronology for off-platform migration, escalation, and key risky turns.
attachmentsHigh if presentImages, QR codes, documents, archives, and executable files often carry the risky payload.

Reason code glossary

known_malicious_urlthreat_feed_hitprior_blocked_urlnew_domainnewly_observed_urlunobservable_urlexternal_document_linkunreachable_external_document_linksuspicious_tldurl_obfuscationrisky_hosting_asnredirect_chain_suspicioushomograph_domaintypo_squattingbrand_mismatchbrand_impersonationclaimed_company_mismatchemail_domain_mismatchdisposable_emailcredential_harvestinglogin_form_detectedpassword_field_detectedpayment_requestunexpected_payment_requestcrypto_payment_requestgift_card_requestbank_transfer_requestqr_code_url_detectedqr_phishing_riskfake_invoice_patternfake_receipt_patternexecutable_attachmentmacro_enabled_documentarchive_attachment_riskmalicious_file_riskurgency_languagethreat_languageaccount_suspension_languageoff_platform_migrationverification_code_requestidentity_document_requestprompt_injection_attemptbrowser_cloaking_suspectedpage_unreachableinsufficient_contextknown_safe_domainknown_customerallowlisted_domain

Security model

All user-submitted text, webpage text, OCR text, filenames, chat messages, and browser-observed text are treated as hostile evidence. The browser collector never enters credentials, never submits forms, blocks private/local/metadata targets, and produces structured evidence instead of a final decision.

Hosted model APIs

When OPENAI_API_KEY is configured and CUVARK_MODEL_PROVIDER is openai, Cuvark uses the OpenAI Responses API for a structured final judge pass. The deterministic scorer still runs first and hard malicious signals keep conservative handling.

Privacy and retention

Stored-data redaction is enabled by default. Before Cuvark persists case input, evidence, and model output, it redacts email addresses, phone numbers, long numeric tokens, and URL query parameters, and strips raw attachment payloads. Settings can also disable scored-case storage for an organization. Use DELETE /v1/cases/{case_id} or Settings retention purging to remove stored case data.

Local auth

Development mode allows API requests without a key. Set CUVARK_REQUIRE_API_KEY=true and CUVARK_API_KEY to require bearer-token auth.