API Reference

System health check. Returns KV connectivity, env-var status, and a ready_to_sell boolean. Missing env var names are only revealed to authenticated admins.

{ status, ready_to_sell, version, response_ms, checks: { kv, env_vars } }

20-step chat hot path. Injection detection → auth → domain check → rate limit → status/usage checks → FAQ cache → RAG → AI completion → tool calls (lead capture / escalation) → conversation save → analytics.

{ message: string, conversationId?: string, sessionId?: string, metadata?: { url, userAgent } }

{ reply, conversationId, intent, sentiment, followUpQuestions, leadCaptured, escalated, model, usage }

Live demo endpoint (no API key). Supports 4 built-in business personas (SaaS, Ecommerce, Healthcare, Legal). Rate-limited to 30 req/min per IP.

{ message: string, business: "saas" | "ecommerce" | "healthcare" | "legal", conversationId?: string }

{ reply, conversationId, followUpQuestions, business }

Exchange a raw API key for a short-lived (1hr) widget token. Use this so the raw key is never embedded in HTML.

{}

{ token: string, expiresAt: number }

Resolve a widget token to a hashed key for server-side use.

{ hashedKey: string }

Account overview including status, plan, trial end date, monthly usage, and lead/conversation counts.

{ client, usage, leadsCount, conversationsCount }

Paginated list of captured leads with name, email, phone, company, intent, and timestamp.

{ leads: Lead[], count: number }

Last 30 conversations with message history, intent, sentiment, and lead/escalation flags.

{ conversations: Conversation[] }

List knowledge base chunks for this client. Pro+ plan required.

{ chunks: string[], count: number }

Add knowledge to the RAG vector index. Accepts a URL to scrape (up to 10 pages) or raw text. Pro+ plan required.

{ type: "url" | "text", content: string }

{ chunks: number, message: string }

Initiate a PayPal subscription upgrade. Returns a PayPal approval URL to redirect the user to.

{ plan: "starter" | "pro" | "enterprise", billingPeriod: "monthly" | "annual" }

{ approvalUrl: string, subscriptionId: string }

Cancel the active PayPal subscription. Requires { confirm: true } in body as a safety guard.

{ confirm: true }

{ cancelled: true, status: "cancelled" }

PayPal return URL after user approves a subscription. Verifies the subscription_id matches the pending record stored for this client (prevents account takeover), then activates the account.

Redirect to /client-dashboard?upgrade=success or ?upgrade=error

PayPal webhook receiver. Verifies PAYPAL-TRANSMISSION-SIG and processes 11 event types (ACTIVATED, RENEWED, CANCELLED, EXPIRED, SUSPENDED, PAYMENT.SALE.*, PAYMENT.FAILED, UPDATED). Idempotent via NX KV set.

{ received: true }

Shopify webhook receiver. Verifies HMAC-SHA256 signature per client, stores last 100 events. Client identified by ?client= query param.

Shopify webhook payload

{ received: true }

List all clients with config, usage, and lead counts. Sensitive fields (hubspotApiKey, shopifyWebhookSecret) are redacted.

{ clients: ClientConfig[], count: number }

Create a new client. Generates an API key (sk_live_... prefix), stores only the HMAC-SHA256 hash. The raw key is returned once and never stored.

{ businessName, email, domain, plan, module, widgetTitle?, widgetColor? }

{ apiKey: string (returned once), hashedKey, client }

Get a single client by hashed key.

ClientConfig (secrets redacted)

Update client config or run a special action: toggle_active, rotate_key (copies all KV data to new prefix), force_plan, extend_trial.

{ action?: "toggle_active"|"rotate_key"|"force_plan"|"extend_trial", ...fields }

Varies by action

GDPR erasure. Cancels PayPal subscription, deletes vector KB, and removes all 30+ KV key patterns for this client.

{ deleted: true, hashedKey }

Aggregated analytics for a client over 30 or 90 days: totals, daily breakdown, top intents, top sentiments.

AggregatedAnalytics

Billing ledger for a client (last 50 events).

{ ledger: BillingEvent[] }

Force a plan change on a client.

{ client: hashedKey, plan: PlanId }

{ updated: true }

Send a broadcast email to Active, Paid, Trial, or All clients. Supports {{business_name}} substitution and dry-run mode.

{ subject, body, audience: "active"|"paid"|"trial"|"all", dryRun?: boolean }

{ queued: number, dryRun: boolean, recipients?: string[] }

Search logs. Type: audit (last 100 audit entries), errors (last 100 errors), gdpr_export (full JSON export for one client).

AuditEntry[] | ErrorEntry[] | GDPR JSON

All leads across all clients, or filtered to one client. Supports CSV export via ?format=csv.

{ leads: Lead[] } or CSV file

List knowledge base chunks for a client.

{ chunks: string[], count: number }

Add knowledge (URL scrape up to 10 pages, or raw text) to a client's RAG vector index.

{ client: hashedKey, type: "url"|"text", content: string }

{ chunks: number, message: string }

Delete all knowledge base vectors for a client.

{ deleted: true }

Runs at 06:00 UTC daily. Scans all active clients: expires trials, repairs PayPal status drift, detects fast-cancel fraud (subscription cancelled < 48h after activation).

{ processed: number, errors: number }

Runs hourly. Drains the email queue — up to 100 emails per run with a 1.1s delay between sends (Resend rate limit compliance). 3 retries per message.

{ sent: number, failed: number }

Includes current-month usage count (hincrby per-day analytics), lead count, and conversation count.

{ client, usage, leadsCount, conversationsCount }

PayPal sends webhook events here. Signature verified with PAYPAL_WEBHOOK_ID. Events processed: BILLING.SUBSCRIPTION.ACTIVATED/RENEWED/CANCELLED/EXPIRED/SUSPENDED/UPDATED, PAYMENT.SALE.COMPLETED/DENIED/REFUNDED, PAYMENT.FAILED.

PayPal webhook payload

{ received: true }

Shopify sends webhook events here. HMAC-SHA256 verified per client using shopifyWebhookSecret. Stores last 100 events per client.

Shopify webhook payload

{ received: true }