VeriTrust
Dashboard

Integrate email threat investigation, URL intelligence, evidence correlation, usage telemetry, and auditable request identifiers through versioned server endpoints.

VeriTrust email intelligence API.

Use the REST-style API from a trusted backend or private script. The focused public surface covers email investigation, Link Intelligence, usage telemetry, and the policy-backed Evidence Correlation Gateway; VeriTrust does not currently ship an official SDK.

Signed-in users can create and revoke keys from API Access when their workspace plan permits it. The raw key is returned once; later list responses contain only masked metadata.

Open the PowerShell gateway guide

Authentication

Send the key as a Bearer token over HTTPS. Do not embed it in frontend JavaScript, a mobile binary, a public repository, or a shared notebook.

Authorization: Bearer vtg_live_YOUR_API_KEY
curl "https://YOUR_DOMAIN/api/v1/usage" \
  -H "Authorization: Bearer vtg_live_YOUR_API_KEY"

Scopes

New keys default to the focused detection scopes plus unified-gateway scan, read, and cancel access.

  • phishing:scan - use Phishing API
  • link:scan - use Link Intelligence API
  • usage:read - read API usage
  • gateway:scan - submit evidence-correlation Gateway scans and private uploads
  • gateway:read - read tenant-scoped gateway status and reports
  • gateway:cancel - cancel an unfinished gateway scan

Rate Limits And Error Format

Requests are checked against both the key's daily limit and the workspace's monthly API quota. The API Access and Usage & Limits pages show the deployed values; do not assume one fixed limit across plans. API v1 JSON responses include a request_id for support and logging.

{
  "ok": false,
  "request_id": "vt_req_xxxxx",
  "error": {
    "code": "INVALID_INPUT",
    "message": "Please provide a valid URL or text containing a URL."
  }
}

Common error codes include MISSING_API_KEY, INVALID_API_KEY, REVOKED_API_KEY, INSUFFICIENT_SCOPE, RATE_LIMITED, API_NOT_INCLUDED, MONTHLY_API_LIMIT_REACHED, SUBSCRIPTION_INACTIVE, INVALID_INPUT, INVALID_MODEL, MODEL_ERROR, and INTERNAL_ERROR.

Email Investigation API

Use the email investigation endpoints for suspicious message text and the dedicated Email v2 workflow for raw .eml evidence. Results preserve model, rule, and available forensic evidence instead of presenting one score as proof.

curl -X POST "https://YOUR_DOMAIN/api/v1/phishing" \
  -H "Authorization: Bearer vtg_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Your account will be blocked. Verify your password now.","model":"fast"}'

Usage API

GET /api/v1/usage requires usage:read and returns the key's daily usage, masked key metadata, and available workspace usage-and-limits snapshot. Usage lookups are themselves recorded as API usage events.

Evidence Correlation Gateway API

The implemented gateway base path is /api/v1/gateway. Default API keys include scan, read, and cancel scopes. Every submission requires an Idempotency-Key header so a retry cannot create a duplicate scan.

  • POST /api/v1/gateway/email/analyze-text — run the email forensic specialist on a subject and message body.
  • POST /api/v1/gateway/email/analyze-eml — upload an original .eml file as message/rfc822 for sender, attachment, link, and delivery-route evidence.
  • GET /api/v1/gateway/email/evidence/{scan_id} — retrieve the normalized email evidence behind a result.
  • POST /api/v1/gateway/scans — submit text, URLs, and registered media with gateway:scan.
  • GET /api/v1/gateway/scans?limit=20 — list tenant-scoped scans with gateway:read.
  • GET /api/v1/gateway/scans/{scan_id} — read status, evidence, and the current decision.
  • GET /api/v1/gateway/reports/{scan_id} — retrieve the complete normalized gateway report.
  • POST /api/v1/gateway/scans/{scan_id}/cancel — request cancellation with gateway:cancel.
  • POST /api/v1/gateway/uploads and POST /api/v1/gateway/uploads/{upload_id}/complete — register and complete private media uploads before scan submission.

Policy, review, operations, and webhook-management routes require their explicit management scopes and a current workspace owner or admin role. Production webhook delivery also requires an approved destination-host allowlist.

curl -X POST "https://YOUR_DOMAIN/api/v1/gateway/scans" \
  -H "Authorization: Bearer vtg_live_YOUR_API_KEY" \
  -H "Idempotency-Key: YOUR_UNIQUE_UUID" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {"kind": "api"},
    "content": {
      "text": "Review this account-verification message.",
      "urls": ["https://example.com/account-verification"],
      "media": []
    },
    "processing_mode": "synchronous",
    "metadata": {"context_categories": ["email"]}
  }'

For copy-ready Windows commands that accept either pasted email text or an .eml path, use the PowerShell email-forensics guide.

Python Example

import os
import requests

API_KEY = os.environ["VERITRUST_API_KEY"]
BASE_URL = "https://YOUR_DOMAIN"

payload = {
    "url": "https://secure-bank-verify-example.com/login",
    "model": "swift"
}

response = requests.post(
    f"{BASE_URL}/api/v1/link-check",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json=payload,
    timeout=60
)

data = response.json()

print(data["result"]["label"])
print(data["result"]["risk_level"])
print(data["result"]["confidence"])
print(data["result"]["summary"])

Private Jupyter Notebook Example

import os
import requests
from IPython.display import display, Markdown

API_KEY = os.environ["VERITRUST_API_KEY"]
BASE_URL = "https://YOUR_DOMAIN"

url = "https://secure-bank-verify-example.com/login"

response = requests.post(
    f"{BASE_URL}/api/v1/link-check",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"url": url, "model": "swift"},
    timeout=60
)

data = response.json()

display(Markdown(f"""
## VeriTrust Link Intelligence

**URL:** {url}  
**Verdict:** {data["result"]["label"]}  
**Risk:** {data["result"]["risk_level"]}  
**Confidence:** {data["result"]["confidence"]:.2%}  

{data["result"]["summary"]}
"""))

Security Best Practices

Never expose VeriTrust API keys in frontend JavaScript, public GitHub repositories, or shared notebooks. Use environment variables or server-side calls.

  • Store keys in environment variables or a secret manager.
  • Rotate and revoke keys from the dashboard when access changes.
  • Use the narrowest scope set that fits your integration.
  • Do not log raw API keys or paste them into public notebooks.