---
title: "Reports (SSL / WHOIS) — API v1 and MCP | Nodea Documentation"
description: "Reference for the SSL and WHOIS reports: API v1 endpoints with status/expiry/sort filters, the monitoring:read scope, report_ssl/report_whois flags, the report-ssl/report-whois MCP tools and examples."
url: "https://nodea.io/en/api-docs/reports"
lang: "en"
updated: "2026-07-16"
---

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

> Reports module reference — SSL and WHOIS expiry reports: API v1 endpoints (status/expiry/sort filters), the monitoring:read scope, MCP tools and examples.

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

MethodPathScopeDescriptionGET/api/v1/reports/sslmonitoring:readSSL certificate expiry report, paginated. GET/api/v1/reports/whoismonitoring:readDomain 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.

ToolScopeTypeParametersreport-sslmonitoring:readread-onlyvalidity (valid/invalid/unknown), expiring\_within\_days (0–3650), limit (1–100, default 50). report-whoismonitoring:readread-onlyvalidity, 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" } } }

## Related

- [Websites — API v1 and MCP | Nodea Documentation](https://nodea.io/en/api-docs/websites)
- [Heartbeats — API v1 and MCP | Nodea Documentation](https://nodea.io/en/api-docs/heartbeats)
- [Status Pages — API v1 and MCP | Nodea Documentation](https://nodea.io/en/api-docs/status-pages)

---

Languages: [pl](https://nodea.pl/pl/dokumentacja-api/reports.md)  
Site index: [llms.txt](https://nodea.io/en/llms.txt)