API Dokumentów

Dokumenty to główny zasób w clarife. Każdy dokument zawiera bloki (tekst, nagłówki, zrzuty ekranu, kod, tabele).

Wymagane scopy: documents:read, documents:write

Lista dokumentów

bash

curl -s "https://my.clarife.app/api/v1/documents?limit=10&offset=0&sort=updated_at&order=desc" \
  -H "Authorization: Bearer clrf_xxxxx" | jq

Parametry query:

Parametr	Typ	Domyślnie	Opis
limit	integer	50	Wyniki na stronę (1-100)
offset	integer	0	Przesunięcie paginacji
sort	string	updated_at	Pole sortowania: updated_at, created_at, title
order	string	desc	Kolejność: asc lub desc
project_id	uuid	--	Filtruj po projekcie

Odpowiedź 200 OK:

json

{
  "data": [
    {
      "id": "d1234567-...",
      "title": "Mój tutorial",
      "description": "Jak skonfigurować...",
      "updated_at": "2026-03-28T12:00:00Z",
      "created_at": "2026-03-20T10:00:00Z",
      "block_count": 12,
      "screenshot_count": 5,
      "word_count": 450,
      "visibility": "private"
    }
  ],
  "total": 42,
  "limit": 10,
  "offset": 0
}

Pobierz dokument

bash

curl -s https://my.clarife.app/api/v1/documents/DOCUMENT_ID \
  -H "Authorization: Bearer clrf_xxxxx" | jq

Zwraca pełną treść dokumentu z blokami (content).

Odpowiedź 200 OK:

json

{
  "data": {
    "id": "d1234567-...",
    "title": "Mój tutorial",
    "description": "Jak skonfigurować...",
    "content": {
      "meta": { "version": 1, "locale": "pl" },
      "blocks": [
        { "type": "heading", "id": "h1-tytul", "sort_order": 0, "level": 1, "content": "Krok 1" },
        { "type": "text", "id": "t1-opis", "sort_order": 1, "content": "Otwórz ustawienia..." },
        { "type": "screenshot", "id": "ss1-ekran", "sort_order": 2, "media_id": "m1234...", "caption": "Ekran ustawień", "alignment": "center" }
      ]
    },
    "version": 4,
    "block_count": 3,
    "screenshot_count": 1,
    "word_count": 12,
    "visibility": "private",
    "template": null,
    "branding_id": null
  }
}

Pole version to numer wersji dokumentu rosnący przy każdej zmianie treści - użyj go jako expected_version przy aktualizacji (patrz niżej).

Utwórz dokument

bash

curl -s -X POST https://my.clarife.app/api/v1/documents \
  -H "Authorization: Bearer clrf_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Nowy tutorial",
    "description": "Instrukcja konfiguracji",
    "project_id": "p1234567-...",
    "visibility": "private"
  }' | jq

Parametry body:

Pole	Typ	Wymagane	Opis
title	string	nie	Tytuł (max 500 znaków, domyślnie "Untitled")
description	string	nie	Opis (max 2000 znaków)
content	object	nie	Obiekt z meta i blocks (patrz Format treści poniżej)
project_id	uuid	nie	Przypisz do projektu
template	string	nie	Identyfikator szablonu
visibility	string	nie	private lub workspace (wymaga X-Workspace-Id)

Odpowiedź 201 Created:

json

{
  "data": {
    "id": "d1234567-...",
    "title": "Nowy tutorial",
    "created_at": "2026-03-28T12:00:00Z"
  }
}

Zaktualizuj dokument

bash

curl -s -X PATCH https://my.clarife.app/api/v1/documents/DOCUMENT_ID \
  -H "Authorization: Bearer clrf_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Zmieniony tytuł",
    "description": "Zaktualizowany opis"
  }' | jq

Parametry body:

Pole	Typ	Opis
title	string	Nowy tytuł (max 500 znaków)
description	string	Nowy opis (max 2000 znaków)
content	object	Nowa treść z blokami
expected_version	integer	Opcjonalna blokada współbieżności - wartość version z GET /documents/:id (niezgodność = 409 CONFLICT)

⚠️ Uwaga: Przy aktualizacji content musisz wysłać pełną treść - tablica blocks zastępuje istniejącą, a pola block_annotations i block_enhance_settings (jeśli dokument je ma) trzeba odesłać razem z nią, inaczej zostaną trwale usunięte. Najpierw pobierz obecną treść przez GET /documents/:id, zmodyfikuj ją i wyślij całość.

Blokada współbieżności (opcjonalna): w polu expected_version prześlij wartość version z odpowiedzi GET /documents/:id. Zapis wykona się tylko wtedy, gdy dokument nie zmienił się w międzyczasie - w przeciwnym razie API zwróci 409 z kodem CONFLICT i aktualnym numerem wersji w komunikacie. Po konflikcie pobierz dokument ponownie, nanieś swoje zmiany na świeżą treść i ponów zapis. Zalecamy wysyłanie expected_version przy każdej aktualizacji content - chroni to przed nadpisaniem zmian zapisanych równolegle w edytorze, w innej integracji lub przez agenta MCP.

Odpowiedź 200 OK:

json

{
  "data": {
    "id": "d1234567-...",
    "title": "Zmieniony tytuł",
    "version": 5,
    "updated_at": "2026-03-28T13:00:00Z"
  }
}

