[Intum Pomoc](https://intum.pl/pomoc.md) / [API](https://intum.pl/pomoc/baza-wiedzy/api.md)

# [Bazy wiedzy](https://intum.pl/pomoc/baza-wiedzy/api/bazy-wiedzy.md)

Tworzenie, aktualizacja, usuwanie i pobieranie baz wiedzy przez API.

**Autoryzacja:** `Authorization: Bearer TOKEN` — token musi mieć uprawnienie **kb**
**Content-Type:** `application/json`

## API Endpoints

| Metoda | Ścieżka | Opis |
|--------|---------|------|
| GET | `/kb/knowledge_bases.json` | Lista baz wiedzy |
| GET | `/kb/knowledge_bases/:id.json` | Pojedyncza baza wiedzy |
| POST | `/kb/knowledge_bases.json` | Utworzenie bazy wiedzy |
| PATCH | `/kb/knowledge_bases/:id.json` | Aktualizacja bazy wiedzy |
| DELETE | `/kb/knowledge_bases/:id.json` | Usunięcie bazy wiedzy |

## Pola knowledge_base

| Pole | Typ | Wymagane | Opis |
|------|-----|----------|------|
| `title` | string | tak | Nazwa bazy wiedzy |
| `description` | string | nie | Opis bazy wiedzy |
| `url` | string | nie | URL bazy wiedzy (np. `https://pomoc.firma.pl`) |
| `kind` | string | nie | Typ: `knowledge_base` (domyślnie) |
| `lang` | string | nie | Język: `pl`, `en`, `fr`, `cs`, `sk`, `de`, `es`, `uk`. Formatka nowej bazy podpowiada język konta; bez `lang` w API baza dostaje `pl` |
| `read_access` | string | nie | Kto widzi zawartość: `public` (wszyscy, domyślnie), `logged_in` (każdy zalogowany, także gość), `users` (użytkownicy nie-goście z uprawnieniem `kb_show_priv`), `admins` (osoby z dostępem do ustawień konta) |
| `department_id` | integer | nie | Zawęża `users`/`admins` do jednego działu (brak = wszystkie działy). Na poziomach `public`/`logged_in` jest czyszczone |
| `private` | boolean | nie | Przestarzałe, trzymane dla zgodności: `true` = `read_access: users`, `false` = `read_access: public`. Ustawiaj `read_access` |
| `template` | string | nie | Szablon widoku: `docs` (domyślny dla nowej bazy), `protocol_basic`, `default`, `marsian`, `marsian_old`, `syntax`. Forum zawsze dostaje `default` |
| `prefix` | string | nie | Prefix URL w ścieżce publicznej (np. `pomoc`) |
| `domain_id` | integer | nie | ID domeny własnej |
| `category_in_url` | boolean | nie | Czy URL kategorii jest częścią URL wpisu |
| `redirect_to_main_domain` | boolean | nie | Przekierowanie na główną domenę |
| `use_url_token` | boolean | nie | Wymagaj tokenu w URL do dostępu |
| `comments_auto_approve` | string | nie | Minimalna rola autora, aby jego komentarz został automatycznie zaakceptowany (wartość obejmuje wymienioną rolę i wszystkie wyższe): `yes` (każdy), `guest` (gość i wyżej), `old_guest` (gość >7 dni i wyżej), `approved_guest` (zatwierdzony gość i wyżej), `user` (użytkownik i wyżej), `operator` (operator i wyżej), `admin` (tylko admin), `no` (nikt) |
| `multilang_code` | string | nie | Kod grupy tłumaczeń (łączenie baz w różnych językach) |
| `external_id` | string | nie | Identyfikator bazy w systemie zewnętrznym (import, synchronizacja). Unikalny w obrębie konta; pusty = brak |
| `content_api` | string | nie | Opis API bazy wiedzy w Markdown — wyświetlany w dokumentacji |
| `app_link_host` | string | nie | Adres systemu doklejany do linków `app:/ścieżka` we wpisach (np. `https://app.intum.pl`). Normalizowany do samego schematu i hosta (`app.intum.pl/` → `https://app.intum.pl`). Puste = link `app:/x` renderuje się jako sama ścieżka `/x` |
| `fields` | object | nie | Dodatkowe pola (np. `{"html_head": "<script>..."}`) |

## Format requestu

### POST — Utworzenie bazy wiedzy

```json
{
  "knowledge_base": {
    "title": "Centrum pomocy",
    "lang": "pl",
    "template": "protocol_basic",
    "prefix": "pomoc",
    "category_in_url": true
  }
}
```

### PATCH — Aktualizacja bazy wiedzy

```json
{
  "knowledge_base": {
    "title": "Nowa nazwa",
    "content_api": "## API\n\nOpis endpointów..."
  }
}
```

## Format odpowiedzi

### Sukces — POST (201 Created)

```json
{
  "id": 1176,
  "title": "Centrum pomocy",
  "kind": "knowledge_base",
  "lang": "pl",
  "template": "protocol_basic",
  "prefix": "pomoc",
  "read_access": "public",
  "department_id": null,
  "private": false,
  "category_in_url": true,
  "content_api": null,
  "entries_count": 0,
  "created_at": "2026-03-05T08:48:43.186+01:00"
}
```

### Sukces — GET lista (200 OK)

```json
[
  {
    "id": 1176,
    "title": "Centrum pomocy",
    "prefix": "pomoc",
    "entries_count": 7,
    "template": "protocol_basic",
    "content_api": "## API\n\nOpis..."
  }
]
```

### Błąd walidacji (422 Unprocessable Content)

```json
{
  "title": ["nie może być puste"]
}
```

## Szablony

| Szablon | Opis |
|---------|------|
| `protocol_basic` | Nowoczesny szablon z paskiem bocznym, wyszukiwarką i przyciskiem AI |
| `default` | Podstawowy szablon |
| `marsian` | Szablon z pełną szerokością |
| `marsian_old` | Starsza wersja szablonu marsian |
| `syntax` | Szablon z podświetlaniem składni |
| `docs` | Układ dokumentacji jak pomoc w aplikacji: drzewo kategorii i podkategorii po lewej, treść, spis „Na tej stronie” po prawej, poprzedni/następny. Wpis o adresie kategorii (np. `index.md` z publikacji pomocy) jest treścią strony kategorii. W nagłówku linki Kategorie (`/c`) i Wszystkie wpisy (`/all`); lista `/all` z datą aktualizacji przy wpisie, domyślnie od ostatnio zaktualizowanych, `?sort=newest` - ostatnio dodane, `?sort=views` - popularne. Zalecany dla baz publikowanych z pomocy w aplikacji. Wpisy bez kategorii na stronie głównej i na górze menu; bez kategorii nie ma linku Kategorie. Wygląd zmienia `fields.skin` |

## Wskazówki

- **`content_api`** — pole Markdown opisujące API bazy wiedzy. Wyświetlane w widoku bazy jako dokumentacja techniczna. Ustaw ogólny opis endpointów, autoryzacji i przykładów
- **`prefix`** — definiuje ścieżkę publiczną bazy (np. prefix `pomoc` → `/pomoc/artykul`)
- **`fields.skin`** — skórka szablonu `docs` (tylko przy `template: "docs"`): `default` (klasyczna, domyślna), `aurora`, `editorial`, `terminal`, `cyberpunk`. Nieznana wartość i `default` zapisują się jako brak skórki. W `PATCH` wysyłaj jako `knowledge_base[skin]`
- **`fields.api_switch`** — `"1"` włącza przełącznik API w menu przycisku AI na każdej stronie bazy (dokumentacja ↔ widok `.api`), nie tylko na stronach z `content_api`. `knowledge_base[api_switch]`
- **`fields.product_url`** — strona www produktu ("Strona produktowa"): link w sidebarze bazy i linia `Strona produktowa: [adres](url)` pod opisem w wersji markdown bazy (`/kb/<prefix>.md`, która zaczyna się od tytułu i `description`). `knowledge_base[product_url]`
- **`category_in_url`** — gdy `true`, URL wpisu zawiera prefix kategorii (np. `/pomoc/organizacja/uzytkownik`)
- **`template`** — szablon wizualny. Bez `template` nowa baza wiedzy dostaje `docs` (zalecany: drzewo kategorii, spis treści, przycisk AI, skórki). `protocol_basic` - wcześniejszy domyślny, z paskiem bocznym i wyszukiwarką
- Po utworzeniu bazy wiedzy, dodawaj wpisy przez [kb_entry_api](https://intum.intum.pl/kb/intum-kb/baza-wiedzy/api/wpisy)

## Powiązane

- [common_api](https://app.intum.pl/noe/prompt/common_api.md) — wspólne zasady API (format, autoryzacja, odpowiedzi)