Baza Wiedzy

Przegląd

API Bazy Wiedzy pozwala programowo zarządzać treścią firmowego centrum pomocy - składać kategorie, publikować wpisy i zmieniać ustawienia portalu. Typowy scenariusz: agent AI tworzy dokument, udostępnia go i od razu publikuje w bazie.

ℹ️ Informacja: Baza Wiedzy to funkcja planu Business. API jest dostępne na planach Pro i Business - na planie Pro wywołania endpointów Bazy Wiedzy zwracają błąd PLAN_LIMIT_REACHED.

Samo utworzenie i usunięcie bazy odbywa się w dashboardzie - API zarządza ustawieniami i treścią istniejących baz.

Scopy

Scope	Uprawnia do
kb:read	Odczyt baz, kategorii i wpisów
kb:write	Zmiana ustawień bazy, zarządzanie kategoriami i wpisami

Endpointy

Metoda	Endpoint	Opis	Scope
GET	/kb	Lista Twoich baz	kb:read
GET	/kb/{id}	Baza z kategoriami i wpisami	kb:read
PATCH	/kb/{id}	Zmiana ustawień bazy	kb:write
POST	/kb/{id}/categories	Utworzenie kategorii	kb:write
PATCH	/kb/{id}/categories/{categoryId}	Edycja kategorii	kb:write
DELETE	/kb/{id}/categories/{categoryId}	Usunięcie kategorii	kb:write
POST	/kb/{id}/entries	Dodanie wpisu	kb:write
PATCH	/kb/{id}/entries/{entryId}	Edycja wpisu	kb:write
DELETE	/kb/{id}/entries/{entryId}	Usunięcie wpisu	kb:write

Publikacja dokumentu do bazy

Wpis wskazuje na link udostępniania, więc pełny workflow ma trzy kroki:

Krok 1 - Utwórz dokument

POST /documents - zobacz API dokumentów.

Krok 2 - Utwórz link udostępniania

POST /shares z document_id - zobacz API udostępnień.

Krok 3 - Dodaj wpis do bazy

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": "uuid-linku",
    "title": "Jak zacząć",
    "description": "Konfiguracja konta krok po kroku",
    "category_id": "uuid-kategorii",
    "slug": "jak-zaczac"
  }'

Pola wpisu: share_id (wymagane), title (wymagane, do 200 znaków), description (do 1000 znaków - trafia do wyników wyszukiwania), category_id, slug (generowany z tytułu, gdy pominiesz), visibility (external/internal), sort_order.

Kategorie

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": "Pierwsze kroki",
    "icon": "rocket",
    "color": "#6366F1",
    "sort_order": 0
  }'

Drzewo do 3 poziomów - podkategorię tworzysz podając parent_id.
icon to nazwa ikony z zestawu Lucide, color to kolor hex.
Usunięcie kategorii kasuje jej podkategorie; wpisy zostają (bez kategorii).

Ustawienia bazy

PATCH /kb/{id} przyjmuje: name, slug, description, locale, branding_id, visibility (external/internal), allowed_emails, allowed_domains, is_active, is_indexable, home_entry_id (wpis startowy).

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": "uuid-wpisu" }'

Limity i błędy

Kod	Znaczenie
409 + PLAN_LIMIT_REACHED	Limit kategorii (20) lub wpisów (200) osiągnięty
409 + CONFLICT	Slug zajęty w tej bazie albo link już podpięty
403 + PLAN_LIMIT_REACHED	Konto bez planu Business
404 + NOT_FOUND	Baza, kategoria lub wpis nie istnieje (lub brak dostępu)

Narzędzia MCP

Wszystkie operacje są też dostępne jako narzędzia serwera MCP: 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.

💡 Wskazówka: Agenty AI mogą odczytać zasób MCP clarife://guides/knowledge-base - opisuje pełny workflow publikacji (dokument → link → wpis), kategorie i limity.

Kontekst workspace

Z nagłówkiem X-Workspace-Id członek workspace z uprawnieniem Zarządzanie Bazą Wiedzy operuje na bazach właściciela workspace - tak samo jak w dashboardzie.