API

The NNumbers WAF has a REST API documented in OpenAPI. It is the same API the Console uses: everything you do on screen can be done by a call, with the same permission and the same per-organization isolation.

Overview

Item	How it works
Style	REST, JSON body, snake_case fields
Identifiers	UUID version 7, as text
Dates and times	RFC 3339, in UTC
Documentation	OpenAPI specification published with the product
Scope	Always the organization of your session

The Console is the recommended way to start: it shows the state of each step and avoids mistakes when assembling a call. The API is for automation — creating domains in bulk, syncing the policy with your provisioning, pulling events into your SIEM.

Authentication

Authentication happens through the Console: you obtain the credential from your NNumbers Console access and use it in the calls. There is no WAF-specific username and password, and the API does not accept a credential from another organization.

The organization comes from the credential, never from the body, the query or a call header. A resource from another organization answers 404, not 403: its existence is not revealed.

Permissions

Each operation requires a permission, consistent with the Console roles:

Permission	Covers
domains.read	Reading domains, verification, state and origin
domains.manage	Creating, changing and removing domain, origin and verification
protection.manage	Activating and deactivating protection
policies.read	Reading policies, rules, exceptions and revisions
policies.manage	Creating and changing policy and rules
exceptions.manage	Creating and removing exceptions
events.read	Reading events
metrics.read	Reading overview and metrics

A call without the required permission answers a scope error, with the correlation identifier to take to support.

Pagination

Lists use a cursor:

Parameter	Value
limit	From 1 to 200; default 50
cursor	Opaque value returned in the previous response

The response carries the items and the next cursor:

{
  "items": [],
  "next_cursor": "opaque"
}

When next_cursor is null, the list ended. Do not build a cursor yourself and do not store a position by page number: the cursor is opaque and may change shape.

Idempotency

Every call that creates, changes or removes requires the Idempotency-Key header, with 1 to 128 characters.

Situation	Response
First call with the key	Operation executed
Retry with the same key and the same body	The same response as the first, flagged as replayed
Retry with the same key and a different body	Idempotency conflict
Key already expired	The key is discarded after 24 hours

Use one key per intended change, generated once and reused on retries. That is what prevents a duplicate domain when the network fails midway.

Changes also accept version control: the resource has an integer version, and the call may require the version to stay the same. If someone else changed it first, the response is a version conflict, not a silent overwrite.

Errors

The error always has the same shape:

{
  "error": {
    "code": "validation_failed",
    "message": "Readable text about what failed",
    "correlation_id": "identifier of the call"
  }
}

Code	When it happens
unauthorized	Missing or invalid credential
forbidden_scope	Valid credential without the operation permission
not_found	Resource does not exist in your organization
validation_failed	Invalid body or parameter
conflict	Conflict with the current state
version_conflict	The required version is no longer current
idempotency_conflict	Same idempotency key with a different body
hostname_unavailable	Hostname already registered by another organization
invalid_state_transition	The step is not valid in the domain current state
verification_failed	Ownership verification did not pass
origin_rejected	Origin refused by the address or port rules
policy_in_use	Policy still used by a domain
payload_too_large	Body above the API limit
rate_limited	Calls above the API limit
dependency_unavailable	Service temporarily unavailable; retry later

Keep the correlation_id of every failure: it links the call to the record on the NNumbers side without reproducing the error.

Long-running operations

Verifying, activating, deactivating, removing and applying a policy are operations that do not finish in the same response. The call answers with the resource and the current state, and you follow it through the domain state — the same states the Console shows.

Next steps

• Domains — the states the API returns.
• Events and exceptions — what to pull into your monitoring.
• Security — permissions and auditing.