The REST API
Authenticate with a scoped key, list sites, read findings, and request a crawl. The API describes itself at /api/v1/openapi.
Noverva has a versioned REST API for driving it from your own systems. It is available on plans that include API access.
Authentication
Create a key from API keys in the application. The key is shown once, because only a hash of it is stored — there is no version of "show it to me again" we could honestly offer. If you lose it, revoke it and make another.
Send it as a bearer token:
Authorization: Bearer nv_your_key_here
Keys carry scopes. A key with only read scopes cannot request a crawl. Give each integration the narrowest set it needs, so a leaked key is worth less.
What it can do
| Method | Path | Scope |
|---|---|---|
GET | /api/v1/sites | read |
GET | /api/v1/sites/{siteId}/findings | read |
POST | /api/v1/sites/{siteId}/crawl | write |
The full specification is served at /api/v1/openapi, so a client can be generated rather than hand-written.
Responses you should handle
401 — the key was not accepted. Every credential failure returns the same message deliberately: telling you a key was "revoked" rather than "unknown" would confirm that it once existed.
402 — the key is valid and your plan does not include API access. This is separate from 401 on purpose, so an integrator is not sent hunting for a credential problem that does not exist.
429 — rate limited. Limits are per plan and counted per account as well as per key, so issuing more keys does not buy more traffic. Every response carries x-ratelimit-limit and x-ratelimit-remaining so you can slow down before being refused rather than after.
Entitlements are checked on every request
Your plan is consulted when the request arrives, not when the key was created. A key made while you had API access stops working if the subscription ends — which is the point. It also means an upgrade takes effect immediately, with no need to reissue anything.
What is not here yet
Webhooks. The signing primitives and tables exist, and the dispatcher does not, so there is currently no way to be notified rather than polling. It is on the roadmap and this page will say so when it ships.