Nopase integrations — getting started

The differential API is how subscribers integrate differential monitoring into their own systems: SIEM, SOAR, ticketing, dashboards, scripts or custom applications. Baseline data (domains, scans, findings, infrastructure) is readable with a token on every registered account. Differentials and their events require active differential monitoring when read with a token; the signed-in dashboard always keeps showing your saved results.

Create an API key

1. Create a read-only API key

Sign in and open Integrations. Click View my JSON to see your real differential immediately, then Create personal token for external tools. The default token reads your own saved results and expires after 90 days. Scopes and expiry can be changed under Advanced token options. Save the displayed secret once in your own secret store. Rotation revokes the old credential immediately. Revocation, suspension and forced password rotation stop key access. No key can launch scans or change billing.

Send the key in an Authorization header over HTTPS. Never put it in a URL, browser source, logs or Git.

curl --fail-with-body 'https://YOUR_NOPASE_HOST/api/v1/differentials?limit=25' \
  -H 'Authorization: Bearer YOUR_NOPASE_API_KEY'

The browser can open the same JSON using its sign-in session; an explicit invalid bearer token is always rejected, even when signed in. If you have no completed comparison, the response contains data: []. Verify a domain, complete the free baseline and run the first genuine differential, then call the same endpoint. Open a scan using its id at /api/v1/scans/SCAN_ID.

2. Endpoint reference

All timestamps are UTC ISO-8601. Stable IDs refer to persisted records. With a token, differentials and events need active differential monitoring and return only the domains your plan covers; every other endpoint has no payment check. API version: 1.0.

GET /api/v1/domains · domains:read: Your domains and current monitoring status.
GET /api/v1/scans · scans:read: Scan jobs, including incomplete and failed jobs.
GET /api/v1/findings · findings:read: Findings in snapshotId, or your latest snapshot. Cursor pins the snapshot. Optional severity filter.
GET /api/v1/differentials · differentials:read: Differential history: real comparisons between complete snapshots of the domains your differential monitoring plan covers, oldest first. Filters: domainId, differentialId, severity (info|low|medium|high|critical, the highest change severity), category (dns, subdomains, ports, services, httpHeaders, tls, technologies, findings, observations: at least one change in it), since and until (ISO 8601, on computedAt; since inclusive, until exclusive). GET /api/v1/differentials/latest returns the most recent one (same filters), or null. With an API token, requires active differential monitoring and returns only the domains your plan covers (403 subscription_required otherwise); the signed-in dashboard keeps showing saved results.
GET /api/v1/events · events:read: One canonical diff.created event per stored differential, including no-change comparisons. Same filters and subscription requirement as differentials; format=ndjson streams them.
GET /api/v1/technologies · findings:read: Technology inventory observed in snapshotId (default: your latest snapshot): product, version, whether the version was observed or inferred, evidence source, collection method and confidence.
GET /api/v1/vulnerabilities · findings:read: CVE exposure assessments for your observed technologies. Severity (advisory) and certainty (evidence) are separate. origin distinguishes BASELINE, DIFFERENTIAL and INTELLIGENCE_UPDATE (new advisory, no infrastructure change). With snapshotId, returns a read-only point-in-time assessment of that stored snapshot.
GET /api/v1/intelligence · findings:read: Intelligence update events (new CVE, fix, range or exploitation status) that affected your stored evidence. Never counted as infrastructure changes.
GET /api/v1/hypotheses · findings:read: Experimental, clearly labelled risk hypotheses from passive evidence. Not confirmed vulnerabilities and not counted in finding totals.
GET /api/v1/infrastructure · scans:read: The canonical intelligence dataset of one stored snapshot (domainId, or snapshotId; default: the latest complete snapshot): hosts, addresses, DNS records, services, HTTP responses and security headers, TLS certificates, technologies, authentication interfaces, findings, exposure assessments, coverage limitations and provenance. The Intelligence Center and its JSON, CSV and PDF exports (GET /api/v1/infrastructure/export?format=json|csv|pdf) are produced from this exact dataset. Reading it never starts a scan.
GET /api/v1/scans/{id} · scans:read: Deterministic scan evidence, including preserved incomplete results. Evidence is null before a snapshot exists.
GET /api/v1/health: Any valid read key; checks the database and returns no infrastructure secrets.
GET /api/v1/infrastructure/export?format=json|csv|pdf · scans:read: Downloads of the infrastructure dataset for one snapshot (domainId or snapshotId): the JSON file is the exact /api/v1/infrastructure document, the CSV archive holds documented tables (hosts, IP addresses, DNS, services, HTTP, TLS, technologies, authentication interfaces, findings, coverage) with a README, and the PDF is a report rendered from the same dataset. Free, read-only, never starts a scan.

Download OpenAPI 3.1 — response schemas generated from the live validators

Differential API

Each differential compares two complete snapshots of one domain: its identifiers, computedAt, the highest change severity, added, removed and changed counts, the categorised changes (dns, subdomains, ports, services, httpHeaders, tls, technologies, findings, observations), the AI analysis when one exists and its report. Responses keep the same JSON contract for existing consumers.

# The most recent differential of one domain (data is null when none exists yet)
curl --fail-with-body 'https://YOUR_NOPASE_HOST/api/v1/differentials/latest?domainId=DOMAIN_ID' \
  -H 'Authorization: Bearer YOUR_NOPASE_API_KEY'

