Websites — API v1 i MCP | Dokumentacja API Nodea

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 <token>. 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 = wyłącznie właściciel. 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żka	Scope	Opis
GET	/api/v1/websites	monitoring:read	Lista stron (własne + zaakceptowane udziały), paginowana.
GET	/api/v1/websites/{website}	monitoring:read	Szczegóły strony wraz z testami; `meta.can_manage`.
GET	/api/v1/websites/{website}/runs	monitoring:read	Historia uruchomień testów (TestRun), najnowsze pierwsze.
GET	/api/v1/websites/{website}/uptime	monitoring:read	Miesięczne agregaty uptime z `website_uptimes`.
GET	/api/v1/websites/{website}/maintenance-windows	monitoring:read	Lista okien serwisowych strony.
POST	/api/v1/websites	monitoring:write	Utworzenie strony z zestawem testów. Zwraca `201`.
PUT/PATCH	/api/v1/websites/{website}	monitoring:write	Aktualizacja nazwy/URL, upsert testów, sync grup powiadomień i wykluczonych run-serwerów.
POST	/api/v1/websites/{website}/run	monitoring:write	Ręczne uruchomienie sond (HEALTH_CHECK/SSL/WHOIS). `202`/`422`/`503`.
POST	/api/v1/websites/{website}/pause	monitoring:write	Idempotentna pauza (ustawia `paused_at`).
POST	/api/v1/websites/{website}/resume	monitoring:write	Idempotentne wznowienie (czyści `paused_at`).
POST	/api/v1/websites/{website}/mute	monitoring:write	Przełącznik `paused_at` null↔now (wycisza powiadomienia).
POST	/api/v1/websites/{website}/clone	monitoring:write	Klon strony dla użytkownika tokenu. Zwraca `201`.
POST	/api/v1/websites/{website}/maintenance-windows	monitoring:write	Utworzenie okna serwisowego. Zwraca `201`.
DELETE	/api/v1/websites/{website}/maintenance-windows/{maintenanceWindow}	monitoring:write	Usunięcie okna serwisowego (scoped binding). Zwraca `204`.
DELETE	/api/v1/websites/{website}	monitoring:delete	Trwał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.

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ędzie	Scope	Typ	Opis
websites-list	monitoring:read	read-only	Lista stron; filtry `search`, `status` (paused/healthy/unhealthy), `page`, `per_page` (max 50).
website-get	monitoring:read	read-only	Szczegóły strony wraz z testami. Param: `id`.
website-create	monitoring:write	zapis	Utworzenie strony; `name`, `url`, `tests[]` (type/interval/parameters, min 1).
website-update	monitoring:write	idempotentne	Aktualizacja `name`/`url` + upsert `tests[]`. Tylko właściciel.
website-delete	monitoring:delete	destrukcyjne	Trwałe usunięcie; wymaga `confirm: true`.
website-run-now	monitoring:write	zapis	Dispatch sond; opcjonalny `test_type`. Zwraca `dispatched`/`skipped`.
website-set-paused	monitoring:write	idempotentne	Pauza/wznowienie przez `paused: true\|false` (nie toggle).
website-runs	monitoring:read	read-only	Historia uruchomień; `test_type`, `page`, `per_page` (max 50).
website-uptime	monitoring:read	read-only	Miesięczny uptime; `months` (domyślnie 12, max 60).
website-maintenance-windows	monitoring:read	read-only	Lista okien serwisowych z flagą `active_now`.
website-maintenance-window-create	monitoring:write	zapis	Utworzenie okna; `starts_at`/`ends_at` (wall-clock w `timezone`), `recurrence_type`, `weekdays`.
website-maintenance-window-delete	monitoring:write	destrukcyjne (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 }
  }
}

Websites — API v1 i MCP | Dokumentacja Nodea