--- title: "Polityki eskalacji — API v1 i MCP | Nodea" description: "Dokumentacja REST API v1 i narzędzi MCP dla polityk eskalacji w Nodea: kroki eskalacji (position, delay_minutes), reguła XOR grupa/integracja, scope'y alerting oraz przykłady curl i JSON-RPC." url: "https://nodea.pl/pl/dokumentacja-api/escalation-policies" lang: "pl" updated: "2026-07-16" --- # Polityki eskalacji — API v1 i MCP | Nodea > Polityki eskalacji sterują tym, kogo i po jakim czasie powiadamiamy podczas incydentu. Poznaj endpointy REST API v1, kształt obiektu kroku (reguła XOR), kody błędów oraz komplet 5 narzędzi MCP. Polityka eskalacji to uporządkowana lista **kroków**, które decydują, kogo i po jakim opóźnieniu powiadamiamy w trakcie incydentu. Każdy krok wskazuje jeden cel powiadomienia — grupę powiadomień albo integrację — oraz opóźnienie liczone od otwarcia incydentu. Ten dokument opisuje operacje REST **API v1** oraz komplet narzędzi **MCP** do zarządzania politykami. Wszystkie endpointy działają pod ścieżką bazową https://app.nodea.io/api/v1. Uwierzytelnianie odbywa się osobistym tokenem Passport przekazywanym w nagłówku Authorization: Bearer \. Obowiązuje limit throttle:api-v1 = 240 żądań na minutę. Polityki eskalacji wymagają włączonego modułu **Strony WWW** (flaga Pennant websites) — trasy jadą pod tą samą flagą co monitoring stron, nie mają własnej. Dostęp jest zawężony do właściciela: obcy lub nieznany identyfikator zawsze zwraca 404 (nie 403), aby API nie potwierdzało istnienia cudzego zasobu. Scope'y OAuth: odczyt wymaga alerting:read, zapis alerting:write, usuwanie alerting:delete. ## API v1 MetodaŚcieżkaScopeOpisGET/escalation-policiesalerting:readLista polityk właściciela (paginacja, wyszukiwanie, sortowanie).GET/escalation-policies/{escalationPolicy}alerting:readPojedyncza polityka z krokami w kolejności pozycji.POST/escalation-policiesalerting:writeUtworzenie polityki z listą kroków (zwraca 201).PATCH / PUT/escalation-policies/{escalationPolicy}alerting:writeAktualizacja nazwy i/lub całego łańcucha kroków.DELETE/escalation-policies/{escalationPolicy}alerting:deleteTrwałe usunięcie polityki i jej kroków (zwraca 204). ### Obiekt kroku (steps\[\]) i reguła XOR Pole steps to tablica kroków. Każdy krok zawiera: - delay\_minutes — liczba całkowita 0–1440. Opóźnienie liczone od **otwarcia incydentu** (a nie od poprzedniego kroku), po którym ten krok się uruchamia. Wartość 0 oznacza natychmiastowe powiadomienie. - notification\_group\_id — **albo** identyfikator Twojej grupy powiadomień (rozgłasza do wszystkich integracji w grupie). - integration\_id — **albo** identyfikator pojedynczej Twojej integracji. **Reguła XOR:** każdy krok musi wskazywać **dokładnie jeden** z celów — notification\_group\_id LUB integration\_id. Egzekwują to dwie warstwy walidacji: - Przypadek *brak celu* (żaden z dwóch) — reguła required\_without na obu polach zwraca 422. - Przypadek *oba cele naraz* — dodatkowy hook withValidator dokłada błąd do klucza steps.{index} i zwraca 422 z komunikatem, że krok ma wskazywać jeden cel, nie oba. Cel każdego kroku musi należeć do właściciela tokenu. Regułą Rule::exists(...)-\>where('user\_id', ...) obcy identyfikator grupy lub integracji również zwraca 422 (a nie 404) — dzięki temu eskalacja nie może przejść przez poświadczenia innego najemcy. ### Pozycja i kolejność Pole position nie jest przyjmowane w żądaniu — **kolejność w tablicy** steps staje się 0-based position (pierwszy element = 0, drugi = 1, …). To ta kolejność wyznacza łańcuch eskalacji. W odpowiedzi kroki są zawsze zwracane posortowane po position. ### Kształt odpowiedzi Zasób EscalationPolicyResource zwraca politykę z zagnieżdżonymi krokami: { "data": { "id": 42, "name": "Krytyczne API produkcyjne", "steps": \[ { "id": 101, "position": 0, "delay\_minutes": 0, "notification\_group\_id": 7, "integration\_id": null }, { "id": 102, "position": 1, "delay\_minutes": 15, "notification\_group\_id": null, "integration\_id": 3 } \], "steps\_count": 2, "created\_at": "2026-07-15T09:00:00+00:00", "updated\_at": "2026-07-15T09:00:00+00:00" } } W każdym kroku dokładnie jedno z pól notification\_group\_id / integration\_id jest wypełnione, drugie to null. Pole steps\_count pojawia się, gdy kontroler doliczył relację. ### GET /escalation-policies — parametry listy Obsługiwane parametry zapytania: search (fraza w nazwie, max 255), sort (whitelista: name, created\_at), direction (asc / desc), per\_page (1–100, domyślnie 20), page. Domyślne sortowanie: alfabetycznie po name. curl -s "https://app.nodea.io/api/v1/escalation-policies?search=API&sort=name&per\_page=20" \\ -H "Authorization: Bearer $TOKEN" \\ -H "Accept: application/json" ### POST /escalation-policies — utworzenie z krokami curl -s -X POST "https://app.nodea.io/api/v1/escalation-policies" \\ -H "Authorization: Bearer $TOKEN" \\ -H "Content-Type: application/json" \\ -H "Accept: application/json" \\ -d '{ "name": "Krytyczne API produkcyjne", "steps": \[ { "delay\_minutes": 0, "notification\_group\_id": 7 }, { "delay\_minutes": 15, "integration\_id": 3 } \] }' Pierwszy krok (pozycja 0) rozgłasza natychmiast do grupy 7; drugi (pozycja 1) po 15 minutach uderza w integrację 3. Odpowiedź: 201 Created z pełnym zasobem. ### PATCH /escalation-policies/{id} — aktualizacja Aktualizacja jest częściowa: name i steps są opcjonalne. Nazwa zmienia się tylko, gdy wysłano klucz name. Lista steps ma semantykę **zastąpienia całości** — kontroler usuwa dotychczasowe kroki i odtwarza je z przesłanej tablicy w jej kolejności, ale **tylko wtedy**, gdy klucz steps był obecny. Pominięcie steps zachowuje istniejący łańcuch. # Zmiana samej nazwy (kroki bez zmian) curl -s -X PATCH "https://app.nodea.io/api/v1/escalation-policies/42" \\ -H "Authorization: Bearer $TOKEN" \\ -H "Content-Type: application/json" \\ -d '{ "name": "Krytyczne API — nowa nazwa" }' ### DELETE /escalation-policies/{id} Trwałe usunięcie polityki i jej kroków, zwraca 204 No Content. Strony przypięte do polityki nie blokują usunięcia — ich klucz websites.escalation\_policy\_id jest zerowany przez bazę (nullOnDelete) i wracają do domyślnego zachowania „powiadom wszystkie kanały przy pierwszej awarii". curl -s -X DELETE "https://app.nodea.io/api/v1/escalation-policies/42" \\ -H "Authorization: Bearer $TOKEN" ### Kody błędów KodZnaczenie401Brak lub nieważny token Bearer.403Token bez wymaganego scope'u (alerting:read / write / delete) lub wyłączony moduł websites.404Polityka nie istnieje lub należy do innego użytkownika.422Błąd walidacji: brak name/steps, delay\_minutes poza 0–1440, naruszenie reguły XOR (żaden lub oba cele), albo cel spoza własnych grup/integracji. ## MCP Te same operacje udostępnia 5 narzędzi MCP. Egzekwują identyczne scope'y i wymagają modułu websites. W narzędziach identyfikatory polityk są przekazywane jako łańcuch znaków. Narzędzie usuwające jest oznaczone jako *destrukcyjne* i wymaga jawnego confirm: true. NazwaScopeTrybOpisescalation-policies-listalerting:readtylko odczytPaginowana lista polityk z krokami; parametry search, page, per\_page (max 50).escalation-policy-getalerting:readtylko odczytJedna polityka z krokami po id; dokłada nazwy grup i integracji.escalation-policy-createalerting:writezapisUtworzenie polityki z name i steps (kolejność = kolejność eskalacji).escalation-policy-updatealerting:writezapis (idempotentny)Aktualizacja name i/lub steps; podane steps zastępują cały łańcuch.escalation-policy-deletealerting:deletedestrukcyjnyTrwałe usunięcie; wymaga confirm: true. ### Przekazywanie kroków W narzędziach escalation-policy-create i escalation-policy-update parametr steps to tablica obiektów o polach delay\_minutes (0–1440), notification\_group\_id oraz integration\_id — z tą samą regułą XOR (dokładnie jeden cel na krok). Kolejność elementów staje się position. Cele spoza własnych grup/integracji są odrzucane (jeden obcy identyfikator przerywa całą operację). ### tools/call — utworzenie { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "escalation-policy-create", "arguments": { "name": "Krytyczne API produkcyjne", "steps": \[ { "delay\_minutes": 0, "notification\_group\_id": 7 }, { "delay\_minutes": 15, "integration\_id": 3 } \] } } } ### tools/call — usunięcie (z potwierdzeniem) { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "escalation-policy-delete", "arguments": { "id": "42", "confirm": true } } } Bez confirm: true narzędzie zwraca błąd „Deletion requires confirm: true." i nie kasuje niczego. Po sukcesie zwraca { "deleted": true, "id": "42" }. Narzędzia zwracają dane w formie ustrukturyzowanej — polityka z krokami w kolejności pozycji, wraz z nazwami grup (notification\_group\_name) i integracji (integration\_name). ## Powiązane - [Grupy powiadomień — API v1 i narzędzia MCP | Nodea](https://nodea.pl/pl/dokumentacja-api/notification-groups) - [Integracje powiadomień — API v1 i MCP | Nodea](https://nodea.pl/pl/dokumentacja-api/integrations) --- Wersje językowe: [en](https://nodea.io/en/api-docs/escalation-policies.md) Spis treści witryny: [llms.txt](https://nodea.pl/pl/llms.txt)