Status Pages — API v1 i MCP | Dokumentacja API Nodea

Moduł Status Pages obsługuje publiczne strony statusu: publiczny widok stanu wybranych monitorowanych stron WWW pod adresem /status/{slug}. API v1 zapewnia pełny CRUD nad definicjami stron statusu. Publiczny renderer (/status/{slug}) to osobna, nieuwierzytelniona trasa web i nie jest częścią tego API.

Uwierzytelnianie, zakresy i flaga

Bearer token Passport. Zakresy: monitoring:read (index, show), monitoring:write (create, update), monitoring:delete (delete). Moduł bramkowany flagą features:websites (strony statusu jadą na tej samej fladze co strony WWW).

Własność (ownership) — brak polityki

StatusPage nie ma klasy polityki. Dostęp jest wyłącznie właścicielski — każdy wiersz jest ograniczony do user_id = użytkownik tokenu. Cudzy albo nieznany identyfikator konsekwentnie zwraca 404 (nigdy nie potwierdza istnienia zasobu innego najemcy). Dodatkowo strony przypisane do strony statusu muszą być własnością użytkownika (pivot OWNER) — sam udział FOREIGN nie wystarcza, bo strona statusu eksponuje stronę WWW publicznie. Cudzy website_id → 422 (API rzuca błąd zamiast cicho pomijać).

API v1 — endpointy

Metoda	Ścieżka	Scope	Opis
GET	/api/v1/status-pages	monitoring:read	Lista stron statusu użytkownika (z licznikiem stron WWW), paginowana.
GET	/api/v1/status-pages/{statusPage}	monitoring:read	Szczegóły z listą przypisanych stron WWW.
POST	/api/v1/status-pages	monitoring:write	Utworzenie strony statusu. Zwraca `201`.
PUT/PATCH	/api/v1/status-pages/{statusPage}	monitoring:write	Aktualizacja (częściowa) + sync stron WWW gdy podano `selectedWebsiteIds`.
DELETE	/api/v1/status-pages/{statusPage}	monitoring:delete	Trwałe usunięcie. Zwraca `204`.

GET /status-pages — parametry zapytania

per_page (int 1–100, domyślnie 20), page.

POST/PATCH — parametry ciała

title (string, wymagany, max 120).
slug (string, wymagany, max 80, regex ^[a-z0-9-]+$, unikalny; przy update wyjątek dla własnego slug).
description (string, opcjonalny, max 1000).
accent_color (wymagany, regex ^#[0-9A-Fa-f]{6}$).
logo_url (url, opcjonalny, max 500).
is_public (boolean; przy częściowym PATCH pominięcie nie zmienia widoczności).
selectedWebsiteIds[] — identyfikatory stron WWW posiadanych przez użytkownika (pivot OWNER); kolejność listy = kolejność wyświetlania (display_order).

Kształt odpowiedzi (StatusPageResource)

Pola: id, slug, title, description, accent_color, logo_url, is_public, public_url (zawsze rozwiązywalny — prywatna strona po prostu 404 dla gości), website_ids[], websites[] ({id,name}, tylko gdy relacja załadowana), websites_count, created_at, updated_at.

Kody błędów

401 — brak/niepoprawny token; 403 — brak scope lub nieaktywna flaga; 404 — nieznany lub cudzy identyfikator; 422 — walidacja (nieunikalny slug, zły kolor, cudzy/nieposiadany website_id).

Przykłady — API

Utworzenie strony statusu

curl -s -X POST https://app.nodea.io/api/v1/status-pages \
  -H "Authorization: Bearer $NODEA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Status usług",
    "slug": "status-uslug",
    "accent_color": "#50CD89",
    "is_public": true,
    "selectedWebsiteIds": ["9b1f...uuid", "7c22...uuid"]
  }'

Publikacja istniejącej strony (PATCH)

curl -s -X PATCH https://app.nodea.io/api/v1/status-pages/{id} \
  -H "Authorization: Bearer $NODEA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Status usług", "slug": "status-uslug", "accent_color": "#50CD89", "is_public": true }'

MCP — narzędzia

Ten sam model auth/scope co API v1 i flaga features:websites. Rozwiązywanie po id jest właścicielskie (brak polityki); brakujący i cudzy id zwracają ten sam błąd. W przeciwieństwie do web (który cicho pomija cudze id), narzędzia MCP odrzucają każdy website_id nienależący do użytkownika, więc sfałszowana lista nie wyeksponuje cudzej strony publicznie.

Narzędzie	Scope	Typ	Opis
status-pages-list	monitoring:read	read-only	Lista stron statusu (najnowsze pierwsze); `page`, `per_page` (max 50).
status-page-get	monitoring:read	read-only	Szczegóły z uporządkowaną listą stron WWW. Param: `id`.
status-page-create	monitoring:write	zapis	`title`, `slug`, `description`, `accent_color` (domyślnie #50CD89), `logo_url`, `is_public` (domyślnie false), `website_ids[]` (tylko posiadane).
status-page-update	monitoring:write	idempotentne	Aktualizacja częściowa; `website_ids[]` zastępuje całą listę (tylko posiadane).
status-page-delete	monitoring:delete	destrukcyjne	Trwałe usunięcie; wymaga `confirm: true`.

Wynik (status-page-*): id, slug, title, description, accent_color, logo_url, is_public, public_url, websites_count (gdy policzone), websites[] ({id,name,url,display_order,visible}, gdy załadowane), created_at, updated_at.

Przykład — MCP (JSON-RPC)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "status-page-create",
    "arguments": {
      "title": "Status usług",
      "slug": "status-uslug",
      "is_public": true,
      "website_ids": ["9b1f...uuid", "7c22...uuid"]
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "status-page-delete",
    "arguments": { "id": "5d40...uuid", "confirm": true }
  }
}

Status Pages — API v1 i MCP | Dokumentacja Nodea