Frequently Asked Questions
Everything you need to know about BeforeQuery.
General
What is BeforeQuery?
BeforeQuery is an AI Knowledge Assistant that connects your documentation, code, tickets, and internal knowledge sources. It provides accurate answers with source citations via an embeddable widget, Slack/Discord bots, and a REST API.
How is BeforeQuery different from just using ChatGPT?
ChatGPT answers from its training data, which does not include your product documentation, internal wikis, or private repositories. BeforeQuery retrieves from your specific knowledge sources and cites the exact document each answer came from — so users can verify and trust the response.
Do I need machine learning expertise to use BeforeQuery?
No. You connect a source (a URL, a GitHub repo, a Notion workspace) and BeforeQuery handles chunking, embedding, indexing, retrieval, and generation. There is no model to fine-tune or infrastructure to manage.
RAG & Citations
What is RAG and why does it matter?
RAG stands for Retrieval-Augmented Generation. Instead of generating answers from model training data alone, RAG retrieves relevant documents first, then generates an answer grounded in those documents. This eliminates hallucinations about your specific product and makes every answer verifiable via citation links.
How are citations generated?
During retrieval, each source chunk is tracked with its URL and page title. The generation prompt instructs the LLM to cite sources inline. The response JSON includes a structured citations array with the URL, title, and excerpt for every source chunk used to construct the answer.
What happens when BeforeQuery cannot find a good answer?
When retrieval confidence falls below the configured threshold, BeforeQuery returns a transparent fallback message rather than hallucinating. You configure the fallback text — typically a message directing users to a support channel or telling them what to search for in your docs.
How does the hybrid search work?
BeforeQuery combines semantic vector search (meaning-based) with BM25 keyword matching (term frequency-based). Results from both are merged using reciprocal rank fusion, then re-ranked with a cross-encoder model. This finds the right chunk even when users phrase questions very differently from how the docs are written.
Sources & Integrations
Can BeforeQuery index GitHub and GitLab repositories?
Yes. Connect a GitHub or GitLab repository and specify which paths to index — for example README.md, docs/, ADRs, and changelogs. BeforeQuery installs a webhook that triggers an incremental re-index on every push to the configured branch, so the index is always current without manual intervention.
Does repo indexing work with self-hosted GitLab?
Yes. BeforeQuery supports both GitLab.com and self-hosted GitLab instances. You provide the instance URL and a personal access token with read_repository scope.
Which helpdesk platforms does BeforeQuery integrate with?
BeforeQuery integrates natively with Zendesk, Freshdesk, Front, Jira Service Management, Linear, and Salesforce Service Cloud. Each integration adds an AI copilot panel that drafts replies inside the helpdesk UI, cited from your knowledge base. Agents can review, edit, and send — or you can enable auto-resolve for tickets above your configured confidence threshold.
How does ticket deflection work and what is the confidence threshold?
When a user submits a support ticket or contacts your team, BeforeQuery checks whether it can answer with high confidence. If the confidence score exceeds your threshold (you set this per project), the ticket is resolved automatically and the user receives the answer immediately — no agent required. Tickets below the threshold route normally to a human agent. You can adjust the threshold at any time, and simulation mode lets you preview the deflection rate on historical tickets before enabling live deflection.
Can I test Support Automation before enabling it in production?
Yes — this is what simulation mode is for. Import historical tickets from your helpdesk and run BeforeQuery against them. You see the draft answer, confidence score, and whether each ticket would have been auto-resolved. Review the quality ticket by ticket, tune your threshold, and enable live deflection only when you are satisfied. Nothing is sent to customers during simulation.
What is the MCP server and how do I use it?
Every BeforeQuery project exposes a Model Context Protocol (MCP) server at POST https://api.beforequery.com/mcp/projects/:projectId. Authenticate with your X-Client-Key header. Any MCP-aware AI application — Cursor, Windsurf, Claude Desktop, or your own LLM wrapper — can call this endpoint to list and invoke your project's knowledge as structured MCP tools. No additional configuration is required; the MCP server is active on all Pro and Enterprise projects.
Does BeforeQuery support Shopify and SharePoint?
Yes. The Shopify connector indexes your products, collections, and store pages — so your chat widget can answer product Q&A from your actual catalog. The SharePoint connector indexes SharePoint sites, document libraries, and pages for enterprise knowledge bases. Both connectors sync on a schedule and support incremental updates.
How do the Slack and Discord bots work?
Once installed, the Slack bot responds to the /askai slash command and to direct @mentions in any channel it is invited to. The Discord bot works the same way. Both bots use the identical RAG pipeline as the widget and return answers with citation links inline. Responses are posted in-thread by default to keep channels tidy.
What is the difference between the web widget, the React component, and the JavaScript SDK?
The web widget (hosted at widget.beforequery.com) is a single script tag — zero configuration, works on any HTML page, no framework required. The @beforequery/react package provides a <BeforeQueryChat /> drop-in component and a useBeforeQuery headless hook for full control over the UI. The @beforequery/sdk package is framework-agnostic and targets Vue, Svelte, vanilla JS, React Native, and Node.js server-side integrations.
What are Collections and how do per-collection permissions work?
Collections are named groups of sources within a project. You can issue client keys scoped to one or more collections, so a public-facing widget only queries your public docs while an internal tool can query internal wikis. Per-collection permissions are enforced at the API level — a key outside its allowed collections receives an authorization error.
Does BeforeQuery support versioned documentation?
Yes. You can tag sources with a version label (v1, v2, latest, etc.) and issue client keys scoped to a specific version. Users always receive answers from the version of the docs that matches their product version.
AI Actions & Agent Platform
What are AI Actions?
AI Actions let BeforeQuery call your own customer APIs from within a chat conversation. For example, a user asking 'What is the status of my order?' can trigger a call to your order-status API and receive a real-time answer — not just a link to a docs page. You define the API endpoints, parameters, and authentication. BeforeQuery handles calling them and weaving the response into the AI answer with citations.
How do approval rules work for AI Actions?
Each AI Action has a configurable approval policy. Low-risk, read-only actions (like order status or account lookups) can be set to auto-approve — they execute immediately when triggered. Sensitive actions (like account modifications or refund requests) can require human approval. When a human-approval rule triggers, the action pauses, an approver is notified via Slack or email, and execution resumes only after explicit approval. You can also set an auto-expire policy that applies a default decision if no response arrives within a configured timeout.
What is the Agent Platform?
The Agent Platform lets you build multi-agent workflows on top of your BeforeQuery knowledge base. You define a coordinator agent that receives user input and delegates to specialist agents — each with their own tools, knowledge scope, and persona. Human-approval nodes can pause execution at any step for human review. Every run produces a full observability trace showing latency, token cost, retrieved chunks, and decisions per step.
What is the @beforequery/agents SDK?
It is an open-source TypeScript package (npm install @beforequery/agents). It provides runAgent for executing a single agent, defineAgent for declaring graph nodes and edges in code, mcpClient for calling MCP servers as tools, and a2aClient for calling external A2A agents. It runs in Node.js 18+, Vercel Edge, Cloudflare Workers, and other standard serverless environments. It is MIT licensed.
Security & Privacy
Is my documentation data shared with other customers?
No. Each project is fully isolated. Your indexed content, vectors, and analytics data are scoped to your workspace and are never used to answer questions for other customers.
Is BeforeQuery SOC 2 compliant?
BeforeQuery is SOC 2 Type II certified. Contact us for our security report and to sign a DPA for Enterprise plans.
Where is my data stored?
Data is stored in the US by default. EU data residency is available on Enterprise plans. All data is encrypted at rest (AES-256) and in transit (TLS 1.3).
Do you support SSO?
Yes. Enterprise plans include Single Sign-On via OIDC and SAML 2.0. We support Okta, Azure AD, Google Workspace, OneLogin, and any SAML-compliant identity provider.
Is the widget protected against abuse?
Yes. The hosted widget at widget.beforequery.com is protected by Google reCAPTCHA. This prevents automated bots from consuming your question quota. reCAPTCHA runs invisibly and does not add friction for real users. You can disable it for internal or authenticated surfaces.
How are client keys secured?
Public client keys (bq_pk_...) are safe to embed in client-side code — they grant access only to the specific project and collections they were issued for, and only to the Chat and Search endpoints. Backend integrations use a client ID and secret pair (bq_ci_.../bq_cs_...) which must never be exposed client-side.
Pricing & Limits
Is there a free plan?
Yes. The Free plan includes 1 project, 500 indexed pages, and 100 AI questions per month. No credit card required.
What counts as an AI question?
Any call to the Chat API or a user interaction via the widget, Slack bot, or Discord bot that generates an answer. Search API queries (keyword or vector search without generation) do not count toward the question limit.
Can I try Pro before paying?
Yes. Pro comes with a 14-day free trial. No credit card required to start.
What happens if I exceed my monthly question limit?
You are notified at 80% and 100% of your limit. You can upgrade mid-month at any time. If you choose not to upgrade, new questions return the fallback message until the limit resets on your billing date.