openapi: 3.1.0 info: title: Nexren Shield Customer REST API version: 1.0.0 description: "High-performance edge security, DDoS mitigation, Origin Lock, and cache control API for Nexren Shield.\n\n**Idempotency:** POST/PUT/PATCH/DELETE requests may send an `Idempotency-Key` header (1-128 characters of `[A-Za-z0-9_.:-]`). The first response for the same token, method, path and key is stored for 24 hours and replayed on retries with `Idempotent-Replayed: true`. Reusing a key with a different body returns 422; a concurrent duplicate returns 409. 5xx responses are not stored." contact: name: Nexren Shield Security Operations url: "https://shield.nexren.info" email: support@nexren.com servers: - url: "https://shield.nexren.info/api" description: Nexren Shield Production API Gateway security: - bearerAuth:[] - apiKeyAuth:[] paths: /v1/whoami: get: summary: Inspect Active API Token & Auth Status description: Returns token metadata, granted scopes, client IP, and rate limit status. tags: - Identity responses: 200: description: Token and auth details 401: description: Unauthorized /v1/identity: get: summary: Get Authenticated Identity Profile description: Returns the authenticated user profile, organization info, and active plan. tags: - Identity responses: 200: description: Identity profile details 401: description: Unauthorized /v1/sites: get: summary: List Protected Websites description: Returns list of all sites accessible to the authenticated user. tags: - Sites parameters: - name: includePending in: query schema: type: boolean description: Include sites in pending setup - name: search in: query schema: type: string description: Filter by domain keyword responses: 200: description: List of sites 401: description: Unauthorized 403: description: "Forbidden - Insufficient scope (requires sites:read)" post: summary: Create / Onboard New Site description: "Registers a new domain for edge protection. The caller must prove DNS control first: a CNAME pointing to the Shield target AND a TXT record at _nexren-challenge. carrying the caller's own verification token (both are required). Reserved test TLDs (.test, .invalid, .local) are exempt; platform admins may pass skipDnsCheck. When the domain's www/apex sibling or parent domain is registered under another account, the 201 response carries `relatedSite` (relation + hostname, never the other owner)." tags: - Sites requestBody: required: true content: application/json: schema: type: object required: - domain properties: domain: type: string example: api.example.com originUrl: type: string example: "https://198.51.100.25:443" mode: type: string enum: - Off - Monitor - Balanced - Under Attack default: Balanced enabled: type: boolean default: true responses: 201: description: Site created successfully 400: description: Bad request - invalid domain or origin 403: description: Forbidden - the hostname or its www/apex sibling belongs to a site you are only a team member of 409: description: Conflict - domain already registered 422: description: "dns_verification_required - CNAME and TXT ownership records not found for the caller's token" /v1/sites/{id}: get: summary: Get Site Configuration & Status description: Retrieves complete configuration and health status for a site. tags: - Sites parameters: - name: id in: path required: true schema: type: string responses: 200: description: Site configuration 404: description: Site not found patch: summary: Update Site Settings description: Modifies origin URL, protection mode, or enabled state for a site. tags: - Sites parameters: - name: id in: path required: true schema: type: string requestBody: content: application/json: schema: type: object properties: originUrl: type: string mode: type: string enum: - Off - Monitor - Balanced - Under Attack enabled: type: boolean responses: 200: description: Site updated 404: description: Site not found delete: summary: Delete Site description: Deletes a site and removes all edge configurations. tags: - Sites parameters: - name: id in: path required: true schema: type: string responses: 200: description: Site deleted 404: description: Site not found /v1/sites/{id}/purge-cache: post: summary: Purge Edge Cache description: "Evicts the site's edge static-asset cache (all entries, or only the given paths with every query/encoding variant; a trailing * is a prefix match). Takes effect on the edge within effectiveWithinMs (about 1 s). entries/bytes are real numbers: the cache contents in the edge's last stats report (at most ~30 s old, timestamp countsAsOf). When they are not known, entries/bytes/purgedSize are null, countsExact is false and countsUnknownReason explains why; a made-up 0 is never returned. A full-site purge happens ONLY for {\"purgeAll\": true} (without paths) or for an empty body / {}. Anything else is either a path purge or a 400 that purges nothing: invalid JSON, a null or non-object body, an unknown field (e.g. \"path\"), paths that is null, not an array, empty or only blank strings, '*' or '/*' as a path (use purgeAll:true), a non-boolean purgeAll (null included), purgeAll:true together with paths, or purgeAll:false without paths." tags: - Sites parameters: - name: id in: path required: true schema: type: string requestBody: content: application/json: schema: type: object additionalProperties: false description: Optional. An empty body or {} purges the whole site. properties: purgeAll: type: boolean description: "true purges the whole site and must not be combined with paths; false requires paths. No default: omit the field instead of sending null." paths: type: array items: type: string minItems: 1 maxItems: 100 description: "URL paths to purge, e.g. /static/app.js or /assets/* (trailing * = prefix match). Not null; '*' and '/*' are rejected (use purgeAll:true)." examples: wholeSite: summary: Purge the whole site value: purgeAll: true somePaths: summary: Purge specific paths value: paths: - /static/app.js - /assets/* responses: 200: description: Purge scheduled content: application/json: schema: type: object properties: ok: type: boolean message: type: string purgedAt: type: integer purgedSize: type: string nullable: true scope: type: string enum: - all - paths paths: type: array items: type: string entries: type: integer nullable: true description: null when unknown bytes: type: integer nullable: true description: null when unknown countsExact: type: boolean countsUnknownReason: type: string nullable: true enum: - no-edge-report - report-predates-last-purge - per-path-counts-not-reported - report-truncated - null countsAsOf: type: integer nullable: true description: Time (ms) of the report the counts describe cacheEnabled: type: boolean generation: type: integer effectiveWithinMs: type: integer 400: description: "Invalid body (nothing is purged): malformed JSON, null or non-object body, unknown field, null/non-array/empty paths, '*' or '/*' as a path, non-boolean purgeAll, purgeAll:true with paths, or purgeAll:false without paths" 404: description: Site not found /v1/sites/{id}/members: get: summary: List Site Team description: "Lists the site owner and the members this site is shared with. Each member carries `permissions` (per-area `view` / `edit` map), `role` (derived label: viewer | editor | manager when the set equals a preset, otherwise custom), username, invitedBy, createdAt and `manageable` (whether you may change/remove them). The response also returns your own `myPermissions`, `grantablePermissions`, the `permissionAreas` catalog and the `presets`. Emails are included only for callers with team:edit. Requires sites:read and the site permission team:view. Every site payload also carries `myRole` (owner | viewer | editor | manager | custom) and `myPermissions`." tags: - Sites parameters: - name: id in: path required: true schema: type: string responses: 200: description: Owner, members (with permissions), maxMembers, canManage, grantablePermissions, permissionAreas, presets 403: description: "Insufficient site permission (team:view)" 404: description: Site not found post: summary: Add Site Member description: "Shares the site with another existing Nexren Shield account, identified by its exact username or email, with a chosen permission set. Send `permissions` (per-area map, e.g. {\"analytics\":\"view\",\"security\":\"edit\"} or {\"security\":{\"view\":true,\"edit\":true}}) or a `preset` (viewer | editor | manager; `role` is accepted as an alias). Edit implies view; `edit` with an explicit `view: false`, unknown areas, unsupported levels, unmet prerequisites (visitorIps needs analytics:view, maintenanceHtml needs maintenance:edit) and an empty set are rejected with 400. Requires sites:write and team:edit. You can only grant permissions you hold yourself, and only the site owner can grant team:edit. Errors never reveal whether an account exists. Rate limited." tags: - Sites parameters: - name: id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object required: - identifier properties: identifier: type: string description: Exact username or email of an existing account permissions: type: object description: "Per-area permission map. Areas (modules): analytics (traffic & logs), visitorIps, security (WAF/DDoS/bot, mode, timed mode, WAF sensitivity, traffic profile, verification lifetime), rules (custom rules, IP lists, country/TLS, scoped WAF exceptions), access (Zero Trust), origin, ssl, cache, captcha, maintenance, maintenanceHtml, notifications (channels, owner alerts, all-my-sites scope), analysis, team. Values: none | view | edit, or {view: boolean, edit: boolean}." additionalProperties: oneOf: - type: string enum: - none - view - edit - type: object properties: view: type: boolean edit: type: boolean preset: type: string enum: - manager - editor - viewer description: "Used when permissions is omitted: viewer = view only (every module view, visitor IPs masked, no team), editor = edits security/rules/maintenance/notifications/cache/analysis, manager = full admin (every module edit except team management, which only the owner grants)" role: type: string enum: - manager - editor - viewer description: Deprecated alias of preset responses: 201: description: Member added 400: description: Invalid permissions (code invalid_permissions) 403: description: Insufficient site permission, or granting permissions beyond your own 404: description: User not found or cannot be added (generic) 409: description: Already a member, or member limit reached (the limit is checked before the account lookup, so it never reveals whether an account exists) 429: description: Too many invite attempts /v1/sites/{id}/members/{userId}: patch: summary: Change Member Permissions description: "Replaces a member's permission set (`permissions` or `preset`; `role` accepted as an alias of preset). You need team:edit; unless you are the owner, the member must hold no permission you lack and must not have team:edit, the new set must be within your own, and you cannot grant team:edit. Nobody can change their own permissions. Every change re-validates the site's credential bindings: channels whose supplier lost notifications:edit and a Zero Trust 2FA credential whose supplier lost access:edit are detached (`detached`, `warnings`). The response includes the `diff` (added / removed permission tokens), which is also written to the audit log. Requires sites:write." tags: - Sites parameters: - name: id in: path required: true schema: type: string - name: userId in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: permissions: type: object preset: type: string enum: - manager - editor - viewer role: type: string enum: - manager - editor - viewer responses: 200: description: Permissions changed 400: description: Invalid permissions 403: description: Insufficient site permission 404: description: Member not found delete: summary: Remove Member / Leave Site description: "Removes a member (needs team:edit and, unless you are the owner, the member's permissions must be within yours and exclude team:edit) or, with your own user id or `me`, leaves the site. Channels and credentials the member bound to the site are detached immediately; `review` counts the Zero Trust access rules/tunnels the member added, which stay active on the site. Requires sites:write." tags: - Sites parameters: - name: id in: path required: true schema: type: string - name: userId in: path required: true schema: type: string responses: 200: description: Member removed 403: description: Insufficient site permission 404: description: Member not found /v1/sites/{id}/origin: get: summary: Get Origin Configuration description: Retrieves origin IP/URL and Origin Lock status. tags: - Origin & Lock parameters: - name: id in: path required: true schema: type: string responses: 200: description: Origin details 404: description: Site not found put: summary: Update Origin Configuration description: Updates origin IP/URL and Origin Lock header / secret. tags: - Origin & Lock parameters: - name: id in: path required: true schema: type: string requestBody: content: application/json: schema: type: object properties: originUrl: type: string originLockEnabled: type: boolean responses: 200: description: Origin updated 404: description: Site not found /v1/sites/{id}/origin/lock/toggle: post: summary: Toggle Origin Lock description: Toggles cryptographic Origin Lock enforcement on or off for the site. tags: - Origin & Lock parameters: - name: id in: path required: true schema: type: string requestBody: content: application/json: schema: type: object required: - enabled properties: enabled: type: boolean responses: 200: description: Origin lock toggled successfully 404: description: Site not found /v1/policies/{id}: get: summary: Get Site Policy description: Retrieves protection mode and threat response rules for the site. A timed mode exposes `modeRevertTo` (the mode it will return to) and `modeRevertAt` (epoch ms); both are empty/0 for a permanent mode. Maintenance fields include `maintenanceEta` (UTC epoch ms as a string), `maintenanceContact` and `maintenanceAutoEnd`. tags: - Policies parameters: - name: id in: path required: true schema: type: string responses: 200: description: Policy details 404: description: Site not found put: summary: Update Site Policy description: "Modifies protection mode ('Off', 'Monitor', 'Balanced', 'Under Attack') and challenge settings. Send `modeDurationMinutes` with `mode` to switch temporarily: the control plane reverts to the previous mode when the duration ends (checked every 30 s; plan limits apply, e.g. it never reverts into Under Attack on a plan without it). `modeDurationMinutes: 0` (or a mode change without a duration) makes the current mode permanent and cancels a pending revert. Also accepted on PATCH. Also per-site customizations: traffic profile, verification lifetime, WAF sensitivity." tags: - Policies parameters: - name: id in: path required: true schema: type: string requestBody: content: application/json: schema: type: object properties: mode: type: string enum: - Off - Monitor - Balanced - Under Attack wafEnabled: type: boolean botProtectionEnabled: type: boolean challengeEnabled: type: boolean rateLimitEnabled: type: boolean trafficProfile: type: string enum: - web - api - webhook - realtime default: web description: "How unverified traffic is handled. 'web' serves the HTML verification page (default). 'api', 'webhook' and 'realtime' never serve HTML challenges: challenge decisions are logged and a strict per-IP rate limit applies instead (api 20, webhook 5, realtime 30 req/s; halved under attack; 429 JSON with Retry-After). WAF blocks, IP blacklist, geo blocks, Zero Trust and DDoS protections still apply. 'webhook' additionally does not treat a missing User-Agent or cookie-less POST as a bot signal." profilePaths: type: string description: "Newline-separated path patterns the traffic profile applies to (e.g. '/api/*\\n/webhook/*'). Empty = whole site. Other paths keep the 'web' behaviour. Max 100 lines, each starting with '/'." challengeTtlMinutes: type: integer minimum: 5 maximum: 43200 default: 30 description: Lifetime of the verification (clearance) cookie in minutes (5 minutes – 30 days). Capped at 15 minutes while Under Attack or automatic mitigation is active. Lowering it invalidates longer cookies immediately. modeDurationMinutes: type: integer minimum: 0 maximum: 10080 description: 0 = permanent (default); otherwise 5–10080 minutes (7 days) after which the previous mode is restored automatically. Send together with `mode`. maintenanceEta: type: string description: "Estimated completion as UTC epoch ms or ISO 8601 with a timezone (e.g. 2026-10-09T18:00:00Z). Empty string clears it." maintenanceContact: type: string description: E-mail address or https URL shown on the maintenance page. Empty string clears it. maintenanceAutoEnd: type: boolean description: Turn maintenance off automatically when maintenanceEta passes. wafSensitivity: type: string enum: - low - medium - high default: medium description: "WAF score thresholds: low = block 85 / challenge 55, medium = 70 / 40, high = 55 / 30. Under Attack keeps the block threshold at most 45." responses: 200: description: Policy updated (includes modeRevertTo / modeRevertAt) 400: description: Invalid field value 403: description: Insufficient site role or plan 404: description: Site not found patch: summary: Patch Site Policy description: "Same as PUT: partial update, only the fields present in the body are changed." tags: - Policies parameters: - name: id in: path required: true schema: type: string requestBody: content: application/json: schema: type: object properties: mode: type: string enum: - Off - Monitor - Balanced - Under Attack wafEnabled: type: boolean botProtectionEnabled: type: boolean challengeEnabled: type: boolean rateLimitEnabled: type: boolean trafficProfile: type: string enum: - web - api - webhook - realtime default: web description: "How unverified traffic is handled. 'web' serves the HTML verification page (default). 'api', 'webhook' and 'realtime' never serve HTML challenges: challenge decisions are logged and a strict per-IP rate limit applies instead (api 20, webhook 5, realtime 30 req/s; halved under attack; 429 JSON with Retry-After). WAF blocks, IP blacklist, geo blocks, Zero Trust and DDoS protections still apply. 'webhook' additionally does not treat a missing User-Agent or cookie-less POST as a bot signal." profilePaths: type: string description: "Newline-separated path patterns the traffic profile applies to (e.g. '/api/*\\n/webhook/*'). Empty = whole site. Other paths keep the 'web' behaviour. Max 100 lines, each starting with '/'." challengeTtlMinutes: type: integer minimum: 5 maximum: 43200 default: 30 description: Lifetime of the verification (clearance) cookie in minutes (5 minutes – 30 days). Capped at 15 minutes while Under Attack or automatic mitigation is active. Lowering it invalidates longer cookies immediately. modeDurationMinutes: type: integer minimum: 0 maximum: 10080 description: 0 = permanent (default); otherwise 5–10080 minutes (7 days) after which the previous mode is restored automatically. Send together with `mode`. maintenanceEta: type: string description: "Estimated completion as UTC epoch ms or ISO 8601 with a timezone (e.g. 2026-10-09T18:00:00Z). Empty string clears it." maintenanceContact: type: string description: E-mail address or https URL shown on the maintenance page. Empty string clears it. maintenanceAutoEnd: type: boolean description: Turn maintenance off automatically when maintenanceEta passes. wafSensitivity: type: string enum: - low - medium - high default: medium description: "WAF score thresholds: low = block 85 / challenge 55, medium = 70 / 40, high = 55 / 30. Under Attack keeps the block threshold at most 45." responses: 200: description: Policy updated 400: description: Invalid field value 403: description: Insufficient site role or plan 404: description: Site not found /v1/sites/{id}/waf/rules: get: summary: List Site WAF Rules description: Returns custom WAF rules defined for the site. tags: - Policies parameters: - name: id in: path required: true schema: type: string responses: 200: description: List of WAF rules post: summary: Create Site WAF Rule description: Creates a new custom WAF rule. tags: - Policies parameters: - name: id in: path required: true schema: type: string responses: 201: description: WAF rule created /v1/sites/{id}/waf/rules/{ruleId}: delete: summary: Delete Site WAF Rule description: Deletes a custom WAF rule. tags: - Policies parameters: - name: id in: path required: true schema: type: string - name: ruleId in: path required: true schema: type: string responses: 200: description: WAF rule deleted /v1/events: get: summary: Query Security Events description: Returns paginated stream of security events, challenge outcomes, and blocked threats. tags: - Events parameters: - name: siteId in: query schema: type: string description: Filter by site ID - name: action in: query schema: type: string enum: - block - challenge - allow description: Filter by event action - name: limit in: query schema: type: integer default: 50 description: Number of events (max 100) responses: 200: description: Security events log 401: description: Unauthorized /v1/analytics/summary: get: summary: Get Summary Metrics description: Request counts, estimated bandwidth and mitigation statistics. summary.cachedRatio is the measured edge cache hit ratio (hits / (hits + misses) reported by the edge processes since they started), null when there were no cache-eligible requests. tags: - Analytics parameters: - name: period in: query schema: type: string enum: - 1h - 24h - 7d - 30d default: 24h responses: 200: description: Analytics summary 401: description: Unauthorized /v1/tokens: get: summary: List API Tokens description: Returns all API tokens owned by the authenticated user with masked prefix previews. tags: - Tokens responses: 200: description: List of API tokens 401: description: Unauthorized post: summary: Create API Token description: Creates a new scoped API token. Secret key is returned only once in response. tags: - Tokens requestBody: required: true content: application/json: schema: type: object required: - name properties: name: type: string example: Terraform Key scopes: type: array items: type: string example: - "sites:read" - "sites:write" - "analytics:read" expiresInDays: type: integer default: 30 ipRestrictions: type: string example: 198.51.100.10 responses: 201: description: Token created 400: description: Invalid scope or name /v1/tokens/{id}: delete: summary: Delete / Revoke API Token description: Permanently deletes and revokes an API token. tags: - Tokens parameters: - name: id in: path required: true schema: type: string responses: 200: description: Token revoked 404: description: Token not found /v1/sites/{id}/origin/lock/snippets: get: summary: Get Origin Lock Web Server Snippets description: "Returns ready-to-paste firewall and web server configuration snippets (Nginx, PHP, Apache, Caddy, Cloudflare, UFW, Iptables) configured with the site's unique cryptographic header and secret." tags: - Origin & Lock parameters: - name: id in: path required: true schema: type: string responses: 200: description: Origin Lock code snippets 404: description: Site not found /v1/sites/{id}/origin/lock/verify: post: summary: Verify Origin Lock Live description: Executes live cryptographic handshake probe to verify origin web server blocks direct IP access while allowing Nexren Shield edge proxy. tags: - Origin & Lock parameters: - name: id in: path required: true schema: type: string responses: 200: description: Origin Lock verification result 404: description: Site not found /v1/sites/{id}/tunnels: get: summary: List Site Tunnels description: Lists all Nexren Tunnels configured for zero-open-port reverse origin tunneling on this site. tags: - Tunnels parameters: - name: id in: path required: true schema: type: string responses: 200: description: List of site tunnels 404: description: Site not found post: summary: Create Nexren Tunnel description: Provisions a new encrypted WebSocket/QUIC reverse tunnel token for exposing origins behind strict firewalls and NATs without public IPs. tags: - Tunnels parameters: - name: id in: path required: true schema: type: string requestBody: content: application/json: schema: type: object properties: name: type: string example: Primary App Cluster localTarget: type: string example: "http://127.0.0.1:3000" responses: 201: description: Tunnel created with secret token 400: description: Bad request /v1/sites/{id}/tunnels/{tunnelId}: get: summary: Get Site Tunnel Details description: Retrieves live connection status, RTT latency, stream count, and credentials for a tunnel. tags: - Tunnels parameters: - name: id in: path required: true schema: type: string - name: tunnelId in: path required: true schema: type: string responses: 200: description: Tunnel details 404: description: Tunnel not found delete: summary: Revoke Site Tunnel description: Immediately revokes and disconnects an active Nexren Tunnel. tags: - Tunnels parameters: - name: id in: path required: true schema: type: string - name: tunnelId in: path required: true schema: type: string responses: 200: description: Tunnel revoked 404: description: Tunnel not found /v1/sites/{id}/origin-kind: post: summary: Switch Site Origin Kind description: "Switches origin routing mode between direct IP/URL ('direct') and reverse tunnel ('tunnel')." tags: - Tunnels parameters: - name: id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object required: - originKind properties: originKind: type: string enum: - direct - tunnel responses: 200: description: Origin kind switched 400: description: Invalid kind /v1/tunnels: get: summary: List All User Tunnels description: Lists all Nexren Tunnels across all accessible sites for the authenticated account. tags: - Tunnels responses: 200: description: List of all user tunnels 401: description: Unauthorized /v1/sites/{id}/waf/exceptions: get: summary: List Scoped WAF Exceptions description: Returns scoped WAF exceptions in the legacy line format (` [methods]`). Since v4.10.231 they are stored as custom rules (action `skip` with `wafRules`); this view lists custom rules that only have a glob path (+ methods) condition, plus any legacy line that could not be migrated. tags: - WAF parameters: - name: id in: path required: true schema: type: string responses: 200: description: List of WAF exceptions 404: description: Site not found put: summary: Update Scoped WAF Exceptions description: Replaces all scoped exceptions ( [methods]); written as custom rules (`skip` + `wafRules`), other custom rules are kept. Whole-site wildcards are strictly rejected for safety. Site manager role. POST /v1/sites/{id}/waf/exceptions appends one line the same way. tags: - WAF parameters: - name: id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: raw: type: string example: "930120 /api/v1/upload POST\n941100 /admin/* *" responses: 200: description: Exceptions updated 400: description: Syntax or wildcard violation /v1/sites/{id}/waf/exceptions/{ruleId}: delete: summary: Delete WAF Exception Rule description: Removes the rule ID from every scoped exception (custom rules with `wafRules`) of the site. Site manager role. tags: - WAF parameters: - name: id in: path required: true schema: type: string - name: ruleId in: path required: true schema: type: string responses: 200: description: Exception deleted 404: description: Site not found /v1/sites/{id}/custom-rules: get: summary: List Custom Rules description: "Ordered custom rules (first match wins; `log` records and continues; `override` and WAF-rule-scoped `skip` are non-final phases), the built-in templates and the per-site limit (100). Viewer role and policies:read or sites:read." tags: - Custom Rules parameters: - name: id in: path required: true schema: type: string responses: 200: description: Rules, templates and limits 404: description: Site not found put: summary: Replace Custom Rules (ordered) description: "Replaces the whole ordered list. Site manager role and policies:write or sites:write. `allow` skips WAF, bot, rate limiting and verification — but NOT the global/site IP blacklist, country rule, maintenance, Zero Trust or kernel/DDoS flood protection. Relaxing rules (`allow`, `skip`) with a path condition are not applied to ambiguous paths (encoded separators, `..`, `;`). No user regex: paths match by prefix, exact or `*`-glob." tags: - Custom Rules parameters: - name: id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object required: - rules properties: rules: type: array maxItems: 100 items: $ref: "#/components/schemas/CustomRule" responses: 200: description: Saved rules (ids assigned) 400: description: Validation error 404: description: Site not found or role below manager post: summary: Add Custom Rule description: "Adds one rule at `position` (default: end). Site manager role." tags: - Custom Rules parameters: - name: id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: rule: $ref: "#/components/schemas/CustomRule" position: type: integer minimum: 0 responses: 201: description: Rule created 400: description: Validation error or limit reached /v1/sites/{id}/custom-rules/order: post: summary: Reorder Custom Rules description: `ids` must list every rule id exactly once, in the new evaluation order. Site manager role. tags: - Custom Rules parameters: - name: id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object required: - ids properties: ids: type: array items: type: string responses: 200: description: Reordered rules 400: description: ids is not a permutation of the current rule ids /v1/sites/{id}/custom-rules/{ruleId}: get: summary: Get Custom Rule tags: - Custom Rules parameters: - name: id in: path required: true schema: type: string - name: ruleId in: path required: true schema: type: string responses: 200: description: Rule 404: description: Not found patch: summary: Update Custom Rule description: Merges the given fields into the rule; its position is kept. Site manager role. tags: - Custom Rules parameters: - name: id in: path required: true schema: type: string - name: ruleId in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CustomRule" responses: 200: description: Updated rule 400: description: Validation error 404: description: Not found put: summary: Replace Custom Rule description: Replaces the rule in place (position kept). Site manager role. tags: - Custom Rules parameters: - name: id in: path required: true schema: type: string - name: ruleId in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CustomRule" responses: 200: description: Updated rule 400: description: Validation error 404: description: Not found delete: summary: Delete Custom Rule tags: - Custom Rules parameters: - name: id in: path required: true schema: type: string - name: ruleId in: path required: true schema: type: string responses: 200: description: Deleted 404: description: Not found /v1/sites/{id}/exemptions: get: summary: Unified Exemptions View description: Every exemption source in one list — IP-excluded paths, Zero Trust excluded paths (with the implicit effect of scope `all`), the IP allow-list action, ZT session bypasses and custom rules (`allow`/`skip`, WAF-rule-scoped `skip`, relaxing `override`) — each with what it skips. tags: - Custom Rules parameters: - name: id in: path required: true schema: type: string responses: 200: description: Exemption rows 404: description: Site not found /v1/sites/{id}/explain: get: summary: Why Was This Request Blocked? description: "Looks up a request id in this site's event log and replays today's policy step by step (blacklist, IP access, country, maintenance, Zero Trust, custom rules, exemptions, DDoS, override rule, WAF, bot), with a suggested fix (e.g. a custom-rule draft that skips only the matched WAF rule ids, or a `skip waf` draft). Only this site's events; the client IP is masked for the viewer role. Lookup is by request id only. Scope events:read, policies:read or sites:read." tags: - Custom Rules parameters: - name: id in: path required: true schema: type: string - name: requestId in: query required: true schema: type: string pattern: ^[A-Za-z0-9_-]{8,80}$ responses: 200: description: Event, network data and trace 400: description: Malformed request id 404: description: No event for this request id on this site /v1/sites/{id}/waf/exceptions/validate: post: summary: Validate Scoped WAF Exceptions Syntax description: Dry-run syntax validator for exception rules without persisting changes. tags: - WAF parameters: - name: id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object required: - raw properties: raw: type: string example: 930120 /api/upload POST responses: 200: description: Validation result /v1/sites/{id}/ddos: get: summary: Get Rate Limiting & DDoS Mitigation Settings description: Retrieves rate limiting RPS, burst headroom, challenge sensitivity, and live mitigation state. tags: - DDoS & Rate Limiting parameters: - name: id in: path required: true schema: type: string responses: 200: description: DDoS and rate limit configuration 404: description: Site not found put: summary: Update Rate Limiting & DDoS Settings description: Updates RPS limit, burst capacity, mitigation mode, and sensitivity threshold. tags: - DDoS & Rate Limiting parameters: - name: id in: path required: true schema: type: string requestBody: content: application/json: schema: type: object properties: rateLimitRps: type: integer example: 100 rateLimitBurst: type: integer example: 150 ddosSensitivity: type: string enum: - low - medium - high - paranoid challengeBotDDoS: type: boolean responses: 200: description: DDoS settings updated 400: description: Invalid parameters /v1/sites/{id}/ddos/mitigate: post: summary: Trigger Immediate DDoS Mitigation description: "Forces site into emergency 'Under Attack' mode with mandatory JS PoW/CAPTCHA challenge." tags: - DDoS & Rate Limiting parameters: - name: id in: path required: true schema: type: string responses: 200: description: Mitigation engaged 404: description: Site not found /v1/sites/{id}/ddos/reset: post: summary: Reset Rate Limit Windows description: Clears sliding-window rate counters and ban-lists for the site. tags: - DDoS & Rate Limiting parameters: - name: id in: path required: true schema: type: string responses: 200: description: Rate limits reset 404: description: Site not found /v1/notifications/channels: get: summary: List Notification Channels description: "Returns every notification channel visible to the token owner. Each channel has a `scope`: `site` (one site; `siteId` set), `my_sites` (every site the token owner owns or holds the `notifications:edit` site permission on, resolved live at delivery time — never other tenants' sites) or `platform` (platform administrators only; `siteFilter` all_sites/selected_sites/exclude_sites). Targets are always masked (`targetPreview`). Site channels are readable with `notifications:view`; `my_sites` channels only by their creator." tags: - Notifications parameters: - name: scope in: query schema: type: string enum: - all - site - my_sites - platform default: all - name: siteId in: query schema: type: string description: Only site channels of this site and multi-site channels that cover it responses: 200: description: Channel list content: application/json: schema: type: object properties: channels: type: array items: $ref: "#/components/schemas/NotificationChannel" total: type: integer 400: description: Invalid scope 404: description: Site not found post: summary: Create Notification Channel description: "Creates a channel. `scope: site` (default) needs `siteId` and site role 'manager'. `scope: my_sites` covers every site you own or manage. `scope: platform` requires a platform administrator. Non-admin accounts may only bind their own credentials and send email only to their own account address." tags: - Notifications requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/NotificationChannelInput" responses: 201: description: Channel created content: application/json: schema: type: object properties: channel: $ref: "#/components/schemas/NotificationChannel" 400: description: Validation error 403: description: Scope or recipient not allowed 404: description: Site not found /v1/notifications/channels/{id}: get: summary: Get Notification Channel tags: - Notifications parameters: - name: id in: path required: true schema: type: string responses: 200: description: Channel content: application/json: schema: type: object properties: channel: $ref: "#/components/schemas/NotificationChannel" 404: description: Not found patch: summary: Update Notification Channel description: "Merges the given fields. `scope` can switch only between `my_sites` and `platform` (platform: administrators only); a site channel stays site-scoped — recreate it to widen its scope." tags: - Notifications parameters: - name: id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/NotificationChannelInput" responses: 200: description: Updated channel 400: description: Validation error 403: description: Not allowed 404: description: Not found delete: summary: Delete Notification Channel tags: - Notifications parameters: - name: id in: path required: true schema: type: string responses: 200: description: Deleted 404: description: Not found /v1/notifications/channels/{id}/test: post: summary: Send Test Notification tags: - Notifications parameters: - name: id in: path required: true schema: type: string responses: 200: description: Test attempted 404: description: Not found /v1/sites/{id}/notifications/channels: get: summary: List Channels Covering a Site description: Site channels of the site plus the `my_sites`/`platform` channels visible to you that cover it. tags: - Notifications parameters: - name: id in: path required: true schema: type: string - name: scope in: query schema: type: string enum: - all - site - my_sites - platform default: all responses: 200: description: Channel list 404: description: Site not found post: summary: Create Site Channel description: "Creates a `site`-scoped channel on this site (site role 'manager')." tags: - Notifications parameters: - name: id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/NotificationChannelInput" responses: 201: description: Channel created 403: description: Insufficient role 404: description: Site not found /v1/sites/{id}/notifications/owner-alerts: get: summary: Get Owner Alert Defaults description: "When the site has no notification channel subscribed to a critical event (tunnel offline/online, certificate expiring/renewal failed, quota 80%/100%, origin lock broken, DDoS start), Shield emails the site owner's account address. Returns that setting, the optional daily summary flag and the list of covered events." tags: - Notifications parameters: - name: id in: path required: true schema: type: string responses: 200: description: Owner alert settings 404: description: Site not found patch: summary: Update Owner Alert Defaults description: "Turns the owner email fallback (default on) and the daily summary email (default off, sent around 09:00 Europe/Istanbul) on or off. Requires site role 'manager'." tags: - Notifications parameters: - name: id in: path required: true schema: type: string requestBody: content: application/json: schema: type: object properties: ownerAlertsEnabled: type: boolean ownerDigestEnabled: type: boolean responses: 200: description: Updated settings 400: description: No boolean field given 403: description: Insufficient site role 404: description: Site not found /v1/sites/{id}/maintenance: get: summary: Get Maintenance Mode Status description: Retrieves maintenance mode toggle state, custom HTML template, ETA, and IP bypass list. tags: - Maintenance Mode parameters: - name: id in: path required: true schema: type: string responses: 200: description: Maintenance configuration 404: description: Site not found put: summary: Update Maintenance Mode Configuration description: Updates maintenance mode enabled state, custom HTML page, bypass CIDR IPs, and estimated completion time. tags: - Maintenance Mode parameters: - name: id in: path required: true schema: type: string requestBody: content: application/json: schema: type: object properties: enabled: type: boolean customHtml: type: string bypassIps: type: array items: type: string eta: type: string description: "Estimated completion: UTC epoch ms or ISO 8601 with a timezone (e.g. 2026-10-09T18:00:00Z); null or empty clears it. Shown on the maintenance page in UTC and drives Retry-After." contact: type: string description: E-mail address or https URL shown on the maintenance page; null or empty clears it. autoEnd: type: boolean description: Turn maintenance off automatically when the ETA passes (default false). statusCode: type: integer default: 503 responses: 200: description: Maintenance mode updated 400: description: Bad request /v1/sites/{id}/maintenance/toggle: post: summary: Toggle Maintenance Mode description: Quick toggle to switch maintenance mode on or off. tags: - Maintenance Mode parameters: - name: id in: path required: true schema: type: string requestBody: content: application/json: schema: type: object properties: enabled: type: boolean responses: 200: description: Maintenance mode toggled /v1/sites/{id}/maintenance/preview: get: summary: Preview Maintenance Page description: Renders the maintenance HTML template as it will be served to visitors during maintenance. tags: - Maintenance Mode parameters: - name: id in: path required: true schema: type: string responses: 200: description: HTML maintenance page 404: description: Site not found /v1/sites/{id}/zt/access-rules: get: summary: List Zero Trust Access Rules description: Returns path-based Zero Trust access rules protecting private routes and admin portals. tags: - Zero Trust parameters: - name: id in: path required: true schema: type: string responses: 200: description: List of access rules 404: description: Site not found post: summary: Create Zero Trust Access Rule description: Creates an access policy rule requiring TOTP 2FA, corporate email domain verification, or IP whitelist. tags: - Zero Trust parameters: - name: id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object required: - name - pathPattern properties: name: type: string example: Admin Portal 2FA pathPattern: type: string example: /admin/* action: type: string enum: - allow - block - authenticate default: authenticate require2fa: type: boolean default: false allowedEmails: type: array items: type: string allowedIps: type: array items: type: string responses: 201: description: Access rule created 400: description: Bad request /v1/sites/{id}/zt/access-rules/{ruleId}: get: summary: Get Zero Trust Access Rule description: Retrieves single access policy rule by ID. tags: - Zero Trust parameters: - name: id in: path required: true schema: type: string - name: ruleId in: path required: true schema: type: string responses: 200: description: Access rule details 404: description: Rule not found put: summary: Update Zero Trust Access Rule description: Updates an existing Zero Trust access policy rule. tags: - Zero Trust parameters: - name: id in: path required: true schema: type: string - name: ruleId in: path required: true schema: type: string requestBody: content: application/json: schema: type: object properties: name: type: string pathPattern: type: string action: type: string enum: - allow - block - authenticate require2fa: type: boolean responses: 200: description: Access rule updated 404: description: Rule not found delete: summary: Delete Zero Trust Access Rule description: Deletes a Zero Trust access policy rule. tags: - Zero Trust parameters: - name: id in: path required: true schema: type: string - name: ruleId in: path required: true schema: type: string responses: 200: description: Access rule deleted 404: description: Rule not found /v1/sites/{id}/zt/users/{userId}/verify-2fa: post: summary: Verify User 2FA Token description: Validates a 6-digit TOTP code against enrolled Zero Trust user secret. tags: - Zero Trust parameters: - name: id in: path required: true schema: type: string - name: userId in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object required: - token properties: token: type: string example: 123456 responses: 200: description: 2FA verification result 400: description: Invalid token /v1/sites/{id}/zt/sessions: get: summary: Get Zero Trust Sessions description: Lists active authenticated Zero Trust sessions and timeout policies, including `excludedPaths` and `excludedPathsScope`. tags: - Zero Trust parameters: - name: id in: path required: true schema: type: string responses: 200: description: Active sessions and policy 404: description: Site not found patch: summary: Update Zero Trust Session & Exemption Policy description: "Site manager role. `excludedPathsScope`: `all` (default, historical) — a path excluded from Zero Trust is ALSO exempt from IP/country rules, verification, flood verification and bot decisions; `zt_only` — the path skips only Zero Trust. Same body is accepted on PUT and on /zt/exemptions." tags: - Zero Trust parameters: - name: id in: path required: true schema: type: string requestBody: content: application/json: schema: type: object properties: durationMinutes: type: integer authMethod: type: string enum: - email_only - totp_only - both exemptionScope: type: string enum: - cookie_only - ip_only - hybrid bypassRateLimit: type: boolean bypassWaf: type: boolean ipWhitelist: type: string excludedPaths: type: string description: One path pattern per line excludedPathsScope: type: string enum: - all - zt_only protectedPaths: type: string responses: 200: description: Updated policy 400: description: Invalid value 404: description: Site not found or role below manager /v1/sites/{id}/zt/sessions/revoke: post: summary: Revoke Zero Trust Sessions description: Revokes active Zero Trust sessions for a specific user email or all users across the site. tags: - Zero Trust parameters: - name: id in: path required: true schema: type: string requestBody: content: application/json: schema: type: object properties: email: type: string example: dev@example.com responses: 200: description: Sessions revoked 404: description: Site not found /v1/sites/{id}/incidents: get: summary: List Site DDoS Incidents description: Returns recorded volumetric and L7 flood attack mitigation incidents for the site. tags: - Threats & Incidents parameters: - name: id in: path required: true schema: type: string - name: limit in: query schema: type: integer default: 30 responses: 200: description: List of incidents 404: description: Site not found /v1/incidents: get: summary: List All DDoS Incidents description: Returns recorded DDoS attack incidents across all sites accessible to the account. tags: - Threats & Incidents parameters: - name: limit in: query schema: type: integer default: 30 responses: 200: description: List of all DDoS incidents 401: description: Unauthorized /v1/threats/live: get: summary: Real-Time Live Threat Feed description: Returns live stream of blocked attack traffic, matched WAF rules, attacker IP masking, and geo-location. tags: - Threats & Incidents parameters: - name: siteId in: query schema: type: string - name: limit in: query schema: type: integer default: 50 responses: 200: description: Live threat feed 401: description: Unauthorized /v1/threats/summary: get: summary: Threat Intelligence Summary description: Returns aggregated attack distribution breakdown by category (SQLi, XSS, RCE, DDoS, Bot, Scanner). tags: - Threats & Incidents parameters: - name: siteId in: query schema: type: string - name: period in: query schema: type: string enum: - 1h - 24h - 7d - 30d default: 24h responses: 200: description: Threat summary metrics 401: description: Unauthorized /v1/sites/{id}/audit-logs: get: summary: List Site Audit Logs description: Returns security audit trail of configuration changes, key rotations, and actions on this site. tags: - Audit Logs parameters: - name: id in: path required: true schema: type: string - name: limit in: query schema: type: integer default: 50 - name: offset in: query schema: type: integer default: 0 - name: category in: query schema: type: string responses: 200: description: Site audit logs 404: description: Site not found /v1/audit-logs: get: summary: List Account Audit Logs description: Returns security audit trail across all accessible sites and API activities. tags: - Audit Logs parameters: - name: limit in: query schema: type: integer default: 50 - name: offset in: query schema: type: integer default: 0 - name: category in: query schema: type: string - name: search in: query schema: type: string responses: 200: description: Account audit logs 401: description: Unauthorized /v1/audit-logs/{logId}: get: summary: Get Audit Log By ID description: Retrieves complete audit record details including client IP, actor, diff, and timestamp. tags: - Audit Logs parameters: - name: logId in: path required: true schema: type: string responses: 200: description: Audit log entry 404: description: Audit log not found components: schemas: NotificationChannel: type: object properties: id: type: string description: Site channels start with `nch_`, multi-site channels with `notif_rule_` scope: type: string enum: - site - my_sites - platform siteId: type: - string - null description: Set only for `site` scope siteFilter: type: string enum: - all_sites - selected_sites - exclude_sites description: `platform` scope only siteIds: type: array items: type: string description: `platform` scope with selected/exclude filter coveredSiteCount: type: integer description: "`my_sites` scope: sites currently covered" name: type: string platform: type: string enum: - email - telegram - discord - slack - webhook enabled: type: boolean targetPreview: type: string description: Masked destination; secrets are never returned events: type: array items: type: string lastStatus: type: string lastSentAt: type: integer sentCount: type: integer createdAt: type: integer NotificationChannelInput: type: object properties: scope: type: string enum: - site - my_sites - platform default: site siteId: type: string description: Required for `site` scope (or use /v1/sites/{id}/notifications/channels) siteFilter: type: string enum: - all_sites - selected_sites - exclude_sites default: all_sites description: `platform` scope only siteIds: type: array items: type: string name: type: string maxLength: 80 platform: type: string enum: - email - telegram - discord - slack - webhook credentialId: type: string description: Saved credential to deliver through (your own; multi-site scopes only) target: oneOf: - type: string - type: object description: Destination when no credential is given events: type: array items: type: string minSeverity: type: string enum: - all - high_critical - critical_only description: Multi-site scopes only language: type: string enum: - tr - en enabled: type: boolean default: true CustomRule: type: object required: - name - action - match properties: id: type: string pattern: ^cr_[a-z]{6,24}$ description: Assigned by the server when missing or invalid name: type: string maxLength: 80 enabled: type: boolean default: true action: type: string enum: - block - challenge - allow - skip - log - override description: "`override` (replaces the former path rules) is a separate, non-final phase: the first matching override rule changes mode/WAF/bot/verification for the request and may add a per-rule rate limit; final rules are still evaluated." skip: type: array items: type: string enum: - waf - bot - rate_limit - challenge description: Required (non-empty) when action is skip wafRules: type: array maxItems: 50 items: type: string pattern: "^([A-Za-z0-9_.:-]{1,64}|\\*)$" description: "Only with action skip and skip = [\"waf\"]: skip only these WAF rule ids instead of the whole WAF (replaces the former scoped WAF exceptions). Not final — every matching rule of this kind accumulates." override: type: object description: Only with action override. Omitted fields inherit the site setting. Relaxing fields (waf/bot off, Off/Monitor mode, challenge never) are not applied on ambiguous paths when the rule has a path condition. properties: mode: type: string enum: - Off - Monitor - Balanced - Under Attack waf: type: string enum: - on - off botProtection: type: string enum: - on - off challenge: type: string enum: - always - never rateLimit: type: object required: - requests - windowSec properties: requests: type: integer minimum: 1 maximum: 100000 windowSec: type: integer minimum: 1 maximum: 3600 action: type: string enum: - block - challenge default: block match: type: object description: All given conditions must match (AND). At least one condition. properties: path: type: object properties: op: type: string enum: - prefix - exact - glob values: type: array maxItems: 50 items: type: string methods: type: array items: type: string enum: - GET - HEAD - POST - PUT - PATCH - DELETE - OPTIONS - TRACE - CONNECT userAgent: type: object properties: op: type: string enum: - contains - not_contains values: type: array items: type: string asn: type: object properties: op: type: string enum: - in - not_in values: type: array items: type: integer country: type: object properties: op: type: string enum: - in - not_in values: type: array items: type: string pattern: ^[A-Z]{2}$ network: type: object properties: op: type: string enum: - is - is_not values: type: array items: type: string enum: - datacenter - tor headers: type: array maxItems: 5 items: type: object properties: name: type: string op: type: string enum: - contains - equals - present - absent value: type: string query: type: array maxItems: 5 items: type: object properties: name: type: string description: "\"*\" = any parameter (contains/equals only)" op: type: string enum: - contains - equals - present - absent value: type: string ip: type: object properties: op: type: string enum: - in - not_in values: type: array maxItems: 100 items: type: string description: IP or CIDR securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: nx_live_ description: Standard HTTP Authorization header with Bearer token format apiKeyAuth: type: apiKey in: header name: X-API-Key description: Alternative custom header passing the raw API token secret scopes: sites:read: View websites and configuration sites:write: Create and update websites and settings sites:delete: Delete websites policies:read: Read security policy and mode settings policies:write: Modify security policy and mode settings analytics:read: Read analytics and traffic metrics events:read: Read security event logs tokens:read: List API tokens tokens:write: Create and revoke API tokens