Endpoint reference Enterprise
| Endpoint | Method | Purpose |
|---|---|---|
/api/search | POST | Get AI answers with sources/products. |
/api/ingest | POST | Create crawl jobs (simple/sitemap/advanced modes). |
/api/crawls | GET | List crawl history and statuses. |
/api/documents | POST/GET/DELETE | Manage uploaded knowledge files. |
/api/widget-config | GET/POST | Read/save widget visual config. GET also returns availability: {"available": false, "reason": "quota_exceeded"} when the widget should stay hidden. |
/api/quota | GET | Monthly question usage for a site: state (ok, warning, grace, blocked), used, limit, graceLimit, resetDate and suppressedLoads (page views without the assistant). |
/api/widget-suppressed | POST | Called by the widget when it stays hidden, to count page views without the assistant. |
/api/config | GET/POST | Read/save workspace behavior config. |
/api/analytics | GET | Retrieve KPIs, question topics, gaps and trends. |
/api/notify-me | POST | Save a visitor's "Notify me" request for a product the site doesn't carry. Called by the widget. |
/api/notify-me/settings | GET/PUT | Read or change whether the widget offers "Notify me" (owner only for changes). |
/api/notify-me/requests | GET | Export "Notify me" requests with email addresses, as JSON or CSV (owner only). |
/api/brief/settings | GET/PUT | Read or change Monday Brief recipients and timing (owner only for changes, Pro and above). |
/api/gaps/status | PUT | Mark a gap as fixed, dismissed or open (label, kind: product or content). |
/api/gaps/lifecycle | GET | Fixed gaps with weekly volume before and since the fix, change in %, and status: measuring, verified, not_improved or insufficient_data. |
/api/brief/send-test | POST | Send this week's Monday Brief to the saved recipients now (owner only). |
/api/functions | GET/POST | Manage function definitions. |
/api/security-settings | GET/POST | Control token, rate, and abuse safeguards. |
/api/allowlist | GET/POST | Manage authorized domains/origins. |
/api/token | GET/POST | View or rotate API token. |
Authentication
/api/search accepts your API key in the x-api-key header (see API Key and Auth). The widget uses a short-lived initialization token instead. Settings and reporting endpoints (/api/analytics, /api/quota, /api/brief/*, /api/gaps/*, /api/notify-me/settings and /requests) require a signed-in dashboard user and check that they belong to the site.
POST /api/search: response fields
| Field | Description |
|---|---|
answer | The reply to show the visitor. |
sources | Pages and products used. Product sources also include name, image and price. |
status | success or no_answer. |
forcedNoAnswer | true when the assistant declined because retrieval confidence was below the threshold. |
unmetProduct | Short, lowercase name of a product the visitor asked for that the site doesn't carry, or null. |
questionTopic | Which of the site's own question topics the question belongs to, or null. |
notifyOffer | { "product": "…" } when the site has "Notify me" turned on and unmetProduct is set; otherwise null. The widget uses it to show the "Notify me" form. |
confidence, retrievalConfidenceThreshold | Retrieval confidence of the best match, and the threshold in force. |
actionRequest | A Function the assistant suggests, or null. |
When the site is over its monthly question limit, /api/search and /api/webmcp/query return 402 with {"error": "quota_exceeded", "status": "quota_exceeded", "message": "…"}.
POST /api/notify-me
curl -X POST https://askvio.web.app/api/notify-me \
-H "Content-Type: application/json" \
-d '{"clientId":"YOUR_CLIENT_ID","product":"gift cards","email":"visitor@example.com","conversationId":"…","pageUrl":"https://example.com/shop"}'Returns {"ok": true, "duplicate": false}. The same email for the same product is stored once (duplicate: true on repeats). Returns 403 when "Notify me" is off for the site or the origin isn't allowlisted, 400 for an invalid email, and 429 after 5 requests per minute from one IP.
GET /api/notify-me/requests
Query: websiteId, optional format=csv. Each row has gap (the Unmet demand group the product belongs to), product, email, requestedAt and pageUrl. Only the site owner can call it, because it contains email addresses.
GET /api/analytics: intelligence fields
| Field | Description |
|---|---|
questionClusters | What visitors asked, grouped by meaning: label, total, daily counts, examples and up to 20 questions. Group names come from the site's own vocabulary and stay stable over time. |
demandGaps | Products visitors asked for that aren't in the catalog: query, count (asks), notifyCount ("Notify me" requests), alsoUnanswered, lastSeen. |
failedSearches | Questions the site couldn't answer: query, count, samples, lastSeen and gapType (product when the fix is a product decision, content when it's a missing answer). Labels match demandGaps for the same concept. |
gapStatuses | Gaps marked fixed or dismissed: label, kind, status, fixedAt. demandGaps and failedSearches also carry daily counts. |
notifyRequests | Number of "Notify me" requests in the period. |
failedIntentRate | Share of conversations the site couldn't answer. The dashboard derives "answered confidently" from it everywhere. |
terms | Most frequent single words and word pairs (kept for compatibility; prefer questionClusters). |