# WizChat Documentation > Build AI-powered chatbots with your own knowledge base - [WizChat Documentation](/index.md) ## search - [Search the documentation](/search.md) ## ai-agents Use the WizChat documentation from Claude Code, Codex, Cursor, and other AI tools — clean Markdown, an llms.txt index, and a full-text corpus. - [Docs for AI Agents](/ai-agents.md): Use the WizChat documentation from Claude Code, Codex, Cursor, and other AI tools — clean Markdown, an llms.txt index, and a full-text corpus. ## analytics ### costs Track and monitor your AI usage costs - [Cost Monitoring](/analytics/costs.md): Track and monitor your AI usage costs ### queries Analyze chatbot queries and user interactions - [Query Analytics](/analytics/queries.md): Analyze chatbot queries and user interactions ### reports Generate and schedule usage reports - [Usage Reports](/analytics/reports.md): Generate and schedule usage reports ## api ### authentication How to authenticate with the WizChat API - [API Authentication](/api/authentication.md): How to authenticate with the WizChat API ### chatbots API endpoints for interacting with chatbots - [Chatbot API Endpoints](/api/chatbots.md): API endpoints for interacting with chatbots ### documents API endpoints for managing knowledge base documents - [Document API Endpoints](/api/documents.md): API endpoints for managing knowledge base documents ### errors API error codes and troubleshooting - [API Error Codes](/api/errors.md): API error codes and troubleshooting ### teams API endpoints for managing teams - [Team API Endpoints](/api/teams.md): API endpoints for managing teams ## billing ### invoices View and download your billing invoices - [Invoices](/billing/invoices.md): View and download your billing invoices ### plans Compare WizChat subscription plans and features - [Subscription Plans](/billing/plans.md): Compare WizChat subscription plans and features ### top-up Purchase additional AI budget when you need more usage - [Top-Up Credits](/billing/top-up.md): Purchase additional AI budget when you need more usage ### usage Monitor your WizChat usage and AI budget - [Usage Tracking](/billing/usage.md): Monitor your WizChat usage and AI budget ## changelog WizChat release notes and updates - [Changelog](/changelog.md): WizChat release notes and updates ## chatbot-users ### access-modes Configure how users can access your chatbot - [Access Modes](/chatbot-users/access-modes.md): Configure how users can access your chatbot ### access-protection Restrict chatbot access with URL-based app keys or JWT tokens - [Access Protection](/chatbot-users/access-protection.md): Restrict chatbot access with URL-based app keys or JWT tokens ### authentication Require users to authenticate before using your chatbot - [Authentication Setup](/chatbot-users/authentication.md): Require users to authenticate before using your chatbot ### inviting Invite specific users to access your chatbot - [Inviting Users](/chatbot-users/inviting.md): Invite specific users to access your chatbot ### managing View and manage users who access your chatbot - [Managing Users](/chatbot-users/managing.md): View and manage users who access your chatbot ### sso Set up enterprise SSO with Azure AD, Okta, or other OIDC providers for your chatbot - [SSO (Single Sign-On)](/chatbot-users/sso.md): Set up enterprise SSO with Azure AD, Okta, or other OIDC providers for your chatbot ## chatbots ### ai-settings Configure the AI model, prompts, and behavior for your chatbot - [AI Model Settings](/chatbots/ai-settings.md): Configure the AI model, prompts, and behavior for your chatbot ### appearance Customize your chatbot's visual appearance - [Appearance & Branding](/chatbots/appearance.md): Customize your chatbot's visual appearance ### configuration Configure your chatbot's basic settings - [Configuration & Settings](/chatbots/configuration.md): Configure your chatbot's basic settings ### conversation-memory Two memory strategies for personalized chatbot conversations — Graph-based knowledge graph or Conventional summarization - [Conversation Memory](/chatbots/conversation-memory.md): Two memory strategies for personalized chatbot conversations — Graph-based knowledge graph or Conventional summarization ### creating Learn how to create a new chatbot in WizChat - [Creating a Chatbot](/chatbots/creating.md): Learn how to create a new chatbot in WizChat ### deployment Deploy your chatbot and make it accessible to users - [Deployment](/chatbots/deployment.md): Deploy your chatbot and make it accessible to users ### managing Edit, pause, archive, and manage your chatbots - [Managing Chatbots](/chatbots/managing.md): Edit, pause, archive, and manage your chatbots ### media-attachments Attach an audio or video file in the chat and ask questions about it - [Audio and video in chat](/chatbots/media-attachments.md): Attach an audio or video file in the chat and ask questions about it ### sales-agent Configure and manage the Sales Agent for lead capture and delivery - [Sales Agent](/chatbots/sales-agent.md): Configure and manage the Sales Agent for lead capture and delivery ### voice-input Dictate messages with the in-chat microphone and pick your speech language - [Voice input](/chatbots/voice-input.md): Dictate messages with the in-chat microphone and pick your speech language ## getting-started ### first-chatbot Step-by-step tutorial to create your first WizChat chatbot - [Your First Chatbot](/getting-started/first-chatbot.md): Step-by-step tutorial to create your first WizChat chatbot ### key-concepts Understand the fundamental concepts of WizChat - [Key Concepts](/getting-started/key-concepts.md): Understand the fundamental concepts of WizChat ### quick-start Get up and running with WizChat in 5 minutes - [Quick Start Guide](/getting-started/quick-start.md): Get up and running with WizChat in 5 minutes ## integrations ### ai-gateway-byok Use your own API keys through the Vercel AI Gateway - [AI Gateway BYOK (Bring Your Own Key)](/integrations/ai-gateway-byok.md): Use your own API keys through the Vercel AI Gateway ### byoi Use your own LLM, embeddings, vector store, and databases - [BYOI (Bring Your Own Infrastructure)](/integrations/byoi.md): Use your own LLM, embeddings, vector store, and databases ### external-api Access your chatbot programmatically via API - [External API](/integrations/external-api.md): Access your chatbot programmatically via API ### mcp - [Built-in MCP Servers](/integrations/mcp/built-in.md): Pre-configured MCP integrations available in WizChat - [Custom MCP Servers](/integrations/mcp/custom.md): Add your own MCP server integrations - [Interactive UI (MCP-UI)](/integrations/mcp/interactive-ui.md): Let a trusted MCP server render its own interactive dialogs and forms inside the chat - [Local Execution (Return-Script)](/integrations/mcp/local-execution.md): Build an MCP server whose tools run on the user's machine instead of in the cloud - [Model-backed tools](/integrations/mcp/model-backed-tools.md): Let a tool's result be produced by an AI model you declare in the tool's MCP metadata — no API key, no agent - [OAuth Configuration](/integrations/mcp/oauth.md): Set up OAuth authentication for MCP integrations - [MCP Servers Overview](/integrations/mcp/overview.md): Extend your chatbot with Model Context Protocol integrations - [Tool Approval (HITL)](/integrations/mcp/tool-approval.md): Ask users to approve MCP tool calls before they run ### postgresql Query PostgreSQL databases using natural language - [PostgreSQL Integration (QueryWeaver)](/integrations/postgresql.md): Query PostgreSQL databases using natural language ### youtube Import YouTube videos into your knowledge base - [YouTube Integration](/integrations/youtube.md): Import YouTube videos into your knowledge base ## knowledge-base ### access-control Control who can access specific documents in your knowledge base - [Document Access Control](/knowledge-base/access-control.md): Control who can access specific documents in your knowledge base ### crawl-drift See which pages a crawled site added or removed since your last crawl - [Check for Changes (Crawl Drift)](/knowledge-base/crawl-drift.md): See which pages a crawled site added or removed since your last crawl ### managing Manage, organize, and maintain your knowledge base documents - [Managing Documents](/knowledge-base/managing.md): Manage, organize, and maintain your knowledge base documents ### overview Understand how knowledge bases work in WizChat - [Knowledge Base Overview](/knowledge-base/overview.md): Understand how knowledge bases work in WizChat ### scheduled-crawling Automatically keep website content up to date - [Scheduled Crawling](/knowledge-base/scheduled-crawling.md): Automatically keep website content up to date ### scopes Partition your knowledge base into separate scopes with independent access control, behavior, and budgets - [Knowledge Scopes](/knowledge-base/scopes.md): Partition your knowledge base into separate scopes with independent access control, behavior, and budgets ### transcript-corrections Review and resolve AI-suggested transcript corrections for video content - [Transcript Corrections](/knowledge-base/transcript-corrections.md): Review and resolve AI-suggested transcript corrections for video content ### uploading - [Uploading CHM Files](/knowledge-base/uploading/chm.md): Upload Windows CHM help files into your knowledge base - [In-Chat Data Analysis](/knowledge-base/uploading/data-analysis.md): Upload Excel or CSV files in a conversation for instant data analysis - [Excel & Spreadsheets](/knowledge-base/uploading/excel.md): Upload spreadsheet data to your knowledge base - [Images (OCR)](/knowledge-base/uploading/images.md): Extract text from images using OCR - [Uploading PDFs](/knowledge-base/uploading/pdfs.md): Upload and process PDF documents for your knowledge base - [Videos & YouTube](/knowledge-base/uploading/videos.md): Add video content to your knowledge base through transcription ### website-crawling Import content from websites into your knowledge base - [Website Crawling](/knowledge-base/website-crawling.md): Import content from websites into your knowledge base ## management-api ### guides - [Add knowledge base content via the API](/management-api/guides/adding-content.md): Add text or Markdown straight to a chatbot's knowledge base with a single API call — no file upload needed. - [Authentication & scopes](/management-api/guides/authentication.md): How to authenticate Management API requests and how scopes constrain a key. - [Config-as-code](/management-api/guides/config-as-code.md): Export a chatbot's configuration, edit it, and apply the desired state declaratively. - [Errors & rate limits](/management-api/guides/errors-and-rate-limits.md): The Management API error envelope, status codes, and rate-limit behavior. - [OAuth 2.0](/management-api/guides/oauth.md): Authenticate to the Management API with OAuth 2.0 — client-credentials tokens for server-to-server access, plus the interactive flow used by MCP clients. - [Quickstart](/management-api/guides/quickstart.md): Make your first WizChat Management API call in under five minutes. ### overview Programmatic, config-as-code control plane for your WizChat chatbots. - [Management API (v1)](/management-api/overview.md): Programmatic, config-as-code control plane for your WizChat chatbots. ### reference - [Apply a desired-state config document](/management-api/reference/apply-chatbot-config.md): Declarative config-as-code apply. Diffs a desired-state document against the chatbot's CURRENT config and either returns the PLAN (dry-run) or executes it via the shared reconcile services. `prune` defaults to true: array sections (mcpServers, skills, domains) are AUTHORITATIVE — resources present on the chatbot but absent from the document are DELETED. Every delete is surfaced in the dry-run plan before any apply. prune:false = merge-only (create/update, never delete). Only sections present in `spec` are reconciled; absent sections are left untouched (never pruned). Scope model (least-privilege, per present section): dry-run requires the READ scope, apply the WRITE scope, of every section present, PLUS baseline chatbots:read (dry-run) / chatbots:write (apply). Section→scope: core/scopes→chatbots, mcpServers→mcp, skills→skills, accessProtection/externalApi/accessLists/telemetry→security, domains→domains. Execution stops on the FIRST failing op (apply is idempotent, so a stopped apply is recoverable after fixing the offending section); a partial failure returns HTTP 422 with the ops applied so far plus the offending op. - [Authorize a custom domain](/management-api/reference/authorize-chatbot-domain.md): Adds a custom domain to the chatbot's authorized login domain list. Requires a paid plan tier that supports custom domains. On success returns the updated domain status. On failure (the domain authorization call failed) returns 400 with `PublicDomainStatus` (status: `pending_manual`) or a standard `Error` envelope for validation/config failures. Required scope: `domains:write`. - [Start the YouTube connect flow](/management-api/reference/connect-you-tube.md): Begins connecting the caller's YouTube account. Returns an `authorizeUrl` the caller opens in a browser to grant access; the connection is completed by the browser callback. Account-scoped (no chatbot). Required scope: `videos:write`. - [Create an access-protection key](/management-api/reference/create-access-protection-key.md): Mint a new widget access-protection key. The full plaintext key is returned ONCE in the response body. **Store it immediately — it cannot be retrieved again.** Subsequent reads expose only the `keyPrefix` display hint. Required scope: `security:write`. - [Create a chatbot](/management-api/reference/create-chatbot.md): Creates a new chatbot with `status: 'draft'` and `deployment.status: 'pending'`. Creation does not provision any infrastructure or start a deployment. **The first deploy must be done from the WizChat dashboard**, which provisions the underlying infrastructure; the v1 `/deploy` endpoint only re-deploys a chatbot that has already been deployed once. Restricted API keys (those locked to specific chatbot IDs) cannot create chatbots. Plan limits are enforced transactionally. **Note:** newly created chatbots have no `aiConfig` (no LLM model). Before triggering a deployment, use `POST /api/v1/chatbots/{id}/apply` to set `spec.core.aiConfig.llmModel` and related fields. Required scope: `chatbots:write`. - [Create a scheduled crawl](/management-api/reference/create-chatbot-scheduled-crawl.md): Creates a recurring scheduled crawl that re-ingests the given URLs into the chatbot's knowledge base on the chosen cadence. `dayOfWeek` is required for `weekly`; `dayOfMonth` (1-28) for `monthly`. Limited to 3 schedules per chatbot and 100 URLs per schedule (a violation returns 400). Requires admin-level chatbot access. Required scope: `documents:write`. - [Create a knowledge scope](/management-api/reference/create-chatbot-scope.md): Create a single knowledge scope. The scope `id` is derived by slugifying `id` (if given) else `label` (lowercase; `[^a-z0-9_-]` → `-`). Returns 409 if a scope with that id already exists. Unlike PATCH /scopes (which replaces the whole array), this updates one scope in place, so `costLimit`, `authorizedEmails`, and `authorizedDomains` are preserved. Required scope: `chatbots:write`. - [Create an email group](/management-api/reference/create-email-group.md): Creates an email group (name + member emails). Emails are normalized and de-duplicated. Group names must be unique per owner. Required scope: `security:write`. - [Create an external-API key](/management-api/reference/create-external-api-key.md): Mint a new external-API key. The full plaintext key is returned ONCE in the response body (`key` field). **Store it immediately — it cannot be retrieved again.** Subsequent reads expose only the `keyPrefix` display hint. Maximum 5 active keys per chatbot. Required scope: `security:write`. - [Create an MCP server](/management-api/reference/create-mcp-server.md): Create a new MCP server configuration for a chatbot. Stdio transport is not supported via the management API (use HTTP transport). Tool discovery is attempted automatically for HTTP servers. OAuth flows, PostgreSQL scan, and metrics are dashboard-only (deferred). Required scope: `mcp:write`. - [Register an OAuth client](/management-api/reference/create-o-auth-client.md): Register an OAuth client - [Issue an access token (client credentials)](/management-api/reference/create-o-auth-token.md): Public endpoint — no bearer auth required. Exchange `client_id` + `client_secret` for a short-lived access token. Supports `client_credentials` grant type only (RFC 6749 §4.4). Accepts both `application/json` (developer convenience) and `application/x-www-form-urlencoded` (RFC 6749 §4.4.2 standard). Returns `400 invalid_request` for any other Content-Type. Rate-limited: returns `429 rate_limited` + `Retry-After` header when the IP bucket is exceeded. - [Create a skill](/management-api/reference/create-skill.md): Create a new skill for a chatbot. Auto-enables the skills feature on first creation. Name must be unique within the chatbot (max 25 skills per chatbot). Required scope: `skills:write`. - [Deauthorize a custom domain](/management-api/reference/deauthorize-chatbot-domain.md): Removes a custom domain from the chatbot's authorized login domain list. Required scope: `domains:write`. - [Delete a chatbot](/management-api/reference/delete-chatbot.md): Permanently deletes a chatbot and cascades its cleanup (knowledge base, storage, deployment, and configuration). Requires the chatbot OWNER or a team owner/admin (stricter than edit access). Returns 200 on full deletion, or 207 Multi-Status if the chatbot was removed but some downstream cleanup failed (see `errors`). Returns 409 if a shared resource (e.g. a knowledge base still used by another chatbot) blocks deletion — nothing is deleted in that case. Required scope: `chatbots:write`. - [Delete chatbot memory data](/management-api/reference/delete-chatbot-memory-data.md): Permanently deletes the chatbot's graph conversation memory for the given scope. `scope=long-term` removes stored facts + session summaries; `scope=short-term` removes within-session conversation nodes. Destructive and irreversible. Required scope: `chatbots:write`. - [Delete a scheduled crawl](/management-api/reference/delete-chatbot-scheduled-crawl.md): Deletes a scheduled crawl and its run history. Pass `deleteVectors=true` to also purge the vectors this schedule ingested into the KB. Fails closed: if the vector purge fails, the schedule is NOT deleted (its metadata is preserved so the purge can be retried) and a 502 is returned. Required scope: `documents:write`. - [Delete a knowledge scope](/management-api/reference/delete-chatbot-scope.md): Remove one knowledge scope from a chatbot. Also unassigns the scope from the knowledge-base tree and any workflows that referenced it. Returns 409 if the scope still has documents/vectors — reassign or delete them in the dashboard first (no destructive document/vector cascade). Required scope: `chatbots:write`. - [Delete a document](/management-api/reference/delete-document.md): Delete a document and all its data (embedding vectors, storage, metadata). Required scope: `documents:write`. `success` is `false` when any cleanup step produced a warning (honest semantics). `warnings` is always present (empty array on clean delete). - [Delete an email group](/management-api/reference/delete-email-group.md): Delete an email group. Required scope: `security:write`. - [Delete an MCP server](/management-api/reference/delete-mcp-server.md): Remove an MCP server from a chatbot. For PostgreSQL servers, the associated schema graph is also deleted (non-fatal on error). Required scope: `mcp:write`. - [Revoke an OAuth client](/management-api/reference/delete-o-auth-client.md): Revoke an OAuth client - [Delete a lead-delivery channel](/management-api/reference/delete-sales-agent-handoff.md): Removes a lead-delivery channel. Idempotent — deleting an unknown channel still returns success. Required scope: `chatbots:write`. - [Delete a skill](/management-api/reference/delete-skill.md): Remove a skill from a chatbot. Required scope: `skills:write`. - [Delete a video](/management-api/reference/delete-video.md): Delete a video and all its data (embedding vectors, transcript, storage, metadata). Required scope: `videos:write`. `success` is `false` when any cleanup step produced a warning (honest semantics). `warnings` is present when non-empty. - [Trigger a redeploy](/management-api/reference/deploy-chatbot.md): Re-runs the production build with the chatbot's CURRENT build-time environment. Runtime config (model, behavior, appearance, prompts, etc.) is read live and does NOT require a deploy. This endpoint does NOT re-sync build-time settings (e.g. chatbot name, requireAuth, region); if you changed a build-time field, use the dashboard redeploy. Long-running operation (up to 5 min). The response is returned immediately with status `deploying`; poll GET /deployment for the final status. If a build exceeds ~60s the status may remain `deploying`; the already-deploying guard clears after ~10 minutes. Required scope: `deploy`. - [DSAR-erase a sales-agent lead's PII (destructive)](/management-api/reference/erase-sales-agent-lead.md): DESTRUCTIVE. GDPR DSAR hard-erase of a single lead's PII: scrubs the encrypted captured-fields envelope, HMAC hashes, and PII-adjacent geo (IP/region/city/timezone) to null while RETAINING the anonymous row (disposition, capturedAt, geo.countryCode) so aggregate metrics stay intact. Idempotent — a repeat erase on an already-erased lead returns 409 and preserves the original piiErasedAt (GDPR Article 17 audit-trail integrity). Owner/admin gated. Required scope: `security:write`. - [Export sales-agent leads as CSV (with decrypted PII)](/management-api/reference/export-sales-agent-leads.md): Exports a chatbot's captured sales-agent leads as a CSV, over the requested window and filters. Unlike the metadata-only list, this DECRYPTS the captured contact fields (name/email/phone/company) server-side and includes the coarse geo columns. Cells are CSV-injection-hardened (a leading =+@- is escaped with a single quote). Each row carries a `pii_decrypt_status` (ok / failed / erased / none). Capped at 5000 rows after filters — a larger result returns 413 (narrow the window / filters). Owner/admin gated (bulk PII decrypt). Required scope: `security:read`. - [Get access lists](/management-api/reference/get-access-lists.md): Returns the authorizedEmails, authorizedDomains, and allowedEmbedDomains lists for a chatbot. Unlike the PublicChatbot listing (which collapses these to counts for privacy), this endpoint returns the full rosters for headless config-as-code use cases. Requires admin-level access (`canManageAccess`). Required scope: `security:read`. - [Get access-protection config](/management-api/reference/get-access-protection.md): Returns the widget access-protection configuration for a chatbot. jwtConfig.secret is collapsed to a boolean `hasSecret` flag — the raw secret is never returned. Key hashes are stripped; only safe key metadata (id, label, keyPrefix, status, usageCount, timestamps) is returned. Required scope: `security:read`. - [Get workspace usage overview](/management-api/reference/get-aggregate-analytics.md): Owner-level (NOT chatbot-scoped) 7-day cross-chatbot usage overview: per-day query trend + total queries, total chatbots, and deployed-chatbot count. Loops all chatbots the caller owns. FULL-ACCESS CALLER REQUIRED: a chatbot-scoped key (allowedChatbotIds set) receives 403 `chatbot_not_in_key_scope` — it cannot read workspace-wide totals. The dashboard `success` flag and `debug` block are never emitted. Tier-gated (usage, starter+). Required scope: `analytics:read`. - [Get a chatbot](/management-api/reference/get-chatbot.md): Returns a single chatbot by ID. Required scope: `chatbots:read`. - [Export aggregate config](/management-api/reference/get-chatbot-config.md): Assembles the chatbot's CURRENT configuration into a single canonical desired-state document (the 'export current config' / drift baseline for the declarative apply). Reuses every section serializer; never returns secrets — accessProtection.jwtConfig.secret is collapsed to hasSecret, and the access-protection / external-api key arrays are excluded entirely. Baseline scope: `chatbots:read`. Per-section read-scope gating (least-privilege): a section is OMITTED from `spec` when the caller's key lacks its read scope, and listed in `_omittedSections` (core/scopes→chatbots:read, mcpServers→mcp:read, skills→skills:read, accessProtection/externalApi/accessLists/telemetry→security:read, domains→domains:read). Firebase callers hold all scopes. - [Get conversation-intelligence analytics](/management-api/reference/get-chatbot-conversation-analytics.md): Conversation-intelligence aggregates for a single chatbot at dashboard parity: top topics, knowledge gaps, language distribution, scope usage, hourly heatmap, conversation depth. topTopics/knowledgeGaps titles are k-anonymity-gated (≥3 distinct sessions) and exposed exactly as the dashboard shows the owner. No raw session or user identifiers are ever returned — only aggregated, anonymized results. Tier-gated (pro-plus+). Required scope: `analytics:read`. - [Get cost analytics](/management-api/reference/get-chatbot-cost-analytics.md): Returns cost analytics for a single chatbot over the requested period. Tier-gated: the plan's analytics day-cap is applied automatically; a 403 is returned when the plan does not include cost analytics access. Combines completed-day cost rollups with the current day's partial usage. No PII — ownerEmail, userId, and per-other-chatbot breakdowns are always stripped. Required scope: `analytics:read`. - [Detect website crawl drift](/management-api/reference/get-chatbot-crawl-drift.md): Compares a chatbot's crawled URL set for a domain against the domain's CURRENT sitemap.xml, reporting pages ADDED (in the sitemap but not yet crawled) and REMOVED (crawled but no longer in the sitemap). The domain MUST be one the chatbot has already crawled (SSRF-bounded). Content changes on already-crawled pages are NOT detected — no per-page baseline is stored for existing crawls. Required scope: `documents:read`. - [Get deployment status](/management-api/reference/get-chatbot-deployment.md): Returns the deployment status for a chatbot. Internal hosting and credential identifiers are never included in the response. Required scope: `chatbots:read`. - [List authorized domains](/management-api/reference/get-chatbot-domains.md): Returns the authorized login domains and custom domain status for a chatbot. Internal IDs and auth tokens are stripped. Required scope: `domains:read`. Requires admin-level access (`canManageAccess`); callers with only editor access will receive 404 here. - [Get infrastructure analytics](/management-api/reference/get-chatbot-infra-analytics.md): Infrastructure signals for a single chatbot at dashboard parity: latency and TTFT percentiles + histograms, region split, deploy-version timeline (regression detection), and warm-vs-cold ratio. deploymentVersion and dataRegion are owner-facing operational metadata, not user machine ids. Tier-gated (pro+). Required scope: `analytics:read`. - [Get agent quality analytics](/management-api/reference/get-chatbot-quality-analytics.md): Agent behavior & quality aggregates for a single chatbot at dashboard parity (aggregate metrics only — no raw traces, no PII). Answer-quality breakdown, agent decisions, average latency, and MCP tool-error tracking. The chatbot scope is derived server-side from the authenticated owner — no email parameter is accepted. Tier-gated (pro-plus+). Required scope: `analytics:read`. `answerRate` is `number | null`, computed only over turns the chatbot classified; it is `null` (distinct from a genuine 0%) whenever `answerRateTracked` is false — i.e. no classified turns in the window, or the metrics were temporarily unavailable. Consumers must handle `null` before arithmetic and can read `answerRateTracked` to explain the absence. - [Get query-log analytics](/management-api/reference/get-chatbot-queries-analytics.md): Row-level query log for a single chatbot at dashboard parity — the owner's own conversation log. Question and answer text are PII-redacted at insert and the end-user's email is masked. Internal session, row, and network identifiers are never emitted. Each row's sources[] is reshaped to a public citation {title, source, pdfSource} — the raw retrieved chunk text and all other internal source metadata are dropped. Tier-gated (starter+). Required scope: `analytics:read`. - [Get a scheduled crawl](/management-api/reference/get-chatbot-scheduled-crawl.md): Returns one scheduled crawl including its recent run history. No PII (authorized emails/groups are returned only as counts). Required scope: `documents:read`. - [Get a knowledge scope](/management-api/reference/get-chatbot-scope.md): Returns a single knowledge scope by id. Billing detail (costLimit) is stripped and PII rosters (emails/domains) are collapsed to counts. Required scope: `chatbots:read`. - [Get knowledge scopes](/management-api/reference/get-chatbot-scopes.md): Returns the knowledge-scope configuration for a chatbot. Required scope: `chatbots:read`. - [Get search / retrieval-quality analytics](/management-api/reference/get-chatbot-search-analytics.md): Retrieval-effectiveness aggregates for a single chatbot at dashboard parity: score histogram, per-scope retrieval quality, skip-RAG ratio, sources-per-query, and weakest queries. weakestQueries titles are k-anonymity-gated (≥3 sessions) and exposed exactly as the dashboard shows the owner. Tier-gated (pro+). Required scope: `analytics:read`. - [Get token-efficiency analytics](/management-api/reference/get-chatbot-token-analytics.md): Token-usage & latency aggregates for a single chatbot at dashboard parity: total/avg/percentile tokens, model mix, context-growth buckets, and TTFT-by-model. Aggregate-only (no raw text). Tier-gated (pro+). Required scope: `analytics:read`. - [Get video-transcription analytics](/management-api/reference/get-chatbot-transcription-analytics.md): Video-transcription aggregates for a single chatbot at dashboard parity: totals (videos, duration, cost, char/word counts) and breakdowns by service, language, platform, and model. Per-other-chatbot breakdowns are stripped. NOT tier-gated — matches the ungated dashboard route (auth + `analytics:read` + ownership only). All-time totals; no `days` parameter is applied. Required scope: `analytics:read`. - [Get usage analytics](/management-api/reference/get-chatbot-usage-analytics.md): Returns usage analytics for a single chatbot. tokenCount and queryCount are derived from cost rollup data (same tier-gating as cost analytics). Note: queryCount counts recorded cost/usage events (model calls — embeddings, completions, reranks, tool calls — plus other cost events), not user Q&A turns, so expect it to run several × the conversations/quality turn counts. documentCount is the current KB size (total docs in user_documents — not time-windowed). No PII. Required scope: `analytics:read`. - [Get a document](/management-api/reference/get-document.md): Returns a single document by ID (IDOR-guarded). Required scope: `documents:read`. - [Get an email group](/management-api/reference/get-email-group.md): Fetch one of the owner's email groups by id. Required scope: `security:read`. - [Get external-API config](/management-api/reference/get-external-api-config.md): Returns the external-API configuration for a chatbot. Key hashes are stripped; only safe key metadata is returned. Required scope: `security:read`. - [Get an MCP server](/management-api/reference/get-mcp-server.md): Returns a single MCP server by ID. Credentials, headers, and access-key hashes are stripped. Required scope: `mcp:read`. - [Get MCP server access control](/management-api/reference/get-mcp-server-access.md): Returns the access-control settings for an MCP server: authorizedEmails, authorizedGroups, isPublic, accessKeyHint. The access-key hash is never returned. Required scope: `mcp:read`. - [Get an OAuth client](/management-api/reference/get-o-auth-client.md): Get an OAuth client - [Get the Sales Agent configuration](/management-api/reference/get-sales-agent.md): Returns the chatbot's Sales Agent configuration (persona, prompt slots/overlay, model override, lead-capture fields, guardrails, and sales-trigger settings), plus `salesAgentEnabled` — whether the agent is live at runtime. Returns an empty config with `salesAgentEnabled:false` when no agent has been configured yet. Never returns access-key material or internal fields. Required scope: `chatbots:read`. - [Get a sales-agent lead (with decrypted PII)](/management-api/reference/get-sales-agent-lead.md): Reads a single captured sales-agent lead WITH decrypted PII (the audit-logged per-lead detail path). Returns the metadata the list returns PLUS the decrypted contact `pii` (name/email/phone/company/custom), the coarse geo detail (countryCode + region/city/timezone), and a `decryptError` string when server-side decrypt failed (the raw envelope, HMAC hashes, and IP hash are NEVER emitted). 404 for a missing, soft-deleted, or unauthorized lead (IDOR-safe). Owner/admin gated (PII reveal). Required scope: `security:read`. - [Get a skill](/management-api/reference/get-skill.md): Returns a single skill by ID. Required scope: `skills:read`. - [Get telemetry config](/management-api/reference/get-telemetry-config.md): Returns the telemetry configuration for a chatbot. Fields: level (anonymized|identified|full), endUserOptOutAllowed, pseudonymizeIdentifiers, retentionMonths. Required scope: `security:read`. - [Get daily API quota status](/management-api/reference/get-usage.md): Get daily API quota status - [Get a video](/management-api/reference/get-video.md): Returns a single video by ID (IDOR-guarded). Required scope: `videos:read`. - [Get YouTube connection status](/management-api/reference/get-you-tube-status.md): Reports whether the caller's YouTube account is connected, and the connected channel title when available. Never returns tokens. Account-scoped (no chatbot). Required scope: `videos:read`. - [Ingest a PDF document from a URL](/management-api/reference/ingest-chatbot-document.md): Ingests a PDF into the chatbot's knowledge base by fetching it from a PUBLIC URL (SSRF-safe: http(s) only, public-IP-pinned + rebind-safe, size- and time-bounded), then running the standard extract → chunk → embed pipeline. This endpoint is PDF-only (the fileName / URL must end in .pdf); to ingest a local file, host it at a public URL first. Asynchronous — processing continues in the background; poll GET /documents for status. Required scope: `documents:write`. - [Add text or a .txt/.md file to the knowledge base](/management-api/reference/ingest-chatbot-text.md): Adds text or Markdown straight into the chatbot's knowledge base — no file upload needed. Send a single `text` string (with an optional `fileName`) or a batch of `items` (for example curated question/answer pairs). Each entry becomes its own searchable, listable, deletable knowledge source. Processing is synchronous — the response reports per-entry results. Long entries are split automatically. Required scope: `documents:write`. - [Ingest YouTube videos into a chatbot](/management-api/reference/ingest-you-tube-videos.md): Ingests videos from the caller's connected YouTube channel into the chatbot's knowledge base. Videos already in the knowledge base are skipped (`skippedAlreadyImported`). Returns a `jobId` for the ingest. Required scope: `videos:write`. - [Invite a deployed user](/management-api/reference/invite-chatbot-user.md): Invites an end-user to the chatbot by email; the user receives a verification email. Required scope: `security:write`. - [List access-protection keys](/management-api/reference/list-access-protection-keys.md): Returns all access-protection keys for a chatbot. Key hashes are stripped; only safe metadata (id, label, keyPrefix, status, usageCount, timestamps) is returned. Required scope: `security:read`. - [List a chatbot's transcript-correction review queue](/management-api/reference/list-chatbot-corrections.md): Returns every transcript correction across the chatbot's videos as one needs-review-first queue, with per-status totals. Never returns the transcript body or the resolver identity. Required scope: `documents:read`. - [List website crawls](/management-api/reference/list-chatbot-crawls.md): Lists the chatbot's website crawls (most recent first), with live progress. Non-terminal crawls are refreshed against the crawler on read (an API-initiated crawl has no dashboard poller, so this read is what advances its status). Pass `crawlId` to fetch a single crawl. No PII (authorized emails/groups are not returned). Required scope: `documents:read`. - [List sales-agent leads (metadata only)](/management-api/reference/list-chatbot-sales-agent-leads.md): Lists a chatbot's captured sales-agent leads over the requested window. Returns METADATA ONLY — disposition, handoff status, country code, timestamps, coarse attribution, and disposition/country aggregates. NO decrypted PII (name/email/phone/custom capture fields, city, region, IP) is exposed by this list. Owner/admin gated (mirrors the dashboard leads view — CRM-sensitive disposition labels are not readable by domain-grant viewers). Required scope: `analytics:read`. - [List scheduled crawls](/management-api/reference/list-chatbot-scheduled-crawls.md): Lists the chatbot's scheduled (recurring) website crawls, most recent first. A scheduled crawl periodically re-ingests a set of URLs into the KB on an hourly/daily/weekly/monthly cadence. No PII (authorized emails/groups are returned only as counts). Required scope: `documents:read`. - [List deployed users](/management-api/reference/list-chatbot-users.md): Lists the chatbot's deployed (invited) end-users — each user's email, display name, role, status, email-verification flag, and timestamps. Requires admin-level chatbot access. Required scope: `security:read`. - [List chatbots](/management-api/reference/list-chatbots.md): Returns the chatbots you own, created on behalf of a team owner, were granted admin access to, or that are shared with a team you own or administer. Required scope: `chatbots:read`. Chatbots shared with a team where you are a plain member, and chatbots where you have only viewer/editor (non-admin) access, are not listed here — access those directly by id via `GET` / `PATCH /api/v1/chatbots/{chatbotId}`. - [List documents](/management-api/reference/list-documents.md): Returns all documents owned by the authenticated user. Required scope: `documents:read`. Optional `?chatbotId=` filter (restricted keys are scoped to their allowed chatbots automatically). Lists only documents you own, even when `chatbotId` is supplied; a chatbot's full knowledge base is not enumerated here. - [List email groups](/management-api/reference/list-email-groups.md): Lists the owner's email groups (reusable email allow-lists shared across their chatbots). Pass `includeUsage=true` to include how many documents use each group. Email groups are OWNER-scoped, not per-chatbot: a key restricted to specific chatbots still has full access to all of the owner's email groups. Required scope: `security:read`. - [List external-API keys](/management-api/reference/list-external-api-keys.md): Returns all external-API keys for a chatbot. Key hashes are stripped; only safe metadata is returned. Required scope: `security:read`. - [List MCP servers](/management-api/reference/list-mcp-servers.md): Returns all MCP servers configured for a chatbot. Credentials, headers, env vars, and access-key hashes are stripped. Email/group rosters are collapsed to counts. OAuth flows, PostgreSQL scan, and metrics are dashboard-only (not yet in v1 API). Required scope: `mcp:read`. - [List OAuth clients](/management-api/reference/list-o-auth-clients.md): List OAuth clients registered by the authenticated user. Requires Firebase authentication. - [List lead-delivery channels](/management-api/reference/list-sales-agent-handoffs.md): Lists the Sales Agent's lead-delivery (hand-off) channels. Each channel reports its recipients/routing and whether a sending secret is configured (`hasSecret`/`hasWebhookHmac`) without ever exposing the secret itself. Creating a channel is done from the dashboard (it is inseparable from storing the sending secret). Required scope: `chatbots:read`. - [List skills](/management-api/reference/list-skills.md): Returns all skills configured for a chatbot. Required scope: `skills:read`. - [List the owner's team members](/management-api/reference/list-team-members.md): Returns the caller's team/workspace + its members (userId, email, displayName, role, status, invite/accept/last-active timestamps). Workspace-level — no chatbotId. Returns the team from the caller's OWN membership (their active team), so a caller can only read a team they belong to (never cross-tenant); a member/admin sees the roster, matching the dashboard. Returns team:null for a solo user. Internal fields (permissionOverrides, invitedBy) are dropped. Required scope: `security:read`. - [List a video's transcript corrections](/management-api/reference/list-video-corrections.md): Returns a page of transcript corrections for a single video (IDOR-guarded), each with a short context snippet from the surrounding transcript so a caller can judge the most probable word. Never returns the full transcript body or the resolver identity. Required scope: `documents:read`. - [List videos](/management-api/reference/list-videos.md): Returns all videos owned by the authenticated user. Required scope: `videos:read`. Optional `?chatbotId=` filter (restricted keys are scoped to their allowed chatbots automatically). Lists only videos you own, even when `chatbotId` is supplied; a chatbot's full knowledge base is not enumerated here. - [List the caller's YouTube videos](/management-api/reference/list-you-tube-videos.md): Lists videos from the caller's own connected YouTube channel. Without `search`, returns one page plus a `nextPageToken`; with `search`, scans the whole channel by title. Returns `connected:false` as data (not an error) when no channel is connected. Exposes only public video metadata — never tokens. Account-scoped (no chatbot). Required scope: `videos:read`. - [Update access lists](/management-api/reference/patch-access-lists.md): Replace one or more access lists. Each supplied list is replaced wholesale; omitted lists are unchanged. At least one list must be provided. Requires admin-level access (`canManageAccess`). Required scope: `security:write`. - [Update access-protection config](/management-api/reference/patch-access-protection.md): Update access-protection enabled flag and/or jwtConfig (enabled, emailClaim, secret). If a new JWT secret is provided it is encrypted at rest; the plaintext is never stored. Returns the updated config (secret collapsed to hasSecret). Required scope: `security:write`. - [Update a chatbot](/management-api/reference/patch-chatbot.md): Partial update of chatbot configuration fields. Only top-level scalar/object fields accepted; nested arrays are replaced wholesale (not merged). Required scope: `chatbots:write`. The response `chatbot` field may be `null` if the document was deleted concurrently during the update (write-then-read race). - [Update a knowledge scope](/management-api/reference/patch-chatbot-scope.md): Partial update of ONE knowledge scope. Only the supplied fields change; absent fields (including `costLimit`, `authorizedEmails`, `authorizedDomains`) are preserved server-side. `null` on an optional field clears it; `[]` clears an array; `costLimit` is replaced atomically. `id` is immutable (ignored). Required scope: `chatbots:write`. - [Update knowledge scopes](/management-api/reference/patch-chatbot-scopes.md): Partial update of the knowledge-scope configuration. Write set matches GET read set exactly: `scopes`, `uiTree`, `slotWorkflows`, `defaultSlotId`, `defaultScopeLabel`, `showDefaultScopeInSelector`. Unknown fields are ignored. Legacy scope fields (knowledgeScopes, defaultScopeId, scopeRelationships, scopeCanvasLayout, scopeWorkflows, activeScopeWorkflowId) are not managed via this endpoint. Required scope: `chatbots:write`. - [Update external-API config](/management-api/reference/patch-external-api-config.md): Update the external-API enabled flag and/or rate limit. Required scope: `security:write`. - [Update an MCP server](/management-api/reference/patch-mcp-server.md): Partial update of an MCP server configuration. Supports: enabled toggle, modelOverride, credential update, tool re-discovery, accessKeyAction (generate/clear), executionMode, allowUiResources, allowLlmCompletion. OAuth flows, PostgreSQL scan, and metrics are dashboard-only (deferred). Required scope: `mcp:write`. - [Update a skill](/management-api/reference/patch-skill.md): Partial update of a skill. Can update: name, description, body, enabled, mode, linkedServerIds, linkedAgentIds. Immutable fields (id, createdAt, source, sourceServerId) are ignored in the request body. Name must remain unique within the chatbot. Required scope: `skills:write`. - [Replace authorized email list](/management-api/reference/put-document-authorized-emails.md): Replace the authorized email list for a document. Required scope: `documents:write`. - [Update MCP server access control](/management-api/reference/put-mcp-server-access.md): Replace the access-control settings for an MCP server. Supports: isPublic, authorizedEmails, authorizedGroups, and accessKeyAction. When accessKeyAction=generate a one-time plaintext accessKey is returned. Required scope: `mcp:write`. - [Replace telemetry config](/management-api/reference/put-telemetry-config.md): Replace the telemetry configuration for a chatbot. All four fields are required. When `containsSensitiveData` is true on the chatbot, `level` must be 'anonymized' and `endUserOptOutAllowed` will be forced to false. Required scope: `security:write`. - [Revoke a deployed user](/management-api/reference/remove-chatbot-user.md): Revokes a deployed user's access to the chatbot (disables their account). Required scope: `security:write`. - [Resolve a transcript correction](/management-api/reference/resolve-video-correction.md): Resolves a single correction on a video (IDOR-guarded): accept a suggested/candidate word, reject it, apply custom text, or undo a previous resolution. Accepting or applying custom text rebuilds the transcript and re-embeds it in the background. Required scope: `documents:write`. - [Revoke an access-protection key](/management-api/reference/revoke-access-protection-key.md): Revoke (soft-delete) an access-protection key. Revoked keys are immediately rejected; they remain in the list with status=revoked for audit purposes. Required scope: `security:write`. - [Revoke an external-API key](/management-api/reference/revoke-external-api-key.md): Revoke (soft-delete) an external-API key. Revoked keys are immediately rejected. Required scope: `security:write`. - [Start a website crawl](/management-api/reference/start-chatbot-crawl.md): Crawls one or more website URLs into the chatbot's knowledge base (embedded as searchable vectors), mirroring the dashboard website-crawl flow. Provide a single `url` or a `urls` array (max 100; the App batches into ≤10-per-request worker calls). Asynchronous — returns 202 with a crawlId + jobId; poll `GET /crawls` to track progress. Refuses a second in-flight crawl for the same domain + version (409). Requires admin-level chatbot access (owner / team admin / per-chatbot admin) — plain team editors cannot crawl via this API. Required scope: `documents:write`. - [Update a scheduled crawl](/management-api/reference/update-chatbot-scheduled-crawl.md): Updates a scheduled crawl. Any subset of the mutable fields may be provided; at least one is required. Changing the cadence recalculates the next run time. Required scope: `documents:write`. - [Update chatbot runtime settings](/management-api/reference/update-chatbot-settings.md): Updates the chatbot's runtime toggles: web search, unanswered-question tracking, long-term conversation memory, and short-term memory strategy. Mirrors the dashboard settings screen. Enabling long-term memory requires a Pro (or higher) plan AND authentication-required access. Disabling long-term memory, or switching the memory strategy away from 'graph', permanently deletes the stored memory and therefore requires `confirmDelete: true`. Only provided fields change; at least one must be present. Required scope: `chatbots:write`. - [Update document privacy](/management-api/reference/update-document-privacy.md): Update the privacy/access level of a document. Required scope: `documents:write`. - [Update an email group](/management-api/reference/update-email-group.md): Update an email group's name and/or member emails (provide at least one). Required scope: `security:write`. - [Update the Sales Agent configuration](/management-api/reference/update-sales-agent.md): Upserts the Sales Agent configuration. The agent doc is created on the first update (`created:true`). Only known config fields are applied; unknown fields are ignored. Configuring the agent does not enable it at runtime — enablement is a separate control. Required scope: `chatbots:write`. - [Update a lead-delivery channel](/management-api/reference/update-sales-agent-handoff.md): Updates an existing lead-delivery channel (recipients, routing mode, verified sender, webhook URL, included fields, enable/disable). The sending secret cannot be set here — it is managed from the dashboard, and enabling a channel requires its secret to already exist. Required scope: `chatbots:write`. - [Verify domain DNS](/management-api/reference/verify-chatbot-domain.md): Triggers a DNS verification check for the given domain. Returns `verified: true` when DNS is correctly configured; `verified: false` with a pending message when DNS is not yet propagated. Required scope: `domains:write`. - [WizChat Management API](/management-api/reference/wizchat-management-api.md): Programmatic control plane for WizChat chatbots. Authenticate with a `wpk_live_…` Management API key or a Firebase ID token. All endpoints are scoped — see the `x-scope` extension on each operation. ## security ### access-control Role-based access control and permissions in WizChat - [Access Control](/security/access-control.md): Role-based access control and permissions in WizChat ### data-residency Control where your data is stored for GDPR compliance - [Data Residency](/security/data-residency.md): Control where your data is stored for GDPR compliance ### data-retention Understand how long different types of data are kept on WizChat - [Data Retention](/security/data-retention.md): Understand how long different types of data are kept on WizChat ### encryption How WizChat protects your data with encryption - [Encryption](/security/encryption.md): How WizChat protects your data with encryption ### pii-protection How WizChat detects and redacts personally identifiable information - [PII Protection](/security/pii-protection.md): How WizChat detects and redacts personally identifiable information ### zdr Maximum privacy with zero data retention mode - [Zero Data Retention (ZDR)](/security/zdr.md): Maximum privacy with zero data retention mode ## teams ### chatbot-transfer Transfer ownership of a chatbot to another user - [Chatbot Ownership Transfer](/teams/chatbot-transfer.md): Transfer ownership of a chatbot to another user ### creating Create a team to collaborate with others on chatbots - [Creating a Team](/teams/creating.md): Create a team to collaborate with others on chatbots ### invitations Invite people to join your team - [Inviting Members](/teams/invitations.md): Invite people to join your team ### roles-permissions Understand team roles and what each can do - [Roles & Permissions](/teams/roles-permissions.md): Understand team roles and what each can do ### share-requests How team members can request to share chatbots with the team - [Share Request Workflow](/teams/share-requests.md): How team members can request to share chatbots with the team ### sharing Share chatbots with your team or specific individuals - [Sharing Chatbots](/teams/sharing.md): Share chatbots with your team or specific individuals ### team-ownership-transfer Transfer ownership of your entire team to another member - [Team Ownership Transfer](/teams/team-ownership-transfer.md): Transfer ownership of your entire team to another member ## troubleshooting ### common-issues Solutions to frequently encountered problems - [Common Issues](/troubleshooting/common-issues.md): Solutions to frequently encountered problems ### errors Reference for error messages and their solutions - [Error Messages](/troubleshooting/errors.md): Reference for error messages and their solutions ### faq Frequently asked questions about WizChat - [Frequently Asked Questions](/troubleshooting/faq.md): Frequently asked questions about WizChat