Help center

Knowledge Base

Overview

The Knowledge Base API lets you manage your help center's content programmatically - assemble categories, publish entries, and change portal settings. A typical scenario: an AI agent creates a document, shares it, and publishes it to the base right away.

ℹ️ Info: Knowledge Base is a Business plan feature. The API is available on Pro and Business - on Pro, calls to Knowledge Base endpoints return a PLAN_LIMIT_REACHED error.

Creating and deleting a base itself happens in the dashboard - the API manages the settings and content of existing bases.

Scopes

ScopeGrants
kb:readRead bases, categories, and entries
kb:writeChange base settings, manage categories and entries

Endpoints

MethodEndpointDescriptionScope
GET/kbList your baseskb:read
GET/kb/{id}Base with categories and entrieskb:read
PATCH/kb/{id}Update base settingskb:write
POST/kb/{id}/categoriesCreate a categorykb:write
PATCH/kb/{id}/categories/{categoryId}Update a categorykb:write
DELETE/kb/{id}/categories/{categoryId}Delete a categorykb:write
POST/kb/{id}/entriesAdd an entrykb:write
PATCH/kb/{id}/entries/{entryId}Update an entrykb:write
DELETE/kb/{id}/entries/{entryId}Delete an entrykb:write

Publishing a document to a base

An entry points to a share link, so the full workflow has three steps:

Step 1 - Create a document

POST /documents - see the documents API.

Step 2 - Create a share link

POST /shares with a document_id - see the shares API.

Step 3 - Add an entry to the base

bash
curl -X POST "https://my.clarife.app/api/v1/kb/{id}/entries" \
  -H "Authorization: Bearer clrf_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "share_id": "share-uuid",
    "title": "Getting started",
    "description": "Account setup step by step",
    "category_id": "category-uuid",
    "slug": "getting-started"
  }'

Entry fields: share_id (required), title (required, up to 200 characters), description (up to 1000 characters - feeds search results), category_id, slug (generated from the title when omitted), visibility (external/internal), sort_order.

Categories

bash
curl -X POST "https://my.clarife.app/api/v1/kb/{id}/categories" \
  -H "Authorization: Bearer clrf_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Getting started",
    "icon": "rocket",
    "color": "#6366F1",
    "sort_order": 0
  }'
  • Tree up to 3 levels - create a subcategory by passing parent_id.
  • icon is a Lucide icon name, color is a hex color.
  • Deleting a category removes its subcategories; entries stay (uncategorized).

Base settings

PATCH /kb/{id} accepts: name, slug, description, locale, branding_id, visibility (external/internal), allowed_emails, allowed_domains, is_active, is_indexable, home_entry_id (the home entry).

bash
curl -X PATCH "https://my.clarife.app/api/v1/kb/{id}" \
  -H "Authorization: Bearer clrf_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "is_active": true, "home_entry_id": "entry-uuid" }'

Limits and errors

CodeMeaning
409 + PLAN_LIMIT_REACHEDCategory (20) or entry (200) limit reached
409 + CONFLICTSlug taken in this base, or the share is already attached
403 + PLAN_LIMIT_REACHEDAccount without the Business plan
404 + NOT_FOUNDBase, category, or entry doesn't exist (or no access)

MCP tools

All operations are also available as MCP server tools: list_knowledge_bases, get_knowledge_base, update_knowledge_base, create_kb_category, update_kb_category, delete_kb_category, create_kb_entry, update_kb_entry, delete_kb_entry.

💡 Tip: AI agents can read the clarife://guides/knowledge-base MCP resource - it describes the full publishing workflow (document → share → entry), categories, and limits.

Workspace context

With the X-Workspace-Id header, a workspace member with the Manage Knowledge Base permission operates on the workspace owner's bases - the same as in the dashboard.