Knowledge base APIs: answer questions with instructions

A traditional knowledge base waits for a user to find the right article. Search boxes, topic trees and long pages add steps at the moment someone needs help. An API changes the entry point: the product sends a question, and a service returns a relevant answer and the material behind it.

Instructions work especially well here because they describe specific tasks. The result can include a short answer, a link to the relevant guide and, when useful, a GIF showing the next action.

What should an API response include?

Return content that can be shown in a product and checked by a person. A useful minimum is the answer text, the source title and ID, a direct link to the guide, and metadata your application needs to render it.

{
  "answer": "Open Settings → Payment and add a card.",
  "source": { "title": "Update your payment method", "url": "/guides/payment" },
  "language": "en"
}

Confidence, update time and content type can help your app choose how to display a result. You do not need to show every field to the user, but they help support teams review answers.

Design the path from question to guide

1. Collect the question and safe context. Pass only what helps find an answer, such as language, product area or user role. Do not send secrets or unnecessary personal data.
2. Find relevant material. Search should consider meaning, not only matching words. A person may ask to “change my card” while the guide is called “Update your payment method.”
3. Build the answer from a source. State the action briefly and keep a link to the relevant guide. If nothing matches, ask a clarifying question or show a support channel instead of guessing.
4. Offer a next step. A simple request may need only one or two actions. Keep a link to the full guide nearby for people who want more detail.

Why source links matter

An answer without a source is hard to verify and maintain. The user cannot inspect the full process, and the team cannot tell which version of the knowledge base was used. A direct source link gives people a transparent path from a quick answer to the complete explanation.

It also makes errors easier to diagnose. If the wrong guide appears, the team can review the question and metadata, improve tags or clarify a title. Link to the specific guide rather than a generic help-center homepage.

Prepare your guides before integrating

An API cannot fix a contradictory knowledge base. Start with tasks that often generate support requests and make sure the guides:

• use titles that match the tasks people ask about;
• follow a clear sequence and keep separate workflows apart;
• state conditions such as role, plan or interface version;
• show publication status and last review date;
• are visible only to the right audience when some content is internal.

Add common wording and synonyms to descriptions. Keep stable guide IDs and links between related topics, such as card updates, invoices and plan changes.

Build a safe fallback

Decide what happens when no answer is found: ask a follow-up question, offer help-center search or hand the conversation to a person. Make network errors, empty results and unavailable sources understandable. The product should still offer a clear path when the API is down.

Measure whether answers help

Track questions with no match, which sources are selected and what users do next. Collect answer feedback, measure guide clicks and watch for repeat requests on the same task. Test a small set of common questions first, review results manually and expand gradually.

← Read more articles