Narzędzia

Każde narzędzie z aplikacji Gaius-Lex możesz uruchomić przez API: 12 wbudowanych narzędzi Gaius (Pulpit → „Zobacz wszystkie narzędzia”) oraz opublikowane narzędzia Twoje i organizacji (skill, bloczek, schemat). Automaty, czyli narzędzia uruchamiane samoczynnie, nie mają endpointu.

Narzędzie działa tak samo jak w aplikacji: dostaje pola formularza, pracuje w tle i zwraca wynik. Endpointy opisuje kategoria Tools w referencji API.

Uwierzytelnianie

Każde żądanie wysyłasz z kluczem organizacji w nagłówku Authorization: Api-Key <klucz>. Klucz utworzysz w aplikacji: Ustawienia → Organizacja → Klucze API. Klucz tylko do odczytu może listować narzędzia i czytać ich dokumentację, ale nie może ich uruchamiać.

Endpointy

Metoda i ścieżka	Opis
`GET /api/v1/tool-api`	Lista narzędzi dostępnych dla klucza, każde z `run_url` i `info_url`.
`GET /api/v1/tool-api/{tool_id}/info`	Dokumentacja narzędzia: pola wejścia (`input_schema`), wyniki (`outputs_schema`) i przykład wywołania.
`POST /api/v1/tool-api/{tool_id}`	Uruchomienie w tle. Odpowiedź `202` z `run_id` i `poll_url`.
`GET /api/v1/tool-api/{tool_id}/runs/{run_id}`	Stan i wynik uruchomienia.
`POST /api/v1/tool-api/{tool_id}/runs/{run_id}:cancel`	Anulowanie uruchomienia.

Uruchomienie krok po kroku

Sprawdź pola narzędzia: GET /api/v1/tool-api/{tool_id}/info.
Wyślij POST /api/v1/tool-api/{tool_id} z {"inputs": {...}}. Klucze w inputs to klucze pól z input_schema. Pola są sprawdzane tak jak formularz w aplikacji.
Odpytuj poll_url co kilka sekund, aż odpowiedź będzie miała kod 200.
Odczytaj outputs. Pliki wynikowe mają download_url.

curl -X POST https://api.gaius-lex.pl/api/v1/tool-api/gaius.anonymize \
  -H "Authorization: Api-Key $GAIUS_API_KEY" -H "Content-Type: application/json" \
  -d '{"inputs": {"text": "Jan Kowalski, PESEL 80010112345, mieszka w Krakowie."}}'
# 202 {"run_id": "6a0f…", "tool_id": "gaius.anonymize", "status": "queued",
#      "poll_url": "https://api.gaius-lex.pl/api/v1/tool-api/gaius.anonymize/runs/6a0f…", …}

curl https://api.gaius-lex.pl/api/v1/tool-api/gaius.anonymize/runs/6a0f… \
  -H "Authorization: Api-Key $GAIUS_API_KEY"
# 200 {"status": "succeeded", "outputs": {"text": "[OSOBA_1], PESEL [PESEL_1], mieszka w [MIEJSCOWOŚĆ_1]."}, …}

Narzędzia z agentem działają od kilkudziesięciu sekund do kilku minut. Uruchomienia z API trafiają do tej samej kolejki konta co uruchomienia z aplikacji. Gdy kolejka jest pełna, API zwraca 429, a queue_position pokazuje miejsce w kolejce. W aplikacji przy każdym narzędziu jest gotowe wywołanie: narzędzie → „Wywołanie API”.

Stany uruchomienia

`status`	Kod odpowiedzi	Znaczenie
`queued`	`202`	Czeka w kolejce.
`running`	`202`	Trwa.
`waiting_for_user`	`200`	Krok schematu się nie udał i narzędzie czeka na decyzję w aplikacji. `outputs` jest puste.
`succeeded`	`200`	Zakończone, wynik jest w `outputs`.
`failed`	`200`	Błąd, opis jest w `error` (`code`, `message`).
`cancelled`	`200`	Anulowane.

Pliki

Pola typu plik przyjmują listę [{"file_id": "<UUID>"}]. Plik musi leżeć na dysku konta klucza: UUID dostajesz z POST /api/v2/files albo z GET /api/v2/files/uploads/{request_id} (opis w Agent API (v2)). Pliki wynikowe mają name, mime, size, uuid i download_url.

Wbudowane narzędzia Gaius

