Skip to content

Knowledge

Answer a question

Searches the workspace’s articles for the words in the question and returns the best-matching article’s text as the answer. It is a local keyword search: nothing is generated, no credits are used, and generated is always false.

POST/api/v1/knowledge-ai/answer
  • Bearer API key
  • Scope: write
  • or app session
  • Workspace: X-Tenant-ID (optional with a key)

Headers

  • Authorizationstringrequired

    Your API key as Bearer <key>. The word Bearer and the space are case-sensitive. Browser clients signed in to the app use the session cookie instead.

    Constraints
    Keys start with pk_live_ and are 56 characters long.
    Example
    Bearer pk_live_…
  • X-Tenant-IDuuidoptional

    Workspace id. Optional with an API key (a key always acts in its own workspace); if you send it, it must match the key’s workspace. Required with a session cookie. You can pass ?tenant=<id> instead.

    Example
    8d0f6c2e-3b1a-4c55-9a7e-2f4b6d1e9c30

Body

application/json
  • questionstringrequired

    The question to answer.

    Constraints
    3–2000 characters.
    Example
    Can I return an item without a receipt?

Response

200 OKapplication/json

  • answerstring

    Text of the best-matching article, cut to 1200 characters (with …) when longer. When nothing matches: No matching document found. Add your business information to the knowledge base, or try a more specific question.

  • sourcestring

    Title of the matching article, or an empty string when nothing matched.

  • modestring

    Always local_keyword_retrieval.

  • credits_usedinteger

    Always 0.

  • generatedboolean

    Always false: the answer is copied from an article, not written by AI.

Status codes

  • 200OK. The best match, or a fallback message when no article matches.
  • 400Bad request. The question is too short or too long, or the body is not JSON (invalid body).
  • 401Unauthorized. The API key is unknown, revoked or expired (invalid or expired API key), or there is no key and no signed-in session (unauthorized).
  • 402Payment required. Only when subscriptions are enforced and the workspace has no active subscription. The body includes code: "payment_required".
  • 403Forbidden. The API key has the read scope, which only allows GET requests (API key is read-only). A key in another workspace gets API key belongs to a different workspace.

How is the best article chosen?

  • The question is split into keywords: words of 3 or more letters (numbers of any length), case-insensitive, with common stop-words such as “the” or “how” ignored.
  • Simple English endings are removed before comparing, so “shipping” matches “ship” and “refunds” matches “refund”. Words are matched whole: “pay” does not match “payment”.
  • Each keyword found in an article scores 2 points, plus 1 more when it is in the title.
  • An article must contain at least one keyword (for questions with more than 3 keywords, at least a third of them). The highest score wins; on a tie the newer article is kept.
  • When no article qualifies, answer is the fallback message and source is empty.

The same endpoint is also available at POST /api/v1/assistant with an identical request and response.