# History: high-severity differentials with TLS changes since 1 October, 100 per page
curl --fail-with-body 'https://YOUR_NOPASE_HOST/api/v1/differentials?severity=high&category=tls&since=2026-10-01&limit=100' \
  -H 'Authorization: Bearer YOUR_NOPASE_API_KEY'

# Next page: repeat the same query with cursor=<pagination.nextCursor>

A token without active differential monitoring receives 403 with error.code subscription_required; so does a domainId outside your plan.

Pagination, filters and errors

Use limit (default 25, maximum 100) and the returned pagination.nextCursor. Lists are ordered by stable id ascending. Keep filters unchanged between pages. domainId filters every list and must belong to you. differentials and events also accept differentialId to select one exact comparison, severity (info, low, medium, high, critical: the highest change severity), category (at least one change in it) and since/until (ISO 8601 on computedAt; since inclusive, until exclusive). Scans also accept status. Findings use snapshotId (default: your latest snapshot) and optional lowercase severity; the cursor pins that snapshot.

Shared limit: 60 requests per minute per account, enforced in PostgreSQL across keys and processes. A process-wide pre-authentication limit also protects credential verification. HTTP 429 includes Retry-After in seconds. Wait before retrying.

200 with an empty data array means no matching results. 401 means invalid, expired or revoked credentials; 403 means a missing read scope, or subscription_required for differential data without active differential monitoring; 404 means no matching authorized resource; 422 means invalid filters; 503 means service failure. Errors contain apiVersion and error.code, error.message, error.requestId. Record the requestId for support, excluding your credential and sensitive evidence.

JSON and NDJSON export

The JSON endpoints are portable exports. For one event per line, use events?format=ndjson. Follow X-Next-Cursor until absent; JSON pages use pagination.nextCursor. Reports use permission-checked relative links; resolve them against your Nopase origin.

curl --fail-with-body 'https://YOUR_NOPASE_HOST/api/v1/events?format=ndjson&limit=100' \
  -H 'Authorization: Bearer YOUR_NOPASE_API_KEY' > nopase-events.ndjson

Signed HTTPS webhooks

Configure a public HTTPS receiver with a trusted certificate. Private, loopback, reserved and metadata IPs are rejected, including DNS resolutions. The checked IP is pinned for the connection; redirects are not followed. Delivery has an overall 10-second network deadline (including DNS); lower configured timeouts still apply. No response body is stored.

The server generates a 256-bit signing secret when omitted. Save it at creation; rotate from the destination panel if lost. The connection test sends connector.test, never a fabricated finding. Production events are diff.created, including genuine no-change comparisons, using the same stored evidence as the JSON API, and vulnerability.exposure_detected / vulnerability.exposure_resolved. Scan lifecycle events (scan.started, scan.completed, scan.degraded, scan.failed, scan.cancelled) are sent only to destinations that select them; they are relayed from the scan's recorded state within about a minute.

Verify X-NoPase-Signature-V2 = sha256=HMAC-SHA256(secret, timestamp + "." + raw body), with X-NoPase-Timestamp expressed as Unix seconds. Reject timestamps more than five minutes from your clock and compare signatures in constant time. The older X-NoPase-Signature over raw body remains for existing receivers. Prefer v2 for replay protection. Idempotency-Key equals event_id; store processed IDs and acknowledge duplicate IDs with 2xx.

Tested Node.js receiver example: set NOPASE_WEBHOOK_SECRET locally, then run node --experimental-strip-types webhook-receiver.ts. Place its loopback listener behind your public HTTPS reverse proxy. The example verifies signatures and bounds duplicate handling in memory; connect the callback to your durable ingestion before production use.

Respond 2xx only after accepting the event durably. Delivery is at least once: a crash after receiver acceptance can replay the same ID. Recoverable network errors, 408, 429 and 5xx retry with bounded exponential backoff (six attempts). Other HTTP 3xx/4xx and unsafe destinations stop automatically. Delivery state, errors and next attempt are visible from the app. Retry due deliveries without resetting limits. Events are dispatched every minute while the Node server is running; no external queue is required. Historical data remains retrievable through the API even if no destination was configured when it was created.

Compatibility and external costs

Nopase’s REST API, webhook, JSON/NDJSON and OpenAPI integrations have no proprietary SDK or service dependency. These are Nopase implementations of open protocols. External receiver hosting, infrastructure and services may cost money.

Existing Splunk HEC and Elasticsearch adapters remain optional Beta integrations. Splunk is proprietary and may require an external license; it is never a Nopase dependency. Elasticsearch licensing depends on the deployment and version. Neither destination has been validated against a live product instance in this change.

OpenSearch (Apache-2.0), Wazuh, Grafana, n8n and Syslog/CEF are not advertised as available destination connectors. Their native ingestion and licensing need individual validation first. n8n uses a Sustainable Use License rather than an OSI open-source license. No upstream code, commercial SDK or unverified destination recipe is bundled.

Upstream references: OpenSearch, Wazuh log collection, n8n license, OpenAPI.

Troubleshooting

Empty results: complete a scan or choose the correct snapshotId/domainId. Missing scope: rotate with the required read scopes. Expired or revoked key: create a new key. A failed destination test: check DNS, public HTTPS, certificate chain, receiver authentication and returned HTTP status. A failed scan does not erase earlier results. An unavailable NVIDIA assessment does not change deterministic evidence. Missing new events: check the domain’s monitoring status, scan completion and connector filters; installing a connector does not enable paid recurring monitoring.