Connecting Guru to Your Chatbot

If you already have a chatbot, whether an internal help bot, a support widget, or a custom LLM app, Guru can be the knowledge behind it. There are three integration patterns, and the right one depends mostly on one question: does your chatbot maintain conversation context and write its own answers?

Your chatbot	Pattern to use
Has its own LLM that tracks the thread and synthesizes answers	Retrieval: `/search/documents` or the MCP server's Search tool
Is a thin layer that displays whatever it receives	Answers: `/chat/ask-async` or the MCP server's Ask tool

A closer comparison:

Pattern	Who writes the answer	Multi-turn aware	Content covered	Build effort
Retrieval (`/search/documents`)	Your LLM	Yes, your bot owns the thread	Cards and connected Sources	Medium
Answers (`/chat/ask-async`)	Guru	Yes, pass `chatThreadId` to continue a thread	Cards and connected Sources	Low
MCP server	Your LLM or Guru, depending on the tool	Yes	Cards and connected Sources	Low, if your platform is an MCP client

Retrieval: your bot asks Guru for documents

This is the pattern to reach for when your chatbot is built on a modern, context-aware LLM. It puts retrieval where Guru is strongest and synthesis where your bot already has the context: the full conversation, the user's role, and whatever else your system knows.

POST https://api.getguru.com/api/v1/search/documents

curl -X POST https://api.getguru.com/api/v1/search/documents \
  -u $GURU_USER:$GURU_TOKEN \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "{agentId}",
    "searchTerms": "how do I reset my password"
  }'

Field	Description
`agentId`	The Knowledge Agent to search with. You can find it on the API tab of the Knowledge Agent you'd like to use.
`searchTerms`	What to search for.

The response contains the relevant Guru cards and connected-source documents. Your chatbot reads those results and synthesizes the answer.

Choose this pattern when:

Your chatbot's LLM is context-aware (the common case).
Guru is one tool among several, and you combine its results with ticket history, CRM data, or product telemetry.
You want your own prompt to control answer tone, format, and length so responses match your existing bot.

📘
You own answer quality in this pattern
Guru returns the documents; your model writes the answer. Review how your bot passes results to the model, and implement the search as a tool call rather than a fixed pre-processing step, so the model decides when to search and can search again on follow-ups.

Have your bot surface links back to the Guru cards it used. Citations preserve trust and give users a path to the full context.

Answers: Guru writes the response

If your chatbot has no LLM of its own, or you don't want to own prompt engineering and answer quality, let the Knowledge Agent do the retrieval and the reasoning. Guru returns a finished answer with cited sources.

POST https://api.getguru.com/api/v1/chat/ask-async

curl -X POST https://api.getguru.com/api/v1/chat/ask-async \
  -u $GURU_USER:$GURU_TOKEN \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "{agentId}",
    "question": "How do I reset my password?"
  }'

Only question is required; omit agentId and Guru routes to the default agent. A 200 means the answer is ready in that same response. A 202 means Guru is still working and returns a chatThreadId and turnId your bot polls until the answer is ready. Ask a Question covers the full flow, including the status values to branch on and how multi-turn conversations work: pass the chatThreadId back on the next question and Guru holds the thread, so "how do I request PTO?" followed by "what about for contractors?" resolves correctly.

If your questions are consistently fast and you want to avoid polling entirely, POST /api/v1/chat/ask returns the finished answer in a single call.

This pattern brings the full Knowledge Agent along, not just its knowledge. Skills configured on the agent fire when the endpoint is called, shaping the answer's tone, length, and format, and if the agent is connected to external MCP servers, it can call them while producing the answer. Your bot displays the result; the agent's configuration in Guru controls how it behaves.

Choose this pattern when:

The surface is thin: a deflection widget, an FAQ bot, a "search the handbook" slash command, a ticket-form suggestion box.
You want Guru's answer quality and citations out of the box with minimal engineering.
You'd rather tune behavior in the Knowledge Agent's configuration than in your own prompt.

Connect the MCP server

The MCP server delivers both patterns above as tools your agent calls through the Model Context Protocol: its Search tool is the retrieval pattern, and its Ask tool is the answers pattern. If your chatbot platform is already an MCP client (Claude, most modern agent frameworks, and several major chat platforms), this is the fastest path: no custom retrieval code to write or maintain, and your bot can use whichever tool fits each moment. See Available Capabilities for the full tool list and Authentication & Connection Setup to connect.

Prefer calling the API directly when you need fine-grained control over search parameters, filtering, or result post-processing, or when your platform isn't an MCP client.