API v1 · preview

Build on Knowledgebase.org

Your customers keep their knowledge here, and your app reads what they approved and granted, with a source behind every answer.

Quickstart

Create a knowledgebase, add a few items and publish a release.
Open API keys in your workspace and create a key scoped to that base.
Call the API from your server. Never put keys in browser code.

curl -X POST https://knowledgebase.org/v1/answers \
  -H "Authorization: Bearer $KB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"knowledge_base": "your-base-slug", "question": "What are your opening hours?"}'

// Node / TypeScript
const res = await fetch("https://knowledgebase.org/v1/answers", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.KB_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ question: "Do you offer refunds?" }), // omit knowledge_base to search every base in the key's scope
});
const { answer, citations } = await res.json();

Endpoints

POST/v1/answersAnswer a question from approved, released knowledge, with numbered citations. Uses AI when enabled, otherwise returns the best passages.

POST/v1/searchRanked passages from the bases you may read. Each result names its release and revision.

GET/v1/knowledge-basesBases your key is scoped to.

GET/v1/knowledge-bases/{slug}The current release of one base as JSON, a snapshot for sync or export.

GET/v1/directory?q=&type=&location=&language=&topic=Public, listed profiles with filters and the reasons each matched. No key needed, no AI.

POST/v1/network/searchPassages across the public network, at most 3 per source. Add collection to search one of your collections instead.

POST/v1/network/answers"What do these sources say?": an answer that attributes each claim, lists disagreements between sources, and flags missing evidence.

GET/v1/collectionsYour workspace's collections. Members are read with your own rights: your bases in full, others only through their public items.

Apps that connect to other people's knowledgebases

Building a product others use? Register an app under Developer apps, then let each customer connect their own knowledgebase through a permission screen (OAuth 2 authorization code with PKCE). You never handle their password, and they can disconnect you at any time.

GET/oauth/authorizeSend the owner here with response_type=code, client_id, redirect_uri, scope, state and a PKCE S256 code_challenge. They choose knowledgebases, permissions and duration.

POST/oauth/tokenExchange the code (with code_verifier) or a refresh token. Client authentication is required: HTTP Basic with client_id and client_secret.

POST/oauth/revokeRevoke your own access or refresh token (RFC 7009).

GET/v1/changes?cursor=Updates for the knowledgebases you may read (needs changes:read). Identifiers only; resume from next_cursor.

• Permissions: kb:read, kb:search, kb:answer, changes:read. Owners can untick any of them, and can only ever narrow what you asked for.
• Access tokens last one hour; refresh tokens rotate on every use, and replaying an old one ends the whole chain.
• Every request re-checks the owner's current grant, so a disconnect blocks your very next call (401). A missing permission returns 403 insufficient_scope.
• Connected apps read all approved items in the granted knowledgebases, not just public ones, and never drafts.
• A runnable example app lives in the repository at examples/connect-demo.

Access rules

• Only approved items in the latest release are ever returned. Drafts and items still needing review are never visible.
• A key reads only the bases in its scope. Public bases can be read by slug without a key.
• Revoking a key blocks its next request immediately.
• Every response has an x-request-id, and errors return { error: { code, message, request_id } }.
• Owners see every API read in their workspace activity log.

Chat widget

For public knowledgebases, paste one line before </body>:

<script src="https://knowledgebase.org/widget.js" data-kb="your-base-slug" async></script>

On the roadmap

Workspace and base creation via APIEmbedded maker componentsSigned webhooksVersion pinningMCP server for AI agentsTypeScript and Python SDKsPortable package export