--- title: "Heartbeats — API v1 i MCP | Dokumentacja Nodea" description: "Reference modułu Heartbeats (monitory cron / dead-man-switch): endpointy API v1 (CRUD, pause/resume, runs), zakresy monitoring:*, maskowanie tokenu ping, narzędzia MCP i przykłady curl oraz JSON-RPC." url: "https://nodea.pl/pl/dokumentacja-api/heartbeats" lang: "pl" updated: "2026-07-16" --- # Heartbeats — API v1 i MCP | Dokumentacja Nodea > Reference modułu Heartbeats — monitory cron/dead-man-switch: endpointy API v1 (CRUD, pause/resume, runs), maskowanie tokenu ping (tylko właściciel), narzędzia MCP i przykłady. Moduł **Heartbeats** obsługuje monitory typu cron / dead-man-switch: usługa lub zadanie cron musi cyklicznie wywołać publiczny URL ping (/hb/{token}), a pominięcie terminu (interwał + grace) wywołuje alert. Dokument opisuje endpointy REST API v1 oraz narzędzia MCP tego modułu. Publiczny endpoint ping to osobna, nieuwierzytelniona trasa web i **nie** jest częścią tego API. ## Uwierzytelnianie, zakresy i flaga Bearer token Passport (Authorization: Bearer \). Zakresy: monitoring:read (index, show, runs), monitoring:write (create, update, pause, resume), monitoring:delete (usunięcie). Cały moduł bramkowany flagą features:heartbeats. ## Własność, widoczność i maskowanie tokenu Dostęp wymusza HeartbeatPolicy: **view** = właściciel lub zaakceptowany udział FOREIGN, **manage** = wyłącznie właściciel. Istniejący, niewidoczny identyfikator zwraca 403, nieznany — 404. Kluczowa zasada bezpieczeństwa: pola token oraz pochodny ping\_url są sekretem (z nich wynika URL crona klienta), więc serializują się **tylko dla właściciela** (przechodzącego politykę manage). Zaakceptowany udział widzi heartbeat, ale nigdy jego tokenu. Token generowany jest raz przy tworzeniu i jest niezmienny — update go nie regeneruje. ## API v1 — endpointy MetodaŚcieżkaScopeOpisGET/api/v1/heartbeatsmonitoring:readLista heartbeatów (własne + zaakceptowane udziały), paginowana. GET/api/v1/heartbeats/{heartbeat}monitoring:readSzczegóły; meta.can\_manage. Token tylko dla właściciela. GET/api/v1/heartbeats/{heartbeat}/runsmonitoring:readHistoria pingów/pominięć, najnowsze pierwsze. POST/api/v1/heartbeatsmonitoring:writeUtworzenie heartbeatu (generuje token). Zwraca 201. Limit planu → 402 (kod plan\_limit\_exceeded). PUT/PATCH/api/v1/heartbeats/{heartbeat}monitoring:writeAktualizacja name/interval/grace/note. Token niezmienny. POST/api/v1/heartbeats/{heartbeat}/pausemonitoring:writeIdempotentna pauza (ustawia paused\_at). POST/api/v1/heartbeats/{heartbeat}/resumemonitoring:writeIdempotentne wznowienie (czyści paused\_at). DELETE/api/v1/heartbeats/{heartbeat}monitoring:deleteTrwałe usunięcie (kaskada historii). Zwraca 204. ### GET /heartbeats — parametry zapytania - search (string, max 255) — dopasowanie po nazwie. - status (enum: active|paused). - sort (enum: name|interval\_seconds|last\_ping\_at|created\_at, domyślnie created\_at). - direction (asc|desc). - per\_page (int 1–100, domyślnie 20), page. ### POST/PATCH — parametry ciała - name (string, wymagany, max 255). - intervalSeconds (int, wymagany, 60–259200) — oczekiwany interwał pingu. - graceSeconds (int, wymagany, 0–86400) — okres karencji dodany do interwału. - note (string, opcjonalny, max 5000). - notificationGroupsId\[\] (tylko POST) — muszą należeć do użytkownika tokenu (inaczej 422). Update **nie** przyjmuje sync grup. ### Kształt odpowiedzi (HeartbeatResource) Pola: id, name, status (paused→waiting→late→ok), interval\_seconds, grace\_seconds, note, token (tylko właściciel), ping\_url (tylko właściciel), ownership (owner|shared), last\_ping\_at, deadline\_at (dopiero po pierwszym pingu), paused\_at, created\_at, updated\_at. Wpis historii (HeartbeatRunResource): id, heartbeat\_id, state, state\_name (Success = ping / Failure = pominięty termin), reason, reason\_code, created\_at. ### Kody błędów - 401 — brak/niepoprawny token; 403 — scope/polityka; 404 — nieznany id; 422 — walidacja lub cudza grupa powiadomień; 402 — przekroczony limit planu przy tworzeniu (plan\_limit\_exceeded). ## Przykłady — API ### Utworzenie heartbeatu (co 5 min, grace 60 s) curl -s -X POST https://app.nodea.io/api/v1/heartbeats \\ -H "Authorization: Bearer $NODEA\_TOKEN" \\ -H "Content-Type: application/json" \\ -d '{ "name": "Nightly backup", "intervalSeconds": 300, "graceSeconds": 60, "note": "cron 0 3 \* \* \*" }' Odpowiedź zawiera token i ping\_url — jednorazowy moment na podpięcie crona. Skrypt wywołuje potem ping\_url po każdym udanym przebiegu. ### Lista aktywnych heartbeatów curl -s "https://app.nodea.io/api/v1/heartbeats?status=active&sort=last\_ping\_at&direction=desc" \\ -H "Authorization: Bearer $NODEA\_TOKEN" ## MCP — narzędzia Ten sam model auth/scope co API v1 (ensureScope) i flaga features:heartbeats. Token i ping\_url pojawiają się w odpowiedzi tylko gdy wywołujący ma uprawnienie manage (właściciel). NarzędzieScopeTypOpisheartbeats-listmonitoring:readread-onlyLista; search, status (active/paused), page, per\_page (max 50). Bez tokenu. heartbeat-getmonitoring:readread-onlySzczegóły; token + ping\_url tylko dla właściciela. Param: id. heartbeat-createmonitoring:writezapisname, interval\_seconds (60–259200), grace\_seconds (0–86400), note. Limit planu → błąd. Zwraca token+ping\_url. heartbeat-updatemonitoring:writeidempotentneCzęściowa aktualizacja name/interval/grace/note. Tylko właściciel. Token niezmienny. heartbeat-set-pausedmonitoring:writeidempotentnePauza/wznowienie przez paused: true|false. heartbeat-deletemonitoring:deletedestrukcyjneTrwałe usunięcie; wymaga confirm: true. heartbeat-runsmonitoring:readread-onlyHistoria pingów/pominięć; page, per\_page (max 50). ### Przykład — MCP (JSON-RPC) { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "heartbeat-create", "arguments": { "name": "Nightly backup", "interval\_seconds": 300, "grace\_seconds": 60, "note": "cron 0 3 \* \* \*" } } } { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "heartbeat-set-paused", "arguments": { "id": "3af0...uuid", "paused": false } } } ## Powiązane - [Websites — API v1 i MCP | Dokumentacja Nodea](https://nodea.pl/pl/dokumentacja-api/websites) - [Reports (SSL / WHOIS) — API v1 i MCP | Dokumentacja Nodea](https://nodea.pl/pl/dokumentacja-api/reports) - [Status Pages — API v1 i MCP | Dokumentacja Nodea](https://nodea.pl/pl/dokumentacja-api/status-pages) --- Wersje językowe: [en](https://nodea.io/en/api-docs/heartbeats.md) Spis treści witryny: [llms.txt](https://nodea.pl/pl/llms.txt)