API Reference

Authentication

Every request carries the key as a bearer token. There is no API-key header, no query-string token, and no organization-selector header — the key already names exactly one organization, and that is the only tenant a request against it can ever touch.

Base URL:   https://api.nivaronix.com/api/v1
Header:     Authorization: Bearer nvx_...

Example:

curl -H "Authorization: Bearer nvx_..." \
  https://api.nivaronix.com/api/v1/assets

An unknown token, a revoked token, an expired token, and a malformed header all return the same 401 with the same body — deliberately: distinguishing them would let a caller probe which tokens exist.

Getting a key

From the dashboard: Settings → API keys → Create key → choose a name and scopes. The full token is shown exactly once, at creation — copy it before leaving the page. Nivaronix stores only a hash of it afterward and cannot show it to you again; a lost key has to be rotated.

Key limits by plan:

• Free / Starter — API access not included.
• Pro — up to 2 active keys.
• Studio — up to 5 active keys.
• Scale — up to 20 active keys.

Revoked and expired keys are kept as a record and do not count against that limit.

Scopes

Each key carries only the scopes it was created with — there is no implicit "read everything" grant. A read scope needs only organization membership to issue; a write scope needs the matching write permission in the org (the same permission that gates it in the dashboard itself).

protection:read and incidents:write can be granted to a key but do not yet authorize any endpoint below — no route currently reads either scope. Requesting a remedy execution or approval via API key is deliberately not offered at all: a long-lived bearer token is the wrong instrument for an action that changes how your production traffic is handled, and approval is meant to be a human checkpoint.

Pagination & responses

List endpoints take limit/offset query parameters (defaults and maximums vary by endpoint, noted below) and return the matching page alongside the true total count — never a silently truncated list.

{
  "assets": [ … ],
  "total": 47,
  "limit": 25,
  "offset": 0
}

Errors & rate limits

Errors are a JSON body with a single detail field describing what went wrong.

{ "detail": "Asset not found" }

• 401 — missing, invalid, revoked or expired key.
• 403 — the key lacks the scope this route requires, or your plan no longer includes API access.
• 404 — the resource doesn't exist, or belongs to another organization (the two are indistinguishable on purpose).
• 409 — a conflicting resource already exists (e.g. a duplicate asset domain).
• 402 — a plan quota (assets, monitors, reports/month, verified scans/month) is exhausted; the body names the limit, current usage and the plan that raises it.
• 422 — the request body failed validation.
• 429 — rate limited. The same limiter session-authenticated traffic uses; back off and retry.

If your organization's plan drops API access after keys already exist, requests get a grace period rather than an immediate cutoff: responses carry Deprecation/Sunset headers (RFC 8594) and a Warning header naming the date access actually ends, so an integration can find out from its own response headers rather than only from the dashboard.

Assets

{
  "domain": "example.com",
  "name": "Example Co",
  "asset_type": "domain",
  "description": null,
  "tags": []
}

{
  "id": "…",
  "name": "Example Co",
  "domain": "example.com",
  "status": "healthy",
  "health_score": 94,
  "is_verified": true,
  "client_id": null,
  "description": null,
  "created_at": "2026-08-17T14:33:58Z",
  "updated_at": "2026-08-19T05:14:04Z"
}

Scans

Monitors

{
  "asset_id": "…",
  "monitor_type": "http",
  "frequency": null,
  "configuration": {}
}

{
  "frequency": 300,
  "configuration": { "record_type": "A" }
}

Findings, incidents & reports

{
  "asset_id": "…",
  "report_type": "security_report",
  "report_format": "pdf"
}

Clients

The agency grouping primitive — Organization → Client → Asset. A client has no plan of its own; entitlements are always evaluated against the organization.

{
  "name": "Acme Retail",
  "email": "ops@acme.example"
}