API Reference

Create a new workspace account.

curl -X POST /auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"you@agency.com","password":"s3cr3t!","workspaceName":"My Agency"}'

Log in and receive a signed JWT.

curl -X POST /auth/login \
  -d '{"email":"you@agency.com","password":"s3cr3t!"}'

Returns { token, userId, email, workspaceId, workspaceName, plan, role }

Request a password-reset email.

Set a new password using a reset token.

Confirm email address using the verification link token.

List all active API keys for the authenticated workspace.

Returns array of { id, name, publicKey (pk_live_…), lastUsedAt, createdAt }. Secret key is only shown once on creation.

Create a new API key pair.

Returns { publicKey: "pk_live_…", secretKey: "sk_live_…" }. Store the secret key — it cannot be retrieved again.

Revoke and permanently delete an API key.

List all tracked competitors for the workspace.

Returns { competitors: Competitor[], total }

Get a single competitor with metadata and email count.

Add a new competitor to track.

Update competitor metadata.

Remove a competitor and all associated emails and intelligence.

List UTM-attributed campaign clusters detected for a competitor.

Paginated email list with filtering support.

curl /emails?competitorId=uuid&page=1&pageSize=50&dateFrom=2025-01-01 \
  -H "Authorization: Bearer {token}"

Returns { emails: EmailMessage[], total, page, pageSize }

Get full email with HTML content, insight block, links, and AI analysis.

Force re-analysis of a stored email (re-runs AI enrichment and ESP fingerprinting).

Return parsed authentication headers: SPF, DKIM, DMARC results from the received email.

Returns { spfStatus, dkimStatus, dmarcStatus, receivedHeaders[], listId }

Return the stored screenshot URL for an email (if rendered).

Workspace-wide summary: total emails, unique competitors, CTA rate, top sender.

Send-time heatmap (day × hour × count) for all tracked emails.

Returns { heatmapData: [{ dayOfWeek, hour, count }] }

Top CTA link domains with click counts across all captured emails.

Full per-competitor performance report: volume, send timing, word counts, link stats, UTM usage.

Full brand intelligence summary: strategy, promo cadence, subject patterns, and recommendations. AI narrative is returned with evidence tags.

Returns BrandIntelligenceSummary { narrativeSummary (tagged), frequencyTrend, discountPattern, subjectPattern, keyInsights[], actionableRecommendations[] }

Score recent subject lines for urgency, emotion, clarity, and length. Returns AI verdict per subject.

Workspace-wide competitive alerts: frequency spikes, promotional surges, deep discounts, new campaign detection.

Returns { alerts: AlertItem[] } sorted by severity (high → low)

Detect campaign sequences, promotional calendar, and send cadence patterns.

Return the cached sender profile (or build one if none exists). Includes ESP detection, auth signals, company size estimate, industry benchmarks, and DNS facts.

Returns SenderDomainProfile { espDetected, espConfidence, spfPass, dkimPass, dmarcPass, spfRecord, dmarcRecord, dkimSelectorsJson, dnsEvidenceJson, industry, businessModel, companySize, estimatedRevenueLabel, senderIntelligenceScore, narrativeSummary, authRiskScore }

Force a full re-analysis of the sender profile, ignoring cache. Re-runs ESP detection, DNS probe, and benchmark calculations.

List all sender profiles visible to the workspace (Agency = workspace-scoped, superadmin = all).

Live DNS probe for any domain. Returns SPF, DMARC, DKIM, MX, and BIMI records with an authentication risk scorecard. All results are tagged [FACT] — no AI inference.

curl "/intelligence/dns-probe?domain=klaviyo.com" \
  -H "Authorization: Bearer {token}"

Returns {
  spf: { found, record, policy, hard_fail, soft_fail, includes[], ips[] },
  dmarc: { found, record, policy, spf_alignment, dkim_alignment, rua, pct },
  dkim: { selectors_found[], records[{ selector, key_type, key_bits }] },
  mx: { records[], mailbox_provider },
  bimi: { found, record },
  auth_risk: { score, level, factors[] },
  evidence_tag: "FACT — live DNS"
}

Run a DNS probe for a competitor's sender domain and return a structured evidence object.

Crawl all discover-able pages on the competitor site to detect opt-in forms, popup triggers, and ESP provider scripts.

Returns { assetsFound, assetsNew, duration_ms }

List all detected lead assets (forms, popups, exit-intent triggers) for a competitor.

Each asset: { id, url, leadMagnetType, triggerType, provider, isActive, copyPreview, lastSeenAt }

Get a single lead asset with full HTML snippet and provider detection evidence.

Re-crawl a specific page to check for copy changes or new form structure.

Returns { copyChanged: bool, changesDetected: string[] }

Update asset state: mark as ignored or re-enable tracking.

Start a funnel session by subscribing to the opt-in form attached to this asset.

Creates a FunnelSession record and returns { sessionId, assetId, startedAt }

List all funnel sessions for a competitor with attribution and flow analysis data.

Get a single session including all attributed emails in sequence order.

Re-run email attribution for a session. Uses time-proximity decay + header signals to attribute received emails.

Returns { emailsAttributed, avgConfidence }

Run AI flow analysis on an attributed session. Classifies flow type, detects urgency escalation, discount evolution, and dynamic content patterns.

Returns { flowType, flowLabel, urgencyEscalation, dynamicContent, discountEvolution, aiUsed }

Intelligence timeline: events log for copy changes, new assets, urgency escalations, and flow changes.

Mark an intelligence timeline event as read.

Cross-funnel comparison: compares all sessions for a competitor by email volume, urgency, attribution, and flow type.

Return stored client risk analysis for an email.

Returns { overallRisk, clients: [{ client, severity, issues[] }] }

Force re-analysis of client compatibility for a stored email.

Analyse raw HTML without saving. Pass HTML + subject, get back a risk report immediately.

All detected A/B variant clusters for a competitor.

Returns Campaign[] { utmCampaign, emailCount, linkCount, firstSeenAt, lastSeenAt, recentEmails[] }

Re-run the variant clustering algorithm for a competitor.

List all widgets configured for this workspace.

Create a new embeddable widget.

Delete a widget configuration.

Create a Stripe Checkout session for plan upgrade.

Returns { url } — redirect user to this URL to complete payment.

Create a Stripe Customer Portal session for subscription management.

Returns { url } — redirect user to manage their plan.

List recent notifications for the authenticated user.

Mark a notification as read.

Mark all notifications as read.

Mailgun MIME message delivery endpoint. Processes inbound emails, runs ESP fingerprinting, AI enrichment, and stores to database.

Internal use only — must be configured in Mailgun Routes.

List published blog posts.

Get a single blog post by slug.