Reports (SSL / WHOIS) — API v1 and MCP | Nodea Documentation

The Reports module exposes two expiry reports computed over the user's websites (owned + accepted shares): SSL (certificates) and WHOIS (domain registration). Each row is built from a website's SSL/WHOIS test and the details of its latest run (the SSLJob/WhoisJob payload). These are read-only reports — there is no dedicated model; the data is projected from the latest tests.

Authentication, scopes and flags

Passport Bearer token. Both endpoints require the monitoring:read scope. Per-report flag gating: /reports/ssl → features:report_ssl, /reports/whois → features:report_whois. The dataset is bounded by plan limits (a few hundred tests per user), so filtering and sorting happen in memory.

API v1 — endpoints

Method	Path	Scope	Description
GET	/api/v1/reports/ssl	monitoring:read	SSL certificate expiry report, paginated.
GET	/api/v1/reports/whois	monitoring:read	Domain registration (WHOIS) expiry report, paginated.

Query parameters (shared)

• search (string, max 255) — by website name and URL.
• status (enum: valid|invalid|unknown) — validity filter (tri-state is_valid).
• expiry (enum: expired|lt7|lt30|lt90|valid) — time window to expiration.
• sort — per-report whitelist (see below), default expiration_date; direction (asc|desc).
• per_page (int 1–100, default 25), page.

SSL sort whitelist: is_valid, website, days, expiration_date, last_run, issuer, organization. WHOIS: is_valid, website, creation_date, expiration_date, days, last_run. A value outside the whitelist → 422.

Response shape

SSL (SslReportResource): test_id, website ({id,name,url}), valid (bool|null), issuer, organization, valid_from, valid_to (expiration date), days_left (int; negative once expired), last_run_at.

WHOIS (WhoisReportResource): test_id, website, valid (usually null — WHOIS does not classify validity the way SSL does), registrar, creation_date, expiration_date, days_left, last_run_at.

Error codes

• 401 — missing/invalid token; 403 — missing scope or inactive report flag; 422 — invalid sort/status/expiry value.

Examples — API

SSL certificates expiring within 30 days

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"

Domains with invalid/unknown WHOIS

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

MCP — tools

Two read-only tools, the same monitoring:read scope and per-report flags. Unlike the API, the window filter is a single expiring_within_days parameter (expired rows included), and the result is capped by limit (no page-based pagination). Sorting: always ascending by expiration date (soonest first), rows without a date last.

Tool	Scope	Type	Parameters
report-ssl	monitoring:read	read-only	validity (valid/invalid/unknown), expiring_within_days (0–3650), limit (1–100, default 50).
report-whois	monitoring:read	read-only	validity, expiring_within_days, limit (as above).

SSL output (per row): 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.

Example — 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" }
  }
}