Wejście: text to tekst (do 20 000 znaków), files to lista plików. Wyjście: outputs.text to odpowiedź Gaiusa. Narzędzia, które zapisują albo zmieniają pliki, zwracają je dodatkowo w outputs.files.

`tool_id`	Nazwa w aplikacji	Wejście	Wyjście
`gaius.legalResearch`	Research prawny	`text` (wymagane)	`text`
`gaius.prepareDocument`	Przygotuj pismo	`text` (wymagane), `files` (0–10)	`text`
`gaius.caseLawLine`	Znajdź linię orzeczniczą	`text` (wymagane)	`text`
`gaius.extendText`	Wydłuż tekst	`text` (wymagane)	`text`
`gaius.compareDocuments`	Porównaj dokumenty	`files` (2–10)	`text`
`gaius.translate`	Tłumacz	`text` albo `files` (DOCX, 0–5)	`text`, `files`
`gaius.inconsistencyAnalysis`	Analiza niespójności	`text` albo `files` (DOCX, 0–5)	`text`, `files`
`gaius.textCorrection`	Korekta tekstu	`text` albo `files` (DOCX, 0–5)	`text`, `files`
`gaius.chatWithDocument`	Czat z dokumentem	`files` (1–5), `text` (pytanie, opcjonalne)	`text`
`gaius.anonymize`	Anonimizuj	`text` albo `files` (DOCX, 0–5)	`text`, `files`
`gaius.ocr`	Odczytaj tekst z obrazka	`files` (PDF, PNG, JPG, 1–10)	`text`
`gaius.createPdf`	Stwórz PDF	`files` (2–10)	`text`, `files`

„text albo files” oznacza, że trzeba podać przynajmniej jedno z nich. Dla plików DOCX zmiany są wprowadzane jako śledzone zmiany i komentarze, a tłumaczenie powstaje jako nowy plik.

Narzędzia organizacji

Opublikowane skille, bloczki i schematy mają tool_id w postaci tool.<typ>.<id>, np. tool.skill.org_1.klauzule. Pola wejścia i wyniki zależą od narzędzia, dlatego zawsze opisuje je GET /api/v1/tool-api/{tool_id}/info. Lista narzędzi zależy od klucza, więc /info narzędzi wymaga klucza.

Błędy

Błędy mają postać {"code": "...", "field": "...", "detail": "..."}.

Kod HTTP	`code`	Kiedy
`400`	`invalid_request`, `unknown_input`, `required`, …	Błędne `inputs`. `field` wskazuje pole.
`403`	`forbidden`	Brak dostępu do skilla narzędzia. Brak klucza albo uruchomienie kluczem tylko do odczytu też dają `403`.
`404`	`tool_not_found`, `run_not_found`	Nie ma takiego narzędzia albo uruchomienia dla tego klucza.
`409`	`tool_disabled`, `automation_tool`	Narzędzie jest wyłączone albo jest automatem.
`410`	`skill_gone`	Skill narzędzia został usunięty.
`429`		Kolejka uruchomień konta jest pełna.

Dokumentacja endpointów (`/info`)

Każdy endpoint API ma bliźniaczy GET <endpoint>/info, np. GET /api/v1/search/info, GET /api/v1/ocr/poll/{request_id}/info albo GET /api/v1/tool-api/gaius.ocr/info. Zwraca:

endpoint i method: ścieżkę i metodę opisywanego endpointu,
summary i description: co robi endpoint,
input_schema: JSON Schema wejścia (parametry i treść żądania). Endpoint bez wejścia ma {"type": "object", "properties": {}},
output_schema: JSON Schema odpowiedzi. Odpowiedź bez treści (204) ma {"type": "null"},
examples i related: przykłady i powiązane endpointy (np. poll_url),
operations: opis każdej metody tej ścieżki, gdy jest ich kilka.

/info endpointów API nie wymaga klucza. Wyjątkiem są narzędzia, bo ich zestaw zależy od klucza.

curl https://api.gaius-lex.pl/api/v1/search/info
curl https://api.gaius-lex.pl/api/v1/tool-api/gaius.ocr/info -H "Authorization: Api-Key $GAIUS_API_KEY"

Uwierzytelnianie​

Endpointy​

Uruchomienie krok po kroku​

Stany uruchomienia​

Pliki​

Wbudowane narzędzia Gaius​

Narzędzia organizacji​

Błędy​

Dokumentacja endpointów (/info)​