Skip to main content
The v2 validation API exposes ZeroDrift’s agentic email validator. It runs an LLM-driven graph that profiles the email, plans which compliance signals to evaluate, runs them in parallel, adversarially verifies each finding, and synthesizes a final assessment. v2 lives under /api/v2/ and is additive — all v1 routes are unchanged. Use v2 when you want the richer, signal-based output (violations with reasoning and verifier notes, plus an email_profile); use v1 if you depend on the existing fixes / fixes_group shape.

​
Endpoints

Both require the same x-api-key authentication as v1.

​
Async vs. sync

​
mode
string
default:"async"
async (default) creates a job and returns 202 immediately with a job_id and poll URL — identical lifecycle to v1, just a cleaner envelope. sync runs the agentic graph inline and returns the completed result in a single 200 response.
Sync mode is intended for short emails. If the email exceeds the sync size cap (default 20,000 characters) or inline execution fails, the API automatically falls back to async and returns the 202 envelope — a submission is never lost.

​
How v2 differs from v1

  • Signal-based violations — each finding carries signal_id, severity, confidence, the offending quote with character offsets, model reasoning, a verifier_note from the adversarial check, and a suggested fix.
  • email_profile — the agent’s structured read of the email (intent, tone, claims, audience signals, disclosures present) is surfaced alongside violations.
  • Stable status vocabulary — queued, processing, completed, failed (v1’s internal started / in_progress / done are not leaked).
  • Versioned envelope — every response carries "api_version": "v2".

​
Typical flow

1

Submit

POST /api/v2/emails/validate with email_text. Returns 202 + job_id (async) or 200 + full result (sync).
2

Poll

For async, GET /api/v2/jobs/{job_id} until status is completed or failed.
3

Act

Read result.overall_status and result.violations to surface findings.