--- title: "Websites — API v1 i MCP | Dokumentacja Nodea" description: "Pełny reference modułu Websites: endpointy REST API v1 (CRUD, run/pause/resume/mute/clone, runs, uptime, okna serwisowe), zakresy monitoring:*, narzędzia MCP i przykłady curl oraz JSON-RPC." url: "https://nodea.pl/pl/dokumentacja-api/websites" lang: "pl" updated: "2026-07-16" --- # Websites — API v1 i MCP | Dokumentacja Nodea > Reference modułu Websites — endpointy API v1 (CRUD, akcje run/pause/resume/mute/clone, runs, uptime, okna serwisowe), zakresy monitoring:read/write/delete, narzędzia MCP i przykłady. Moduł **Websites** obejmuje pełną obsługę monitorowanych stron WWW: listowanie, tworzenie, edycję, usuwanie oraz akcje operacyjne (run now, pauza, wznowienie, wyciszenie, klonowanie), a także historię uruchomień testów, statystyki uptime i okna serwisowe. Dokument opisuje warstwę REST API v1 (/api/v1) oraz narzędzia MCP z tego modułu. ## Uwierzytelnianie i zakresy (scopes) API v1 uwierzytelnia się tokenem osobistym Passport przez nagłówek Authorization: Bearer \. Każda trasa jest chroniona zakresem odpowiadającym poziomowi operacji: - monitoring:read — listowanie i podgląd (index, show, runs, uptime, maintenance-windows). - monitoring:write — tworzenie, edycja oraz akcje niedestrukcyjne (run, pause, resume, mute, clone, tworzenie/usuwanie okna serwisowego). - monitoring:delete — trwałe usunięcie strony. Cały moduł jest dodatkowo bramkowany flagą Pennant features:websites — wyłączenie modułu ukrywa go zarówno w web UI, jak i w API. Limit zapytań: throttle:api-v1 = 240/min na użytkownika tokenu. ## Własność i widoczność (ownership) Dostęp na poziomie wiersza wymusza WebsitePolicy: **view** = właściciel lub zaakceptowany udział FOREIGN (współdzielenie), **manage** = właściciel. **Wspólna pula administratorów:** administrator Nodea z potwierdzonym 2FA (gdy wymuszanie 2FA dla adminów jest włączone) ma **manage** i **delete** na poziomie właściciela dla stron innych takich administratorów; administrator bez 2FA, były administrator i klient z udziałem FOREIGN — nie. Uprawnienie liczone jest na żywo z roli i 2FA, nie z samego wiersza udziału. Istniejący, ale niewidoczny dla tokenu identyfikator zwraca 403 (polityka), nieznany identyfikator — 404 (route model binding). Akcja run jest wyjątkiem: dostępna dla view (właściciel ORAZ zaakceptowany udział mogą wywołać ponowne sprawdzenie); pozostałe akcje stanu (pause/resume/mute/clone) wymagają manage. Parametry testów (parameters) są maskowane — hasła basic-auth, nagłówki uwierzytelniające i surowe body POST nigdy nie wracają w czystej postaci (schemat \*\*\*\*+ostatnie 4 znaki), więc nawet zaakceptowany udział nie zobaczy poświadczeń właściciela. ## API v1 — endpointy MetodaŚcieżkaScopeOpisGET/api/v1/websitesmonitoring:readLista stron (własne + zaakceptowane udziały), paginowana. GET/api/v1/websites/{website}monitoring:readSzczegóły strony wraz z testami; meta.can\_manage. GET/api/v1/websites/{website}/runsmonitoring:readHistoria uruchomień testów (TestRun), najnowsze pierwsze. GET/api/v1/websites/{website}/uptimemonitoring:readMiesięczne agregaty uptime z website\_uptimes. GET/api/v1/websites/{website}/maintenance-windowsmonitoring:readLista okien serwisowych strony. POST/api/v1/websitesmonitoring:writeUtworzenie strony z zestawem testów. Zwraca 201. PUT/PATCH/api/v1/websites/{website}monitoring:writeAktualizacja nazwy/URL, upsert testów, sync grup powiadomień i wykluczonych run-serwerów. POST/api/v1/websites/{website}/runmonitoring:writeRęczne uruchomienie sond (HEALTH\_CHECK/SSL/WHOIS). 202/422/503. POST/api/v1/websites/{website}/pausemonitoring:writeIdempotentna pauza (ustawia paused\_at). POST/api/v1/websites/{website}/resumemonitoring:writeIdempotentne wznowienie (czyści paused\_at). POST/api/v1/websites/{website}/mutemonitoring:writePrzełącznik paused\_at null↔now (wycisza powiadomienia). POST/api/v1/websites/{website}/clonemonitoring:writeKlon strony dla użytkownika tokenu. Zwraca 201. POST/api/v1/websites/{website}/maintenance-windowsmonitoring:writeUtworzenie okna serwisowego. Zwraca 201. DELETE/api/v1/websites/{website}/maintenance-windows/{maintenanceWindow}monitoring:writeUsunięcie okna serwisowego (scoped binding). Zwraca 204. DELETE/api/v1/websites/{website}monitoring:deleteTrwałe usunięcie strony (kaskada). Zwraca 204. ### GET /websites — parametry zapytania - search (string, opcjonalny, max 255) — dopasowanie po nazwie i URL. - status (enum: paused|healthy|unhealthy|skipped, opcjonalny). - sort (enum: name|url|created\_at, domyślnie created\_at). - direction (asc|desc). - per\_page (int 1–100, domyślnie 20), page (int ≥1). Odpowiedź: kolekcja WebsiteResource — pola: id, name, url, status (paused→unhealthy→skipped→healthy), paused\_at, ownership (owner|shared), tests\[\], created\_at, updated\_at. Każdy test: id, type (wartość enum), type\_name, interval, state, state\_name, parameters (zamaskowane), last\_run. ### POST/PATCH — parametry ciała - url (string, wymagany, reguła SafePublicUrl). - name (string, wymagany, max 255). - intervals (obiekt kluczowany wartością TestType; wartość: sekundy, 0–259200). - parameters (obiekt per-typ; opcjonalny — pominięcie zachowuje istniejącą konfigurację). - notificationGroupsId\[\] — muszą należeć do użytkownika tokenu (inaczej 422). - excludedRunServersId\[\] — istniejące run\_servers.id. Typy testów (backing value): 1=HEALTH\_CHECK, 2=SSL, 4=WHOIS, 16=TCP, 32=DNS, 64=PING, 128=SMTP, 256=POP3, 512=IMAP, 1024=UDP. ### GET /websites/{website}/runs — pola odpowiedzi Każdy element to TestRunResource: id, test\_id, state (wartość enum TestRunState), state\_name (stabilna nazwa maszynowa), reason, reason\_code, skip\_reason, failure\_status\_code, details, run\_server (gdy dołączony) oraz created\_at. reason\_code opisuje sondę, która **wykonała się i zawiodła** (taksonomia awarii: timeout, dns\_failure, connection\_refused, …). skip\_reason opisuje sondę, która **celowo nie została wykonana**, i przyjmuje wartości seeder\_host, ssrf\_blocked lub maintenance\_window. Oba pola wykluczają się wzajemnie. Uwaga dla integratorów: pominięcie seederowe i blokada SSRF współdzielą state = 7 oraz state\_name = "Skipped (seeder)" — zachowana jest zgodność wsteczna. Aby je rozróżnić (na przykład żeby wykryć, że monitorowanie nie działa, bo host rozwiązuje się do adresu prywatnego) trzeba czytać skip\_reason. ### Kody błędów - 401 — brak/niepoprawny token. - 403 — brak wymaganego scope lub polityki (istniejący, cudzy zasób bez dostępu). - 404 — nieznany identyfikator. - 422 — walidacja (np. brak uruchamialnego testu przy run, kod no\_runnable\_test). - 503 — brak zdrowego run-serwera do wykonania sond (kod no\_run\_server\_available). ## Przykłady — API ### Lista stron z filtrem statusu curl -s https://app.nodea.io/api/v1/websites?status=unhealthy&per\_page=10 \\ -H "Authorization: Bearer $NODEA\_TOKEN" \\ -H "Accept: application/json" ### Utworzenie strony z testem health-check co 60 s curl -s -X POST https://app.nodea.io/api/v1/websites \\ -H "Authorization: Bearer $NODEA\_TOKEN" \\ -H "Content-Type: application/json" \\ -d '{ "name": "Sklep", "url": "https://sklep.example.com", "intervals": { "1": 60 }, "parameters": { "1": { "timeout": 10, "status\_codes": "200" } } }' ### Ręczne uruchomienie sond curl -s -X POST https://app.nodea.io/api/v1/websites/{id}/run \\ -H "Authorization: Bearer $NODEA\_TOKEN" \\ -H "Content-Type: application/json" \\ -d '{ "test\_id": 123 }' ## MCP — narzędzia Narzędzia MCP dzielą model uwierzytelniania i zakresów z API v1 (Bearer + scope sprawdzany w ensureScope) oraz flagę features:websites (narzędzie na nieaktywnej fladze znika z tools/list). Identyfikatory zasobów to UUID przekazywane jako string. Brakujący i cudzy identyfikator zwracają ten sam błąd (brak enumeracji między najemcami). NarzędzieScopeTypOpiswebsites-listmonitoring:readread-onlyLista stron; filtry search, status (paused/healthy/unhealthy), page, per\_page (max 50). website-getmonitoring:readread-onlySzczegóły strony wraz z testami. Param: id. website-createmonitoring:writezapisUtworzenie strony; name, url, tests\[\] (type/interval/parameters, min 1). website-updatemonitoring:writeidempotentneAktualizacja name/url + upsert tests\[\]. Tylko właściciel. website-deletemonitoring:deletedestrukcyjneTrwałe usunięcie; wymaga confirm: true. website-run-nowmonitoring:writezapisDispatch sond; opcjonalny test\_type. Zwraca dispatched/skipped. website-set-pausedmonitoring:writeidempotentnePauza/wznowienie przez paused: true|false (nie toggle). website-runsmonitoring:readread-onlyHistoria uruchomień; test\_type, page, per\_page (max 50). website-uptimemonitoring:readread-onlyMiesięczny uptime; months (domyślnie 12, max 60). website-maintenance-windowsmonitoring:readread-onlyLista okien serwisowych z flagą active\_now. website-maintenance-window-createmonitoring:writezapisUtworzenie okna; starts\_at/ends\_at (wall-clock w timezone), recurrence\_type, weekdays. website-maintenance-window-deletemonitoring:writedestrukcyjne (adnotacja)Usunięcie okna po id. Scope pozostaje write. ### Przykład — MCP (JSON-RPC) { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "website-run-now", "arguments": { "id": "9b1f...uuid", "test\_type": 1 } } } { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "website-set-paused", "arguments": { "id": "9b1f...uuid", "paused": true } } } ## Powiązane - [Heartbeats — API v1 i MCP | Dokumentacja Nodea](https://nodea.pl/pl/dokumentacja-api/heartbeats) - [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/websites.md) Spis treści witryny: [llms.txt](https://nodea.pl/pl/llms.txt)