Usuń dokument

Usuwanie jest miękkie (soft delete) - dokument trafia do kosza na 30 dni.

bash

curl -s -X DELETE https://my.clarife.app/api/v1/documents/DOCUMENT_ID \
  -H "Authorization: Bearer clrf_xxxxx"

Odpowiedź 204 No Content: Puste body.

Format treści

Treść dokumentu opiera się na płaskiej strukturze blokowej. Każdy blok musi zawierać te wspólne pola:

Pole	Typ	Wymagane	Opis
type	string	tak	Typ bloku (patrz typy poniżej)
id	string	tak	Unikalny ID w dokumencie (np. "h1-tytul", "ss3-wynik")
sort_order	integer	tak	Kolejność wyświetlania od 0

heading

json

{
  "type": "heading",
  "id": "h1-tytul",
  "sort_order": 0,
  "level": 1,
  "content": "Tytuł tutoriala"
}

level: 1, 2 lub 3 (H1, H2, H3)
content: tekst

text

json

{
  "type": "text",
  "id": "t1-wstep",
  "sort_order": 1,
  "content": "Tekst akapitu.\nUżyj nowych linii dla list:\n• Punkt pierwszy\n• Punkt drugi"
}

content: tekst lub podstawowy HTML (<b>, <i>, <a>, <br>)

screenshot / image

json

{
  "type": "screenshot",
  "id": "ss1-ekran",
  "sort_order": 2,
  "media_id": "77b4185f-bb13-47ea-97a4-6b0d88289df1",
  "caption": "Widok dashboardu",
  "alignment": "center"
}

media_id (UUID, wymagane): odniesienie do przesłanego pliku - patrz Upload mediów dla workflow uploadu
caption (string, opcjonalne): podpis pod obrazem
alignment: "left", "center" lub "right"
width (integer, opcjonalne): szerokość wyświetlania w pikselach

Typ "image" ma identyczną strukturę jak screenshot - użyj go dla diagramów i ilustracji.

divider

json

{ "type": "divider", "id": "d1", "sort_order": 5 }

Brak dodatkowych pól.

code

json

{
  "type": "code",
  "id": "c1-przyklad",
  "sort_order": 6,
  "code": "npm install clarife",
  "language": "bash"
}

code (wymagane): kod źródłowy
language: podświetlanie składni (np. "python", "javascript", "bash", "sql")

table

json

{
  "type": "table",
  "id": "tbl1",
  "sort_order": 7,
  "has_header": true,
  "columns": [
    { "label": "Imię" },
    { "label": "Rola" }
  ],
  "rows": [
    ["Alicja", "Developer"],
    ["Bob", "Designer"]
  ]
}

has_header (boolean, wymagane): czy etykiety kolumn renderują się jako wiersz nagłówka
columns (wymagane): jeden wpis na kolumnę; label to tekst nagłówka, opcjonalnie width (px) i align ("left" | "center" | "right")
rows: tablica 2D stringów - tylko dane, nagłówki są w columns

Adnotacje i ustawienia zrzutów

Poza meta i blocks treść może zawierać dwa opcjonalne obiekty tworzone w edytorze clarife:

block_annotations: warstwy adnotacji (strzałki, ramki, rozmycia itd.) przypisane do bloków zrzutów po ich id
block_enhance_settings: ustawienia ramki i tła zrzutów, również po id bloku

Zwykle nie tworzysz ich ręcznie - pobierasz je w odpowiedzi GET /documents/:id i odsyłasz bez zmian przy aktualizacji. Oba pola są walidowane; nieprawidłowa struktura zwraca 400 VALIDATION_ERROR.

⚠️ Uwaga: aktualizacja content zastępuje całą treść. Jeśli pominiesz block_annotations lub block_enhance_settings, adnotacje i ustawienia zrzutów zostaną trwale usunięte.

Kompletny przykład

bash

curl -X POST https://my.clarife.app/api/v1/documents \
  -H "Authorization: Bearer clrf_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Poradnik konfiguracji",
    "content": {
      "meta": { "version": 1, "locale": "pl" },
      "blocks": [
        { "type": "heading", "id": "h1", "sort_order": 0, "level": 1, "content": "Poradnik konfiguracji" },
        { "type": "text", "id": "t1", "sort_order": 1, "content": "Wykonaj poniższe kroki." },
        { "type": "screenshot", "id": "ss1", "sort_order": 2, "media_id": "77b4185f-...", "caption": "Ekran ustawień", "alignment": "center" },
        { "type": "divider", "id": "d1", "sort_order": 3 },
        { "type": "text", "id": "t2", "sort_order": 4, "content": "Gotowe!" }
      ]
    }
  }'

ℹ️ Informacja: Aby dodać obrazy, musisz je najpierw przesłać przez Upload mediów. Workflow: uzyskaj presigned URL → prześlij plik → potwierdź upload → dodaj blok screenshot z media_id do dokumentu.

Kody błędów

Kod	Opis
NOT_FOUND	Dokument nie istnieje lub brak dostępu
VALIDATION_ERROR	Nieprawidłowe dane wejściowe
CONFLICT	Dokument został w międzyczasie zmieniony - expected_version niezgodne z aktualną wersją
PLAN_LIMIT_REACHED	Osiągnięto limit dokumentów na planie
FORBIDDEN	Brak uprawnień w workspace