Reports (SSL / WHOIS) — API v1 i MCP | Dokumentacja Nodea

Moduł Reports udostępnia dwa raporty terminów ważności liczone po stronach WWW użytkownika (własne + zaakceptowane udziały): SSL (certyfikaty) i WHOIS (rejestracja domen). Każdy wiersz powstaje z testu SSL/WHOIS strony i szczegółów (details) jego ostatniego uruchomienia (payload zadania SSLJob/WhoisJob). To raporty tylko do odczytu — nie ma osobnego modelu, dane są projekcją z ostatnich testów.

Uwierzytelnianie, zakresy i flagi

Bearer token Passport. Oba endpointy wymagają zakresu monitoring:read. Bramkowanie flagami per raport: /reports/ssl → features:report_ssl, /reports/whois → features:report_whois. Zbiór jest ograniczony limitem planu (kilkaset testów na użytkownika), więc filtrowanie i sortowanie odbywa się w pamięci.

API v1 — endpointy

Metoda	Ścieżka	Scope	Opis
GET	/api/v1/reports/ssl	monitoring:read	Raport wygasania certyfikatów SSL, paginowany.
GET	/api/v1/reports/whois	monitoring:read	Raport wygasania rejestracji domen (WHOIS), paginowany.

Parametry zapytania (wspólne)

• search (string, max 255) — po nazwie i URL strony.
• status (enum: valid|invalid|unknown) — filtr ważności (tri-state is_valid).
• expiry (enum: expired|lt7|lt30|lt90|valid) — okno czasowe do wygaśnięcia.
• sort — whitelist zależny od raportu (patrz niżej), domyślnie expiration_date; direction (asc|desc).
• per_page (int 1–100, domyślnie 25), page.

Whitelist sortowania SSL: is_valid, website, days, expiration_date, last_run, issuer, organization. WHOIS: is_valid, website, creation_date, expiration_date, days, last_run. Wartość spoza whitelisty → 422.

Kształt odpowiedzi

SSL (SslReportResource): test_id, website ({id,name,url}), valid (bool|null), issuer, organization, valid_from, valid_to (data wygaśnięcia), days_left (int; ujemny po wygaśnięciu), last_run_at.

WHOIS (WhoisReportResource): test_id, website, valid (najczęściej null — WHOIS nie klasyfikuje ważności jak SSL), registrar, creation_date, expiration_date, days_left, last_run_at.

Kody błędów

• 401 — brak/niepoprawny token; 403 — brak scope lub nieaktywna flaga raportu; 422 — niepoprawna wartość sort/status/expiry.

Przykłady — API

Certyfikaty SSL wygasające w ciągu 30 dni

curl -s "https://app.nodea.io/api/v1/reports/ssl?expiry=lt30&sort=days&direction=asc" \
  -H "Authorization: Bearer $NODEA_TOKEN" \
  -H "Accept: application/json"

Domeny z nieprawidłowym/nieznanym WHOIS

curl -s "https://app.nodea.io/api/v1/reports/whois?status=invalid" \
  -H "Authorization: Bearer $NODEA_TOKEN"

MCP — narzędzia

Dwa narzędzia read-only, ten sam scope monitoring:read i flagi per raport. W przeciwieństwie do API filtr okna to pojedynczy parametr expiring_within_days (wygasłe wliczane), a wynik ograniczany jest przez limit (bez paginacji stronowej). Sortowanie: zawsze rosnąco po dacie wygaśnięcia (najbliższe pierwsze), rekordy bez daty na końcu.

Narzędzie	Scope	Typ	Parametry
report-ssl	monitoring:read	read-only	validity (valid/invalid/unknown), expiring_within_days (0–3650), limit (1–100, domyślnie 50).
report-whois	monitoring:read	read-only	validity, expiring_within_days, limit (jw.).

Wynik SSL (per wiersz): test_id, website_id, website_name, domain, valid, issuer, organization, valid_to, days_left, last_run + meta (total, limit). WHOIS: test_id, website_id, website_name, domain, valid, registrar, creation_date, expiration_date, days_left, last_run + meta.

Przykład — MCP (JSON-RPC)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "report-ssl",
    "arguments": { "expiring_within_days": 30, "limit": 50 }
  }
}

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "report-whois",
    "arguments": { "validity": "invalid" }
  }
}