Niniejszy dokument jest automatycznym tłumaczeniem oryginału w języku angielskim. W przypadku jakichkolwiek rozbieżności między tym tłumaczeniem a oryginalną wersją angielską, wersja angielska jest rozstrzygająca. Przeczytaj oryginał w języku angielskim

Publiczne API

Caiioo zawiera API REST, które pozwala programowo kontrolować wszystko: uruchamiać agentów, zarządzać narzędziami, planować zadania i nie tylko. API działa na tym samym lokalnym serwerze, który zasila aplikację desktopową i mostek przeglądarki.

Podstawowy URL: http://localhost:3847/v1

Uwierzytelnianie: Dwa sposoby uwierzytelniania, oba kontrolowane przez przełącznik API w ustawieniach:

Dla zewnętrznych konsumentów (skrypty, integracje, curl): Ustaw token dostępu API w Ustawienia > Dostęp API, a następnie użyj go jako tokena Bearer:

curl -H "Authorization: Bearer TWÓJ_TOKEN_API" http://localhost:3847/v1/providers

Dla aplikacji lokalnej (automatycznie): Aplikacja desktopowa Caiioo, rozszerzenia przeglądarki i aplikacje mobilne uwierzytelniają się automatycznie za pomocą istniejącego nagłówka autoryzacji przekaźnika (X-Relay-Auth). Nie jest wymagana ręczna konfiguracja — aplikacja zajmuje się tym za kulisami.

Konfiguracja:

Otwórz Caiioo Ustawienia > Dostęp API
Włącz opcję Włącz publiczne API
Ustaw token dostępu API (dowolny wybrany ciąg znaków — traktuj go jak hasło)
Używaj tego tokena we wszystkich żądaniach API

API jest dostępne na localhost oraz przez prywatny przekaźnik. Sprawdź GET /v1/auth/info (nie wymaga autoryzacji), aby poznać aktualny status i instrukcje konfiguracji.

Dostawcy i modele

Dowiedz się, którzy dostawcy LLM są skonfigurowani i jakie modele są dostępne.

Lista dostawców:

GET /v1/providers

Zwraca wszystkie skonfigurowane typy dostawców (Anthropic, OpenAI, Google, OpenRouter, Ollama, Poe, MLX, Baseten i inne w miarę ich dodawania) wraz z flagami możliwości (supportsVision, supportsToolCalling, supportsStreaming itp.) oraz informacją, czy klucz API jest skonfigurowany.

Lista modeli dla dostawcy:

GET /v1/providers/anthropic/models

Zwraca katalog modeli dla danego dostawcy. Każdy model zawiera id, displayName oraz contextLength, jeśli są dostępne.

Zbiorczy katalog wszystkich dostawców:

GET /v1/models

Łączy modele od każdego skonfigurowanego dostawcy w jedną listę. Dostawcy bez kluczy API są pomijani i wymieniani w sekcji warnings.

Agenci

Agenci stanowią serce caiioo. Każdy agent to Tryb — skonfigurowana osobowość z własnym promptem systemowym, narzędziami, zmiennymi i umiejętnościami.

Lista wszystkich agentów:

GET /v1/agents

Zwraca wbudowanych agentów (Shopping, Workplace, General) oraz wszystkich utworzonych przez Ciebie agentów niestandardowych. Każdy jest oznaczony jako source: \"builtin\" lub source: \"custom\".

Utwórz niestandardowego agenta:

POST /v1/agents
Content-Type: application/json

{
  \"id\": \"my-research-agent\",
  \"branding\": {
    \"name\": \"Research Agent\",
    \"description\": \"Przeszukuje sieć i podsumowuje znaleziska\"
  },
  \"defaultSettings\": {
    \"systemPrompt\": \"Jesteś asystentem badawczym. Zawsze podawaj źródła.\",
    \"enabledTools\": { \"web_browsing\": true, \"search_tools\": true }
  },
  \"settingLevels\": {}
}

