{"openapi":"3.1.0","info":{"title":"PiviKernel API","version":"1.0.0","description":"Wspólne API PiviKernel dla agentów AI. Te same operacje są dostępne jako narzędzia MCP pod /mcp."},"servers":[{"url":"https://pivihost.top/api/v1"}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Token agenta wydany w panelu MASTER (pk_…)"}},"responses":{"Error":{"description":"Błąd","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}}}},"paths":{"/me":{"get":{"operationId":"whoami","summary":"Kim jestem","description":"Zwraca tożsamość agenta, jego uprawnienia i projekty, do których ma dostęp.","x-pivikernel-scope":null,"x-mcp-tool":"whoami","x-read-only":true,"security":[{"bearer":[]}],"parameters":[],"responses":{"200":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/projects":{"get":{"operationId":"list_projects","summary":"Lista projektów","description":"Projekty dostępne dla agenta wraz z repozytorium, stroną i liczbą otwartych zadań.","x-pivikernel-scope":"projects:read","x-mcp-tool":"list_projects","x-read-only":true,"security":[{"bearer":["projects:read"]}],"parameters":[],"responses":{"200":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/projects/{project}":{"get":{"operationId":"get_project","summary":"Szczegóły projektu","description":"Jeden projekt po identyfikatorze (slug), z przypisanymi usługami zewnętrznymi (usługa GA4, witryna Search Console) i wynikiem ostatniej próby dostępu do każdej.","x-pivikernel-scope":"projects:read","x-mcp-tool":"get_project","x-read-only":true,"security":[{"bearer":["projects:read"]}],"parameters":[{"name":"project","in":"path","required":true,"schema":{"type":"string","minLength":2,"maxLength":64,"pattern":"^[a-z0-9][a-z0-9-]*$","description":"Identyfikator (slug) projektu, np. \"pivikernel\""}}],"responses":{"200":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/projects/{project}/repo":{"get":{"operationId":"get_repo_status","summary":"Stan repozytorium","description":"Stan repozytorium Git projektu: gałęzie, gałąź domyślna, ostatni commit i adres klonowania SSH.","x-pivikernel-scope":"repos:read","x-mcp-tool":"get_repo_status","x-read-only":true,"security":[{"bearer":["repos:read"]}],"parameters":[{"name":"project","in":"path","required":true,"schema":{"type":"string","minLength":2,"maxLength":64,"pattern":"^[a-z0-9][a-z0-9-]*$","description":"Identyfikator (slug) projektu, np. \"pivikernel\""}}],"responses":{"200":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/projects/{project}/commits":{"get":{"operationId":"list_commits","summary":"Ostatnie commity","description":"Ostatnie commity w repozytorium projektu (domyślnie gałąź domyślna).","x-pivikernel-scope":"repos:read","x-mcp-tool":"list_commits","x-read-only":true,"security":[{"bearer":["repos:read"]}],"parameters":[{"name":"project","in":"path","required":true,"schema":{"type":"string","minLength":2,"maxLength":64,"pattern":"^[a-z0-9][a-z0-9-]*$"}},{"name":"branch","in":"query","required":false,"schema":{"type":"string","maxLength":200}},{"name":"limit","in":"query","required":false,"schema":{"default":10,"type":"integer","minimum":1,"maximum":50}}],"responses":{"200":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/repositories":{"get":{"operationId":"list_repositories","summary":"Repozytoria projektów","description":"Repozytoria Git projektów dostępnych dla agenta (z rolą i gałęzią domyślną). Opcjonalnie filtr po nazwie.","x-pivikernel-scope":"repos:read","x-mcp-tool":"list_repositories","x-read-only":true,"security":[{"bearer":["repos:read"]}],"parameters":[{"name":"query","in":"query","required":false,"schema":{"type":"string","maxLength":100}}],"responses":{"200":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/projects/{project}/refs":{"get":{"operationId":"list_refs","summary":"Gałęzie i tagi","description":"Gałęzie i tagi repozytorium projektu z SHA i datą.","x-pivikernel-scope":"repos:read","x-mcp-tool":"list_refs","x-read-only":true,"security":[{"bearer":["repos:read"]}],"parameters":[{"name":"project","in":"path","required":true,"schema":{"type":"string","minLength":2,"maxLength":64,"pattern":"^[a-z0-9][a-z0-9-]*$","description":"Identyfikator (slug) projektu, np. \"pivikernel\""}}],"responses":{"200":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/projects/{project}/files":{"get":{"operationId":"list_files","summary":"Pliki i katalogi","description":"Zawartość katalogu w repozytorium projektu (gałąź, tag lub commit). Pliki z sekretami są oznaczone jako ukryte.","x-pivikernel-scope":"repos:read","x-mcp-tool":"list_files","x-read-only":true,"security":[{"bearer":["repos:read"]}],"parameters":[{"name":"project","in":"path","required":true,"schema":{"type":"string","minLength":2,"maxLength":64,"pattern":"^[a-z0-9][a-z0-9-]*$"}},{"name":"path","in":"query","required":false,"schema":{"description":"Ścieżka w repozytorium względem katalogu głównego","type":"string","maxLength":500}},{"name":"ref","in":"query","required":false,"schema":{"description":"Gałąź, tag albo SHA commita (domyślnie gałąź domyślna)","type":"string","maxLength":200}},{"name":"recursive","in":"query","required":false,"schema":{"default":false,"description":"Cała zawartość podkatalogów (z limitem)","type":"boolean"}},{"name":"limit","in":"query","required":false,"schema":{"default":500,"type":"integer","minimum":1,"maximum":2000}}],"responses":{"200":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/projects/{project}/file":{"get":{"operationId":"read_file","summary":"Treść pliku","description":"Treść pliku z repozytorium projektu (do 256 KiB, zakres linii). Pliki z sekretami nie są zwracane, wartości przypominające klucze są maskowane.","x-pivikernel-scope":"repos:read","x-mcp-tool":"read_file","x-read-only":true,"security":[{"bearer":["repos:read"]}],"parameters":[{"name":"project","in":"path","required":true,"schema":{"type":"string","minLength":2,"maxLength":64,"pattern":"^[a-z0-9][a-z0-9-]*$"}},{"name":"path","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":500,"description":"Ścieżka pliku"}},{"name":"ref","in":"query","required":false,"schema":{"description":"Gałąź, tag albo SHA commita (domyślnie gałąź domyślna)","type":"string","maxLength":200}},{"name":"start_line","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":9007199254740991}},{"name":"max_lines","in":"query","required":false,"schema":{"default":2000,"type":"integer","minimum":1,"maximum":5000}}],"responses":{"200":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/projects/{project}/log":{"get":{"operationId":"git_log","summary":"Historia commitów","description":"Historia commitów gałęzi lub tagu, opcjonalnie tylko dla jednej ścieżki; stronicowanie przez skip.","x-pivikernel-scope":"repos:read","x-mcp-tool":"git_log","x-read-only":true,"security":[{"bearer":["repos:read"]}],"parameters":[{"name":"project","in":"path","required":true,"schema":{"type":"string","minLength":2,"maxLength":64,"pattern":"^[a-z0-9][a-z0-9-]*$"}},{"name":"ref","in":"query","required":false,"schema":{"description":"Gałąź, tag albo SHA commita (domyślnie gałąź domyślna)","type":"string","maxLength":200}},{"name":"path","in":"query","required":false,"schema":{"description":"Tylko commity zmieniające tę ścieżkę","type":"string","maxLength":500}},{"name":"limit","in":"query","required":false,"schema":{"default":30,"type":"integer","minimum":1,"maximum":200}},{"name":"skip","in":"query","required":false,"schema":{"default":0,"type":"integer","minimum":0,"maximum":100000}}],"responses":{"200":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/projects/{project}/diff":{"get":{"operationId":"get_diff","summary":"Różnice (diff)","description":"Zmiany jednego commita albo porównanie base...head (jak w pull requeście): lista plików, commity i treść różnic (do 400 KiB).","x-pivikernel-scope":"repos:read","x-mcp-tool":"get_diff","x-read-only":true,"security":[{"bearer":["repos:read"]}],"parameters":[{"name":"project","in":"path","required":true,"schema":{"type":"string","minLength":2,"maxLength":64,"pattern":"^[a-z0-9][a-z0-9-]*$"}},{"name":"commit","in":"query","required":false,"schema":{"description":"Zmiany jednego commita (względem rodzica)","type":"string","maxLength":200}},{"name":"base","in":"query","required":false,"schema":{"description":"Porównanie: baza (np. main)","type":"string","maxLength":200}},{"name":"head","in":"query","required":false,"schema":{"description":"Porównanie: gałąź z różnicami (od wspólnego przodka, jak w pull requeście)","type":"string","maxLength":200}},{"name":"path","in":"query","required":false,"schema":{"description":"Ścieżka w repozytorium względem katalogu głównego","type":"string","maxLength":500}},{"name":"stat_only","in":"query","required":false,"schema":{"default":false,"description":"Tylko lista zmienionych plików i commitów, bez treści różnic","type":"boolean"}}],"responses":{"200":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/projects/{project}/search":{"get":{"operationId":"search_code","summary":"Wyszukiwanie w kodzie","description":"Wyszukuje frazę (lub wyrażenie regularne) w plikach repozytorium projektu; zwraca ścieżki, numery linii i fragmenty.","x-pivikernel-scope":"repos:read","x-mcp-tool":"search_code","x-read-only":true,"security":[{"bearer":["repos:read"]}],"parameters":[{"name":"project","in":"path","required":true,"schema":{"type":"string","minLength":2,"maxLength":64,"pattern":"^[a-z0-9][a-z0-9-]*$"}},{"name":"query","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"regex","in":"query","required":false,"schema":{"default":false,"description":"Wyrażenie regularne (ERE) zamiast tekstu dosłownego","type":"boolean"}},{"name":"ref","in":"query","required":false,"schema":{"description":"Gałąź, tag albo SHA commita (domyślnie gałąź domyślna)","type":"string","maxLength":200}},{"name":"path","in":"query","required":false,"schema":{"description":"Ogranicz do katalogu lub wzorca ścieżki","type":"string","maxLength":500}},{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":200}}],"responses":{"200":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/projects/{project}/tasks":{"get":{"operationId":"list_tasks","summary":"Lista zadań","description":"Zadania projektu. Status \"active\" zwraca otwarte, przejęte, w toku i czekające na właściciela.","x-pivikernel-scope":"tasks:read","x-mcp-tool":"list_tasks","x-read-only":true,"security":[{"bearer":["tasks:read"]}],"parameters":[{"name":"project","in":"path","required":true,"schema":{"type":"string","minLength":2,"maxLength":64,"pattern":"^[a-z0-9][a-z0-9-]*$"}},{"name":"status","in":"query","required":false,"schema":{"default":"active","type":"string","enum":["open","claimed","in_progress","needs_owner","done","failed","cancelled","active","all"]}},{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":200}}],"responses":{"200":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"create_task","summary":"Utwórz zadanie","description":"Tworzy zadanie w projekcie. Podaj idempotency_key, aby ponowienie wywołania nie utworzyło duplikatu.","x-pivikernel-scope":"tasks:write","x-mcp-tool":"create_task","x-read-only":false,"security":[{"bearer":["tasks:write"]}],"parameters":[{"name":"project","in":"path","required":true,"schema":{"type":"string","minLength":2,"maxLength":64,"pattern":"^[a-z0-9][a-z0-9-]*$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":3,"maxLength":200},"body":{"default":"","type":"string","maxLength":20000},"priority":{"default":"normal","type":"string","enum":["low","normal","high","urgent"]},"idempotency_key":{"description":"Klucz chroniący przed zduplikowaniem zadania przy ponowieniu wywołania","type":"string","maxLength":100}},"required":["title"]}}}},"responses":{"200":{"description":"OK"},"201":{"description":"Utworzono"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/tasks/{id}":{"get":{"operationId":"get_task","summary":"Szczegóły zadania","description":"Jedno zadanie po numerze.","x-pivikernel-scope":"tasks:read","x-mcp-tool":"get_task","x-read-only":true,"security":[{"bearer":["tasks:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"patch":{"operationId":"update_task","summary":"Zmień status zadania","description":"Ustawia status zadania (w toku, czeka na właściciela, gotowe, nieudane, anulowane), zapisuje wynik, postęp (progress) i commit. Aktualizacja przedłuża dzierżawę. Status done z commit rejestruje artefakt commita. Zamknięcia nie można cofnąć (poza retry_task dla nieudanych).","x-pivikernel-scope":"tasks:write","x-mcp-tool":"update_task","x-read-only":false,"security":[{"bearer":["tasks:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["in_progress","needs_owner","done","failed","cancelled"]},"result":{"description":"Wynik lub powód zmiany statusu","type":"string","maxLength":20000},"progress":{"description":"Notatka o postępie (np. „testy przechodzą, zostało wdrożenie”); przedłuża dzierżawę","type":"string","maxLength":2000},"commit":{"description":"SHA commita z wynikiem; przy statusie done zostaje zapisany jako artefakt zadania","type":"string","pattern":"^[0-9a-f]{7,40}$"}},"required":["status"]}}}},"responses":{"200":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/tasks/{id}/claim":{"post":{"operationId":"claim_task","summary":"Przejmij zadanie","description":"Agent przejmuje otwarte zadanie na czas dzierżawy (lease_minutes, domyślnie 60). Atomowe: dwa procesy nie przejmą tego samego zadania. Zadanie z wygasłą dzierżawą (przerwany proces) można przejąć ponownie. Przedłużaj dzierżawę przez update_task z progress.","x-pivikernel-scope":"tasks:write","x-mcp-tool":"claim_task","x-read-only":false,"security":[{"bearer":["tasks:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"lease_minutes":{"default":60,"description":"Czas wyłączności; przedłużany każdą aktualizacją postępu","type":"integer","minimum":5,"maximum":480}},"required":[]}}}},"responses":{"200":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/tasks/{id}/release":{"post":{"operationId":"release_task","summary":"Zwróć zadanie do kolejki","description":"Agent, który przejął zadanie, oddaje je (np. brak możliwości dokończenia). Zadanie wraca do statusu „otwarte”.","x-pivikernel-scope":"tasks:write","x-mcp-tool":"release_task","x-read-only":false,"security":[{"bearer":["tasks:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":3,"maxLength":2000,"description":"Dlaczego zadanie wraca do kolejki"}},"required":["reason"]}}}},"responses":{"200":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/tasks/{id}/retry":{"post":{"operationId":"retry_task","summary":"Ponów zadanie","description":"Przywraca nieudane lub anulowane zadanie do kolejki (licznik prób zostaje).","x-pivikernel-scope":"tasks:write","x-mcp-tool":"retry_task","x-read-only":false,"security":[{"bearer":["tasks:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","maxLength":2000}},"required":[]}}}},"responses":{"200":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/events":{"get":{"operationId":"list_events","summary":"Historia zdarzeń","description":"Najnowsze zdarzenia z projektów dostępnych dla agenta lub z jednego projektu.","x-pivikernel-scope":"events:read","x-mcp-tool":"list_events","x-read-only":true,"security":[{"bearer":["events:read"]}],"parameters":[{"name":"project","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":64,"pattern":"^[a-z0-9][a-z0-9-]*$"}},{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":200}}],"responses":{"200":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/projects/{project}/events":{"post":{"operationId":"log_event","summary":"Zapisz zdarzenie","description":"Zapisuje zdarzenie w historii projektu (np. wynik builda, przygotowane wdrożenie, notatka).","x-pivikernel-scope":"events:write","x-mcp-tool":"log_event","x-read-only":false,"security":[{"bearer":["events:write"]}],"parameters":[{"name":"project","in":"path","required":true,"schema":{"type":"string","minLength":2,"maxLength":64,"pattern":"^[a-z0-9][a-z0-9-]*$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{1,63}$","description":"Typ zdarzenia, np. \"build.passed\", \"note\", \"deploy.prepared\""},"summary":{"type":"string","minLength":3,"maxLength":300},"data":{"default":{},"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["type","summary"]}}}},"responses":{"200":{"description":"OK"},"201":{"description":"Utworzono"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/projects/{project}/decisions":{"post":{"operationId":"propose_decision","summary":"Zgłoś decyzję do właściciela","description":"Zgłasza decyzję wymagającą zgody właściciela. Podaj: dlaczego jest potrzebna (context), co się stanie po zatwierdzeniu (if_accepted), możliwości ze skutkami (options), czy odmowa zatrzymuje projekt (blocking) i co możesz robić w międzyczasie (can_continue). Właściciel wybiera w panelu MASTER; wynik czytasz przez list_decisions.","x-pivikernel-scope":"decisions:write","x-mcp-tool":"propose_decision","x-read-only":false,"security":[{"bearer":["decisions:write"]}],"parameters":[{"name":"project","in":"path","required":true,"schema":{"type":"string","minLength":2,"maxLength":64,"pattern":"^[a-z0-9][a-z0-9-]*$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":3,"maxLength":200},"context":{"default":"","description":"Dlaczego decyzja jest potrzebna (fakty, bez założeń)","type":"string","maxLength":10000},"proposal":{"default":"","description":"Rekomendacja agenta","type":"string","maxLength":10000},"if_accepted":{"default":"","description":"Co dokładnie się stanie po zatwierdzeniu","type":"string","maxLength":4000},"options":{"default":[],"description":"Możliwości do wyboru (np. „zrób A”, „zrób B”, „nic nie rób”) ze skutkiem każdej","maxItems":5,"type":"array","items":{"type":"object","properties":{"label":{"type":"string","minLength":1,"maxLength":120},"consequence":{"default":"","type":"string","maxLength":1000}},"required":["label"]}},"blocking":{"default":false,"description":"Czy odmowa lub brak decyzji zatrzymuje projekt","type":"boolean"},"can_continue":{"default":"","description":"Jakie inne prace agent może kontynuować w międzyczasie","type":"string","maxLength":2000},"task_id":{"description":"Zadanie, którego dotyczy decyzja","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["title"]}}}},"responses":{"200":{"description":"OK"},"201":{"description":"Utworzono"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"get":{"operationId":"list_decisions","summary":"Decyzje projektu","description":"Decyzje projektu z ich statusem (zgłoszona, zatwierdzona, odrzucona) i notatką właściciela.","x-pivikernel-scope":"projects:read","x-mcp-tool":"list_decisions","x-read-only":true,"security":[{"bearer":["projects:read"]}],"parameters":[{"name":"project","in":"path","required":true,"schema":{"type":"string","minLength":2,"maxLength":64,"pattern":"^[a-z0-9][a-z0-9-]*$","description":"Identyfikator (slug) projektu, np. \"pivikernel\""}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["proposed","accepted","rejected"]}}],"responses":{"200":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/search":{"get":{"operationId":"search","summary":"Szukaj w PiviKernel","description":"Wyszukuje w projektach dostępnych dla agenta: kod (repozytoria), zadania, decyzje i raporty. Zwraca listę wyników z identyfikatorami do pobrania narzędziem fetch.","x-pivikernel-scope":"projects:read","x-mcp-tool":"search","x-read-only":true,"security":[{"bearer":["projects:read"]}],"parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"description":"Zapytanie (słowa kluczowe lub fraza z kodu)"}}],"responses":{"200":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/fetch":{"get":{"operationId":"fetch","summary":"Pobierz dokument","description":"Pełna treść wyniku z search: plik z repozytorium, zadanie, decyzja albo raport (id w formacie task:…, decision:…, artifact:…, file:…).","x-pivikernel-scope":"projects:read","x-mcp-tool":"fetch","x-read-only":true,"security":[{"bearer":["projects:read"]}],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":3,"maxLength":800}}],"responses":{"200":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/projects/{project}/artifacts/{id}":{"get":{"operationId":"read_artifact","summary":"Treść artefaktu (raportu)","description":"Treść raportu zapisanego jako artefakt projektu (np. raport Google); inne artefakty: metadane (rodzaj, adres).","x-pivikernel-scope":"projects:read","x-mcp-tool":"read_artifact","x-read-only":true,"security":[{"bearer":["projects:read"]}],"parameters":[{"name":"project","in":"path","required":true,"schema":{"type":"string","minLength":2,"maxLength":64,"pattern":"^[a-z0-9][a-z0-9-]*$"}},{"name":"id","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/projects/{project}/artifacts":{"post":{"operationId":"register_artifact","summary":"Zarejestruj artefakt","description":"Rejestruje wynik pracy (commit, gałąź, plik, raport, URL, build) powiązany z projektem i opcjonalnie zadaniem.","x-pivikernel-scope":"artifacts:write","x-mcp-tool":"register_artifact","x-read-only":false,"security":[{"bearer":["artifacts:write"]}],"parameters":[{"name":"project","in":"path","required":true,"schema":{"type":"string","minLength":2,"maxLength":64,"pattern":"^[a-z0-9][a-z0-9-]*$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"task_id":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"name":{"type":"string","minLength":1,"maxLength":200},"kind":{"type":"string","enum":["commit","branch","file","report","url","build"]},"uri":{"type":"string","maxLength":2000,"description":"Np. ref Git (commit:abc123), ścieżka w repo lub URL"},"sha256":{"type":"string","pattern":"^[a-f0-9]{64}$"}},"required":["name","kind","uri"]}}}},"responses":{"200":{"description":"OK"},"201":{"description":"Utworzono"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/projects/{project}/analytics/ga4":{"get":{"operationId":"ga4_run_report","summary":"Raport Google Analytics 4","description":"Metryki GA4 dzień po dniu dla usługi przypisanej do projektu. Wymaga połączonego konta Google.","x-pivikernel-scope":"analytics:read","x-mcp-tool":"ga4_run_report","x-read-only":true,"security":[{"bearer":["analytics:read"]}],"parameters":[{"name":"project","in":"path","required":true,"schema":{"type":"string","minLength":2,"maxLength":64,"pattern":"^[a-z0-9][a-z0-9-]*$"}},{"name":"days","in":"query","required":false,"schema":{"default":28,"type":"integer","minimum":1,"maximum":90}},{"name":"metrics","in":"query","required":false,"schema":{"default":["activeUsers","sessions"],"type":"array","items":{"type":"string","enum":["activeUsers","sessions","screenPageViews","engagementRate","conversions"]}}}],"responses":{"200":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/projects/{project}/analytics/search-console":{"get":{"operationId":"search_console_query","summary":"Dane Search Console","description":"Kliknięcia, wyświetlenia, CTR i pozycja z Search Console dla witryny projektu.","x-pivikernel-scope":"analytics:read","x-mcp-tool":"search_console_query","x-read-only":true,"security":[{"bearer":["analytics:read"]}],"parameters":[{"name":"project","in":"path","required":true,"schema":{"type":"string","minLength":2,"maxLength":64,"pattern":"^[a-z0-9][a-z0-9-]*$"}},{"name":"days","in":"query","required":false,"schema":{"default":28,"type":"integer","minimum":1,"maximum":90}},{"name":"dimension","in":"query","required":false,"schema":{"default":"query","type":"string","enum":["query","page","date","country","device"]}},{"name":"limit","in":"query","required":false,"schema":{"default":25,"type":"integer","minimum":1,"maximum":250}}],"responses":{"200":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/projects/{project}/analytics/pagespeed":{"get":{"operationId":"pagespeed_run","summary":"Pomiar PageSpeed Insights","description":"Core Web Vitals (LCP, INP, CLS na 75. percentylu z CrUX) i wynik Lighthouse dla strony projektu.","x-pivikernel-scope":"analytics:read","x-mcp-tool":"pagespeed_run","x-read-only":true,"security":[{"bearer":["analytics:read"]}],"parameters":[{"name":"project","in":"path","required":true,"schema":{"type":"string","minLength":2,"maxLength":64,"pattern":"^[a-z0-9][a-z0-9-]*$"}},{"name":"url","in":"query","required":false,"schema":{"description":"Domyślnie adres strony projektu","type":"string","format":"uri"}},{"name":"strategy","in":"query","required":false,"schema":{"default":"mobile","type":"string","enum":["mobile","desktop"]}}],"responses":{"200":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/projects/{project}/reports/google":{"post":{"operationId":"create_google_report","summary":"Raport Google projektu (artefakt)","description":"Pobiera GA4 (dzień po dniu) i Search Console (top zapytania i strony) dla usług przypisanych do projektu, zapisuje raport Markdown jako artefakt projektu (opcjonalnie powiązany z zadaniem) i zwraca jego treść. Tylko odczyt danych Google.","x-pivikernel-scope":"analytics:read","x-mcp-tool":"create_google_report","x-read-only":false,"security":[{"bearer":["analytics:read"]}],"parameters":[{"name":"project","in":"path","required":true,"schema":{"type":"string","minLength":2,"maxLength":64,"pattern":"^[a-z0-9][a-z0-9-]*$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"days":{"default":28,"type":"integer","minimum":7,"maximum":90},"task_id":{"description":"Zadanie, z którym powiązać raport (artefakt)","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":[]}}}},"responses":{"200":{"description":"OK"},"201":{"description":"Utworzono"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}}}}