canonical: https://jentic.com/apis/botsonic.ai/botsonic # Botsonic-Api-Docs The Botsonic API builds and serves AI chatbots trained on your own content. An agent creates and configures bots, trains them by uploading files, raw text, or bulk URLs, and generates chatbot responses either synchronously or as a stream. It manages each bot's FAQs and starter questions, reads conversations along with the source behind each answer, and retrieves a bot's API token for embedding. Several operations require business access. ## For AI agents Build and run AI chatbots: create bots, train them on files, text, or URLs, generate sync or streaming responses, manage FAQs and starter questions, and read conversations. ## Scope Does not send email or SMS, host a live-agent helpdesk, or run voice calls. Use for building and serving AI chatbots only. ## Capabilities - Generate a chatbot response, synchronously or streamed, for a user message - Create and configure bots and retrieve their details - Train a bot by uploading files, raw text, or bulk URLs - Manage a bot's FAQs and starter questions - Read a bot's conversations, including the source behind each answer - Retrieve a bot's API token for embedding ## Use cases ### Agent-served support bot An AI agent answers customer questions through a Botsonic bot. Through Jentic the agent sends a user message to the response operation and reads back the answer, synchronously for a single reply or streamed for a typing effect. Because each bot is trained on the company's own content, the answers stay grounded in that material. Example prompt: Send a user question to a bot's response operation and return the generated answer ### Content-trained bots A team grounds a bot in its own documentation. The bot-data operations ingest training content as an uploaded file, raw text, or a bulk list of URLs, so an agent can build or refresh a bot's knowledge from a help center or a set of documents. The bot then answers from that content rather than generic knowledge. Example prompt: Bulk-upload a list of help-center URLs to a bot, then generate a response to confirm it answers from them ### Conversation review A team audits what its bot is telling customers. The conversation operations return a bot's conversations, including the source behind each answer, so an agent can review transcripts, spot gaps, and decide what new training content to add. This closes the loop between serving answers and improving them. Example prompt: List a bot's recent conversations with their answer sources and summarize the questions it could not answer well ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | `/v1/business/botsonic` | Generate Sync Or Streaming Response | | POST | `/v1/business/bot` | Create Bot | | GET | `/v1/business/bot/all` | Get All Bots | | POST | `/v1/business/bot-data/upload-file` | Upload File | | POST | `/v1/business/bot-data/bulk-upsert-urls` | Bulk Upload Urls | | GET | `/v1/business/bot-data/conversations/all` | Get All Conversations | | POST | `/v1/business/bot-faq` | Create Single Faq | | POST | `/v1/business/bot-starter-questions` | Create Starter Question | ## Key resources - **Bots** — Create, read, and delete bots and retrieve a bot's API token - **Responses** — Generate synchronous or streaming chatbot responses - **Bot data** — Train a bot by uploading files, text, or bulk URLs - **FAQs and starter questions** — Manage a bot's FAQs and starter questions - **Conversations** — Read a bot's conversations and the source behind each answer ## AI readiness This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use. - **Score:** 57 / 100 - **Maturity:** Foundational - **Dimensions:** - Foundational Compliance: 52 / 100 - Developer Experience & Jentic Compatibility: 62 / 100 - AI-Readiness & Agent Experience: 45 / 100 - Agent Usability: 94 / 100 - Security: 50 / 100 - AI Discoverability: 64 / 100 - **View full report:** https://jentic.com/apis/botsonic.ai/botsonic/scorecard - **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/ - **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview ### Score it yourself Every API in the directory is allowlisted, so you can re-score it with no key required. - **Score your own API:** https://jentic.com/scorecard.md - **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md ```sh npx @jentic/api-scorecard-cli score ``` ## Why Jentic - **Setup:** Wiring the Botsonic API by hand means handling three API-key headers (a bot key in X-BOT-KEY, a user key in USER-API-KEY, and a bot token in the token header), choosing the right one per operation, and managing training-data uploads yourself. Through Jentic you install once, import it from the API Directory, store the keys once, and your agent calls it. - **Permission scoping:** The Botsonic API puts the bot id in the URL path (`/v1/business/bot/{bot_id}`), so a rule can pin your agent to one bot: it can generate responses and read that bot's conversations without reaching bot deletion or other bots. You choose the operations it may call, so deleting a bot or its data is not included unless you add it. - **Credential handling:** Your Botsonic keys are held once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'generate a chatbot response' or 'train a bot on documents', and Jentic returns the matching Botsonic operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Intercom** — Customer messaging with an AI support bot and live chat - **Tidio** — Live chat and AI chatbots for small businesses - **Drift** — Conversational marketing and sales chat ## FAQ ### What authentication does the Botsonic API use? The Botsonic API authenticates with API keys sent in request headers per its OpenAPI spec: a bot key in the X-BOT-KEY header, a user key in the USER-API-KEY header, and a bot token in the token header, each used by different operations and requiring business access. Through Jentic the keys are injected at call time by your own Jentic One instance, so they never enter the agent's prompt or logs. ### Can I train a Botsonic bot on my own content? Yes. The bot-data operations ingest training content three ways: upload a file, upload raw text, or bulk-upload a list of URLs. Once the content is added, the bot's responses draw on it when it answers a user. ### What are the rate limits for the Botsonic API? The OpenAPI spec does not specify rate limits, and several operations require business access. Check the Botsonic documentation at https://botsonic.ai for current limits and plan requirements. ### Is there a Botsonic MCP server? You don't need an MCP server to give your agent the Botsonic API. Jentic connects it directly from the API Directory: import it, store your keys once, and your agent calls it, so you skip installing and syncing a separate server. ### Can I limit what my agent is allowed to do with the Botsonic API? Yes. Write a rule that allows only the response-generation and conversation-read operations for one bot, so your agent can answer and review conversations but cannot delete the bot or its training data. Every call it makes is logged. ### How do I generate a chatbot response with the Botsonic API through Jentic? Search Jentic for 'generate a chatbot response' and it returns the response operation with its input schema; the agent passes the bot key and the user message and reads back the answer, synchronously or streamed. To run it on your own infrastructure, install Jentic One from its GitHub repo.