Zwraca 201 z utworzonym agentem. Zegar wektorowy jest dołączany automatycznie na potrzeby synchronizacji.

Zaktualizuj agenta:

PATCH /v1/agents/my-research-agent
Content-Type: application/json

{ \"branding\": { \"name\": \"Research Agent\", \"description\": \"Zaktualizowany opis\" } }

Łączy poprawkę z istniejącym agentem i aktualizuje zegar wektorowy. Wbudowani agenci zwracają 403 — są tylko do odczytu.

Usuń agenta:

DELETE /v1/agents/my-research-agent

Usuwanie miękkie przez „tombstone” (synchronizuje się między urządzeniami). Zwraca 204.

Uruchamianie agentów

To jest główne zadanie — wywołanie agenta w celu przetworzenia wiadomości.

Tryb synchroniczny

Oczekiwanie na pełną odpowiedź:

POST /v1/runs
Content-Type: application/json

{
  "agentId": "general",
  "input": { "message": "Jaka jest dzisiaj pogoda w Paryżu?" },
  "mode": "sync"
}

Zwraca 200 z { content, usage, status: "completed" } po zakończeniu pracy agenta. Jeśli wystąpi błąd agenta, zwraca 500 z { error, status: "error" }.

Tryb asynchroniczny

Uruchom i zapomnij — przydatne przy długotrwałych zadaniach:

POST /v1/runs
Content-Type: application/json

{
  "agentId": "my-research-agent",
  "input": { "message": "Napisz analizę trendów w energii odnawialnej na 2000 słów" },
  "mode": "async"
}

Natychmiast zwraca 202 z { runId, threadId, status: "running" }.

Sprawdzanie statusu:

GET /v1/runs/{runId}

Zwraca { run: { runId, threadId, agentId, status, createdAt, content?, usage?, error? } }. Status to jeden z: running, completed, error lub cancelled.

Strumieniowanie zdarzeń w czasie rzeczywistym (SSE):

GET /v1/runs/{runId}/events

Zwraca text/event-stream z każdym zdarzeniem agenta na bieżąco: GENERATION_STARTED, STREAMING_CONTENT, wywołania narzędzi, aktywność podagentów oraz zdarzenie końcowe (GENERATION_COMPLETE, GENERATION_ERROR lub GENERATION_CANCELLED). Strumień kończy się po zdarzeniu końcowym.

Anulowanie przebiegu:

POST /v1/runs/{runId}/cancel

Zwraca { run: { ..., status: "cancelled" } }.

Threads

Threads to konwersacje. Każde uruchomienie agenta odbywa się w ramach wątku, a wątki są zachowywane między sesjami. API pozwala na programowe listowanie, odczytywanie, tworzenie i zarządzanie wątkami.

Lista wszystkich wątków (tylko metadane):

GET /v1/threads

Zwraca wątki dla bieżącego profilu z usuniętymi wiadomościami w celu zwiększenia wydajności. Każdy wątek zawiera id, title, createdAt, updatedAt, modeId, archived oraz statystyki użycia.

Pobieranie wątku z pełną treścią wiadomości:

GET /v1/threads/{id}

Zwraca kompletny wątek wraz z tablicą messages — każdą wiadomość użytkownika, odpowiedź asystenta, wywołanie narzędzia i wynik działania narzędzia.

Pobieranie samych wiadomości:

GET /v1/threads/{id}/messages

Zwraca tylko tablicę messages — rozwiązanie lżejsze niż pełny obiekt wątku, gdy potrzebujesz jedynie treści konwersacji.

Tworzenie wątku:

POST /v1/threads
Content-Type: application/json

{ "title": "Research project", "modeId": "general" }

Zwraca 201 wraz z nowym wątkiem. Domyślnie API NIE przełącza aktywnego wątku w aplikacji — przekaż "setActive": true w body, jeśli chcesz to zmienić. Nowy wątek pojawi się natychmiast na pasku bocznym (poprzez transmisję WebSocket).

Aktualizacja wątku:

PATCH /v1/threads/{id}
Content-Type: application/json

{ "title": "Renamed project", "archived": true }

Pola podlegające aktualizacji: title, modeId, archived, lastUsedModel. Zmiany są transmitowane do paska bocznego w czasie rzeczywistym.

Usuwanie wątku:

DELETE /v1/threads/{id}

Wykonuje miękkie usunięcie wątku (znacznik tombstone dla synchronizacji). Zwraca 204. Usunięte wątki trafiają do kosza i mogą zostać odzyskane do momentu opróżnienia kosza.

Aktywny wątek:

GET /v1/threads/active            # Zwraca { threadId }
PUT /v1/threads/active            # Body: { "threadId": "..." }

Zarządzanie koszem:

GET /v1/threads/trash/count       # Zwraca { count }
POST /v1/threads/trash/empty      # Zwraca { deletedCount, protectedCount }

Wątki chronione (zachowane poprzez przełącznik retencji danych) są wyłączone z procesu opróżniania kosza.

Kontynuowanie konwersacji przez API: Aby wysłać kolejną wiadomość w istniejącym wątku, użyj POST /v1/runs z identyfikatorem wątku:

POST /v1/runs
Content-Type: application/json

{
  "agentId": "general",
  "threadId": "existing-thread-id",
  "input": { "message": "Follow up on that last point" },
  "mode": "sync"
}

Agent widzi pełną historię konwersacji z danego wątku.

Załączniki

Załączniki to pliki powiązane z wątkami — zrzuty ekranu, pliki PDF, dokumenty, przesłane obrazy, wygenerowane artefakty. API pozwala na ich listowanie, przesyłanie, pobieranie i zarządzanie nimi.

Lista wszystkich załączników (tylko metadane):

GET /v1/attachments

Zwraca metadane załączników dla bieżącego profilu. Ciężkie pola (dataUrl, extractedContent, extractedImages) są usuwane — użyj punktów końcowych szczegółów lub treści, aby je uzyskać.

Lista załączników dla konkretnego wątku:

GET /v1/threads/{threadId}/attachments

Pobierz metadane załącznika:

GET /v1/attachments/{id}

Zwraca pełne metadane, w tym extractedContent (tekst OCR, przetworzony markdown), contentType, fileName, size oraz flagę hasContent. Surowe dane binarne NIE są dołączone — użyj punktu końcowego /content.

Pobierz plik binarny załącznika:

GET /v1/attachments/{id}/content

Zwraca surowy plik z poprawnymi nagłówkami Content-Type i Content-Disposition. Przekieruj to do pliku:

curl -o wyjscie.pdf \
  -H "Authorization: Bearer $API_TOKEN" \
  http://localhost:3847/v1/attachments/{id}/content

Prześlij załącznik:

POST /v1/attachments
Content-Type: application/json

{
  "threadId": "thread-id",
  "type": "user_upload",
  "contentType": "application/pdf",
  "fileName": "raport.pdf",
  "description": "Raport kwartalny",
  "dataUrl": "data:application/pdf;base64,JVBERi0xLjQ..."
}

dataUrl to adres URL danych zakodowany w base64. Zwraca 201 z nowym ID załącznika. Załącznik jest powiązany z określonym wątkiem.

Aktualizuj metadane załącznika:

PATCH /v1/attachments/{id}
Content-Type: application/json

{ "description": "Zaktualizowany opis", "fileName": "nowa-nazwa.pdf" }

Usuń załącznik:

DELETE /v1/attachments/{id}

Usuwanie miękkie przez znacznik tombstone. Zwraca 204.

Serwery MCP

Zarządzaj połączeniami z serwerami MCP (Model Context Protocol) — serwerami, które dają agentom dostęp do zewnętrznych narzędzi i źródeł danych.

Lista skonfigurowanych serwerów:

GET /v1/mcp-servers

Zwraca wszystkie konfiguracje serwerów MCP dla bieżącego profilu. Pola wrażliwe (authToken, env, credentialId) są usuwane z odpowiedzi.

Pobierz konfigurację serwera:

GET /v1/mcp-servers/{id}

Dodaj nowy serwer MCP:

POST /v1/mcp-servers
Content-Type: application/json

{
  "id": "my-server",
  "name": "My MCP Server",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/files"],
  "serverType": "local"
}

Dla zdalnych serwerów HTTP użyj "url" zamiast "command":

{
  "id": "remote-server",
  "name": "Remote API",
  "url": "https://my-mcp-server.example.com/sse",
  "serverType": "remote"
}

Zaktualizuj serwer:

PATCH /v1/mcp-servers/{id}
Content-Type: application/json

{ "name": "Renamed Server", "args": ["-y", "@mcp/server-v2"] }

Włącz/wyłącz serwer:

POST /v1/mcp-servers/{id}/toggle
Content-Type: application/json

{ "enabled": false }

Usuń serwer:

DELETE /v1/mcp-servers/{id}

Zarządzanie procesami

W przypadku lokalnych serwerów MCP (stdio) możesz bezpośrednio zarządzać procesem serwera.

Lista uruchomionych procesów:

GET /v1/mcp-servers/processes

Zwraca uruchomione procesy serwerów wraz z pid, startedAt oraz statusem running.

Uruchom serwer:

POST /v1/mcp-servers/{id}/start

Odczytuje command/args/env z konfiguracji serwera i uruchamia proces. Zwraca status procesu.

Zatrzymaj serwer:

POST /v1/mcp-servers/{id}/stop

Bezpiecznie zamyka proces serwera (SIGTERM z opcją wymuszenia SIGKILL).

Wywołaj metodę JSON-RPC bezpośrednio:

POST /v1/mcp-servers/{id}/call
Content-Type: application/json

{ "method": "tools/list", "params": {} }

Wysyła surowe żądanie JSON-RPC 2.0 do serwera i zwraca wynik. Przydatne do debugowania lub wywoływania metod nieudostępnionych przez API narzędzi.

Narzędzia i Zestawy Narzędzi

Przeglądaj i wywołuj narzędzia, których używają agenci — przeglądanie sieci, wyszukiwanie, kalendarz, Gmail, Slate i inne.

Lista zestawów narzędzi (pogrupowana):

GET /v1/toolkits

Zwraca wbudowane narzędzia pogrupowane według kategorii (Produktywność, Wyszukiwanie, Narzędzia itp.) oraz wszelkie podłączone serwery MCP jako oddzielne zestawy narzędzi, każdy z listą dostępnych akcji.

Lista wszystkich narzędzi (płaska):

GET /v1/tools
GET /v1/tools?source=embedded   # Tylko wbudowane narzędzia
GET /v1/tools?source=mcp        # Tylko narzędzia serwera MCP

Pobierz szczegóły narzędzia ze schematem wejściowym:

GET /v1/tools/calculator

Zwraca schemat JSON Schema parametrów wejściowych narzędzia, dzięki czemu można je zweryfikować przed wywołaniem.

Bezpośrednie wywołanie narzędzia:

POST /v1/tools/calculator/invoke
Content-Type: application/json

{ "input": { "expression": "sqrt(144) + 3^2" } }

Zwraca { result }. Dane wejściowe są sprawdzane pod kątem schematu narzędzia — nieprawidłowe dane zwracają 422 ze szczegółami. Zdalne narzędzia MCP zwracają 501 z instrukcją użycia /v1/runs (wymagają transportu podprocesu agenta).

Konektory

Zarządzaj integracjami OAuth — Google, Microsoft, GitHub, Notion, Slack i inne.

Przeglądaj katalog dostępnych integracji:

GET /v1/connectors/catalog

Zwraca wszystkich zarejestrowanych dostawców OAuth wraz z ich nazwą, kategorią i domyślnymi zakresami.

Lista Twoich połączonych kont:

GET /v1/connectors

Zwraca aktywne połączenia dla bieżącego profilu. Tokeny nigdy nie są ujawniane — tylko metadane (dostawca, e-mail, status, zakresy, znaczniki czasu).

Sprawdź stan połączenia:

POST /v1/connectors/{id}/test

Zwraca { health: { status, isTokenExpired, canRefresh } }.

Usuń połączenie:

DELETE /v1/connectors/{id}

Tworzenie nowych połączeń wymaga interaktywnego przepływu OAuth za pośrednictwem interfejsu aplikacji lub tras /auth/*.

Wyzwalacze

Zaplanuj automatyczne uruchamianie agentów — codzienne odprawy, cotygodniowe raporty, monitorowanie oparte na interwałach.

Lista wyzwalaczy:

GET /v1/triggers

Utwórz zaplanowany wyzwalacz:

POST /v1/triggers
Content-Type: application/json

{
  "name": "Poranna odprawa",
  "prompt": "Podsumuj moje nieprzeczytane e-maile i dzisiejszy kalendarz",
  "modeId": "general",
  "schedule": { "type": "daily", "time": "08:00" }
}

Obsługiwane typy harmonogramów:

{ "type": "interval", "minutes": 60 } — co N minut (min 15, maks 1440)
{ "type": "daily", "time": "09:00" } — codziennie o określonej godzinie
{ "type": "weekly", "day": "mon", "time": "09:00" } — co tydzień
{ "type": "weekdays", "time": "08:30" } — od poniedziałku do piątku
{ "type": "daysOfWeek", "days": ["mon", "wed", "fri"], "time": "10:00" } — w konkretne dni
{ "type": "monthly", "dayOfMonth": 1, "time": "09:00" } — co miesiąc
{ "type": "manual" } — tylko przy wywołaniu przez API

Ręczne uruchomienie wyzwalacza:

POST /v1/triggers/{id}/fire

Zwraca 202 z threadId dla wynikowego uruchomienia.

Aktualizacja lub usuwanie:

PATCH /v1/triggers/{id}
DELETE /v1/triggers/{id}

Webhooki

Wyzwalacze webhook pozwalają usługom zewnętrznym (CI/CD, monitoring, kreatory formularzy) wywołać uruchomienie agenta przez HTTP.

Utwórz wyzwalacz webhook:

POST /v1/triggers
Content-Type: application/json

{
  "name": "Deploy hook",
  "prompt": "Wystąpiło wdrożenie: {{webhook.body}}",
  "modeId": "general",
  "kind": "webhook"
}

Zwraca 201 z webhookSecret i webhookPath. Zapisz sekret — będzie potrzebny do podpisywania ładunków.

Wyślij webhook:

# Oblicz HMAC-SHA256 surowej treści żądania
SIGNATURE=$(echo -n '{"repo":"my-app","branch":"main"}' | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" | awk '{print $2}')

POST /v1/webhooks/{triggerId}
Content-Type: application/json
X-Webhook-Signature: $SIGNATURE

{"repo": "my-app", "branch": "main"}

Punkt końcowy webhooka NIE wymaga autoryzacji bearer — zamiast tego używa weryfikacji HMAC. Zwraca 202 z threadId wysłanego uruchomienia. Symbol zastępczy {{webhook.body}} w prompcie wyzwalacza jest zastępowany surową treścią żądania.

Funkcje Niestandardowe

Twórz własne narzędzia, które agenci mogą wywoływać. Funkcje są pisane w JavaScript lub Python i wykonywane w piaskownicy (sandbox).

Lista funkcji:

GET /v1/functions

Utwórz funkcję:

POST /v1/functions
Content-Type: application/json

{
  "name": "calculate_bmi",
  "description": "Oblicz wskaźnik masy ciała BMI na podstawie wzrostu i wagi",
  "language": "javascript",
  "source": "return { bmi: (input.weightKg / (input.heightM * input.heightM)).toFixed(1) };",
  "inputSchema": {
    "type": "object",
    "properties": {
      "weightKg": { "type": "number" },
      "heightM": { "type": "number" }
    },
    "required": ["weightKg", "heightM"]
  }
}

Funkcje JavaScript otrzymują input i muszą zwrócić wynik. Funkcje Python ustawiają zmienną result:

# Przykład Python
result = {"bmi": round(input["weightKg"] / (input["heightM"] ** 2), 1)}

Wykonaj funkcję bezpośrednio:

POST /v1/functions/{id}/execute
Content-Type: application/json

{ "input": { "weightKg": 75, "heightM": 1.80 } }

Bezpieczeństwo: JavaScript działa w piaskownicy vm Node (brak dostępu do systemu plików i sieci, limit czasu 10s). Python działa jako podproces z limitem czasu 30s. Oba sprawdzają poprawność danych wejściowych przed wykonaniem.

Aktualizacja lub usuwanie:

PATCH /v1/functions/{id}
DELETE /v1/functions/{id}

Przepływy Pracy (Workflows)

Orkiestruj wielu agentów w grafie DAG (skierowany graf acykliczny) — uruchamiaj kroki równolegle tam, gdzie to możliwe, i przekazuj wyniki z wcześniejszych kroków do późniejszych.

Walidacja grafu przepływu pracy:

POST /v1/workflows/validate
Content-Type: application/json

{
  "graph": {
    "nodes": [
      { "id": "research", "agentId": "general", "prompt": "Zbadaj trendy w energii odnawialnej" },
      { "id": "analyze", "agentId": "general", "prompt": "Zbadaj ceny konkurencji" },
      { "id": "report", "agentId": "general", "prompt": "Napisz raport łączący: {{outputs.research}} i {{outputs.analyze}}", "dependsOn": ["research", "analyze"] }
    ]
  }
}

Zwraca { valid: true/false, errors: [...] }. Sprawdza pod kątem cykli, duplikatów ID i brakujących odniesień do zależności.

Wykonaj przepływ pracy:

POST /v1/workflows/execute
Content-Type: application/json

{
  "graph": {
    "nodes": [
      { "id": "research", "agentId": "general", "prompt": "Zbadaj trendy w energii odnawialnej" },
      { "id": "summarize", "agentId": "general", "prompt": "Podsumuj: {{outputs.research}}", "dependsOn": ["research"] }
    ]
  }
}

Zwraca { status: "completed", outputs: { research: "...", summarize: "..." }, nodeResults: {...} }.

Niezależne węzły (bez wspólnych zależności) działają równolegle. Symbol zastępczy {{outputs.nodeId}} w prompcie węzła jest zastępowany treścią wyjściową nazwanego węzła nadrzędnego. Każdy węzeł to pełne uruchomienie agenta, więc może używać narzędzi, przeglądać sieć i korzystać ze wszystkich możliwości docelowego agenta.

Bazy Wiedzy

Organizuj dokumenty w przeszukiwalne kolekcje, do których agenci mogą się odwoływać.

Lista baz wiedzy:

GET /v1/knowledge/bases

Utwórz bazę wiedzy:

POST /v1/knowledge/bases
Content-Type: application/json

{ "name": "Prace badawcze" }

Zwraca 201 z ID nowej bazy.

Prześlij dokument do bazy wiedzy:

POST /v1/knowledge/bases/{id}/documents
Content-Type: application/json

{
  "fileName": "research-paper.pdf",
  "contentType": "application/pdf",
  "dataUrl": "data:application/pdf;base64,JVBERi0xLjQ...",
  "description": "Trendy energii odnawialnej 2026"
}

Pole dataUrl to adres URL danych zakodowany w base64. Zwraca 201 z metadanymi dokumentu.

Lista dokumentów w bazie wiedzy:

GET /v1/knowledge/bases/{id}/documents

Szukaj wewnątrz bazy wiedzy:

POST /v1/knowledge/bases/{id}/search
Content-Type: application/json

{ "query": "energia odnawialna" }

Zwraca pasujące dokumenty na podstawie nazwy pliku i opisu. Wyszukiwanie semantyczne (wektorowe) pojawi się w przyszłej wersji.

Usuń dokument lub bazę wiedzy:

DELETE /v1/knowledge/bases/{id}/documents/{docId}
DELETE /v1/knowledge/bases/{id}

Eksport i import agentów

Udostępniaj agentów jako przenośne pakiety — między urządzeniami, zespołami lub przez Community Hub.

Eksportuj agenta:

POST /v1/agents/{id}/export

Zwraca pakiet JSON zawierający definicję agenta, wymagania dotyczące narzędzi (pochodne włączonych narzędzi), wymagania dotyczące konektorów (którzy dostawcy OAuth są potrzebni) oraz szablony wyzwalaczy. Metadane synchronizacji są usuwane — pakiet jest czystym, autonomicznym schematem.

Importuj agenta:

POST /v1/agents/import
Content-Type: application/json

{
  \"package\": {
    \"$schema\": \"caiioo.agent.package/v1\",
    \"agent\": {
      \"id\": \"shared-research-agent\",
      \"branding\": { \"name\": \"Research Agent\", \"description\": \"Od zespołu\" },
      \"defaultSettings\": { \"systemPrompt\": \"Badasz różne rzeczy.\" },
      \"settingLevels\": {}
    },
    \"toolRequirements\": [
      { \"toolId\": \"web_browsing\", \"enabled\": true },
      { \"toolId\": \"search_tools\", \"enabled\": true }
    ]
  }
}

Zwraca 201 z zainstalowanym agentem. Konflikty ID z wbudowanymi lub istniejącymi agentami zwracają 409.

Obsługa Błędów

API używa standardowych kodów statusu HTTP:

Kod	Znaczenie
`200`	Sukces
`201`	Utworzono
`202`	Zaakceptowano (operacja asynchroniczna rozpoczęta)
`204`	Usunięto (brak treści)
`400`	Nieprawidłowe żądanie — sprawdź pole `error` po szczegóły
`401`	Brak autoryzacji — brakujący lub nieprawidłowy sekret sesji
`403`	Zabronione — np. próba modyfikacji wbudowanego agenta
`404`	Nie znaleziono
`409`	Konflikt — np. ID agenta już istnieje
`422`	Błąd walidacji — dane wejściowe nie pasują do schematu narzędzia
`500`	Błąd serwera — sprawdź pole `error`
`501`	Nie zaimplementowano — funkcja istnieje, ale nie jest dostępna w ten sposób
`503`	Usługa niedostępna — magazyn lub dostawca nie jest gotowy

Wszystkie odpowiedzi o błędach zawierają { "error": "czytelny dla człowieka komunikat" }.

Przykład Szybkiego Startu

Oto kompletny przepływ pracy: utwórz agenta, uruchom go i strumieniuj wyniki.

# 1. Utwórz niestandardowego agenta
curl -X POST http://localhost:3847/v1/agents \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "quick-summarizer",
    "branding": { "name": "Szybki Podsumowywacz" },
    "defaultSettings": {
      "systemPrompt": "Podsumuj wszelkie dane wejściowe zwięźle w 3 punktach.",
      "enabledTools": { "web_browsing": true }
    },
    "settingLevels": {}
  }'

# 2. Uruchom go asynchronicznie
RUN=$(curl -s -X POST http://localhost:3847/v1/runs \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "agentId": "quick-summarizer", "input": { "message": "Podsumuj https://pl.wikipedia.org/wiki/Sztuczna_inteligencja" }, "mode": "async" }')

RUN_ID=$(echo $RUN | jq -r '.runId')

# 3. Strumieniuj zdarzenia
curl -N http://localhost:3847/v1/runs/$RUN_ID/events \
  -H "Authorization: Bearer $API_TOKEN"

# 4. Eksportuj agenta do udostępnienia
curl -X POST http://localhost:3847/v1/agents/quick-summarizer/export \
  -H "Authorization: Bearer $API_TOKEN"

This guide is maintained by the Caiioo team using Slate, our built-in editor.