# What the onmsg Site API Can Do | onmsg > A clear map of the onmsg site API: ask the AI a question, read a conversation, hand a conversation into the human inbox, and manage knowledge sources. URL: https://onmsg.app/guide/what-the-onmsg-site-api-can-do/ Last-Modified: 2026-09-08 Guide # What the onmsg Site API Can Do A clear map of the onmsg site API: ask the AI a question, read a conversation, hand a conversation into the human inbox, and manage knowledge sources. Published September 8, 2026 · 5 min read ![API endpoints connecting into a chat workspace](/images/featured/modern-3d-illustration-of-api-endpoints-connecting.webp) ## A deliberately small API The site API that ships with Multi-Site & API [/features/multi-site-api/ →](/features/multi-site-api/) is not a general-purpose platform API, and it is more useful for it. It covers the things a custom implementation actually needs and stops there. Five capabilities, all scoped to a single site: - **Ask the AI a question** and get an answer grounded in that site’s knowledge - **Read a conversation** - **Hand a conversation into the site’s human inbox** - **List, add or replace, and delete knowledge sources** - **Read site configuration and usage information** Everything below is what those five make possible. ![API capabilities shown as labelled cards: ask, read, hand off and manage knowledge](/images/content/api-capabilities-shown-as-labelled-cards-ask-read-.webp) ## Ask the AI a question This is the endpoint most custom builds start from. Send a question, get an answer built from that site’s knowledge base, using the grounding configuration you set up in the Grounded AI Agent & Knowledge Base [/features/grounded-ai-agent/ →](/features/grounded-ai-agent/) . The point is that the answer behaves the same as it would in the widget. Strict mode still gates on retrieval. Your refusal message is still your refusal message. You are building a different interface, not a different agent, which means you do not have to reason about two sets of behaviour. Typical uses: a help search box that answers rather than lists links, chat inside a logged-in product, or an assistant embedded somewhere the widget cannot go. ## Read a conversation Retrieve a conversation’s content. Useful for surfacing a customer’s chat history inside your own admin, for archiving, or for building a view your team already lives in. ## Hand a conversation into the human inbox The escalation path, available programmatically. Your custom interface can decide a conversation needs a person and route it into the site’s Shared Team Inbox [/features/shared-team-inbox/ →](/features/shared-team-inbox/) , where it appears with its history intact for a teammate to pick up. This is what stops a custom build becoming a dead end. Without it, an API-driven chat would have to invent its own handoff and its own inbox, which is a much bigger project than it looks. ## Manage knowledge sources ![A documentation pipeline updating knowledge sources through the API automatically](/images/content/modern-3d-illustration-of-a-documentation-pipeline.webp) List, add or replace, and delete knowledge sources. This is the quiet favourite among teams whose documentation changes often. The pattern: when your docs, price list or policies change, your pipeline pushes the updated content as a replacement source. The knowledge base stays current without anyone remembering to log in, which is the failure mode that quietly degrades most AI chat setups after month three. Worth keeping the product’s limits in mind while designing that pipeline. A URL import handles one page rather than crawling, scanned PDFs need OCR before import, and quotas count sources and calculated pages, where a page is 3,000 characters of extracted text. ## Read configuration and usage Read site configuration and usage information. For agencies, this is how per-client usage gets into a dashboard the client already looks at. For product teams, it is how you notice a limit approaching before it becomes a support conversation. ## Site-scoped keys Every key belongs to one site. That is a security property rather than an inconvenience: an integration built for one client cannot reach another’s conversations or knowledge, and a compromised key has a contained blast radius. If you run several sites, generate a key per site and treat them as separate credentials, because that is exactly what they are. Managing multiple websites and brands [/guide/managing-multiple-websites-and-brands/ →](/guide/managing-multiple-websites-and-brands/) covers the wider structure. ## What it does not do It does not replace the inbox, the flow builder or the widget. It complements them. Most implementations use the API for one specific surface and the widget for everything else, and share the same knowledge base and the same team between them. ## Two builds these five endpoints support well **A help-centre search that answers.** Instead of returning ten links, the search box sends the query to the ask endpoint and shows a grounded answer with the links underneath. Visitors who wanted the answer get it; visitors who wanted the document still have it. When the answer is a refusal, the same interface offers the handoff. **An in-product assistant.** Chat inside a logged-in application, where the widget would look foreign and where you already know who the user is. Your interface handles the presentation and the identity; the API handles the answer and the escalation. Both builds share one property worth designing for from the start: they should be able to give up. An assistant that cannot hand off is a dead end wearing a friendly face, and the hand-off endpoint exists so that never has to happen. ## Practical notes before you build **Handle refusals as a first-class state.** Strict mode is designed to refuse, and your interface should treat that as an expected response rather than an error. Show the refusal, offer the handoff. **Do not cache aggressively.** If your pipeline updates knowledge sources, cached answers will outlive the content they were built from. **Keep keys server-side.** A site-scoped key is contained, but it should still not be shipped in client-side code. **Watch usage per site.** Reading usage information programmatically lets you notice an approaching limit before a visitor does. **Test the escalation path in staging.** The handoff is the part that touches humans, and it is the part most likely to be discovered broken in production. ## Where to start Build the ask endpoint first and put it somewhere low-risk, like an internal tool. Once you trust the answers, add the handoff path, then the knowledge management. Doing it in that order means every stage is useful on its own, and none of it is blocked on the next. Read next: when to use the widget vs the API [/guide/when-to-use-the-widget-vs-the-api/ →](/guide/when-to-use-the-widget-vs-the-api/) . ## Learn more about Multi-Site & API One workspace organized around sites, with per-site configuration and a site-scoped API to ask the AI, read conversations, hand off, and manage knowledge. Read the feature page [/features/multi-site-api/ →](/features/multi-site-api/) FAQ ## Questions people ask about this ### Are API keys per site or per account? Per site. A key is scoped to the site it belongs to, which keeps a client or product integration contained and means a leaked key cannot reach your other sites. ### Can the API hand a conversation to a human? Yes. It can hand a conversation into that site's human inbox, which is the same handoff the widget triggers. From there your team sees it with its history intact. ### Can I manage knowledge through the API? Yes. List, add or replace, and delete knowledge sources. That is what makes an automated documentation pipeline possible without anyone opening the admin workspace. ## Related guides ### Managing Multiple Websites and Brands from One Workspace Run chat across several websites and brands from one workspace, with separate configuration, conversations, knowledge, flows and team per site. Read guide [Managing Multiple Websites and Brands from One Workspace →](/guide/managing-multiple-websites-and-brands/) ### When to Use the Embeddable Widget vs the API Choose between the drop-in widget for fast standard installs and the API for custom UIs and integrations, and when to combine both. Read guide [When to Use the Embeddable Widget vs the API →](/guide/when-to-use-the-widget-vs-the-api/) ## Want to try this on your own site? No credit card required. Start free [https://chat.onmsg.app →](https://chat.onmsg.app)