{
  "openapi": "3.1.0",
  "info": {
    "title": "Nexren Shield Customer REST API",
    "version": "1.0.0",
    "description": "High-performance edge security, DDoS mitigation, WAF management, and Zero Trust control API for Nexren Shield.",
    "contact": {
      "name": "Nexren Shield Security Operations",
      "url": "https://shield.nexren.info",
      "email": "support@nexren.com"
    }
  },
  "servers": [
    {
      "url": "https://shield.nexren.info",
      "description": "Production Shield Edge Gateway"
    },
    {
      "url": "http://127.0.0.1:18080",
      "description": "Local Development Control Plane"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    },
    {
      "apiKeyAuth": []
    }
  ],
  "paths": {
    "/v1/identity": {
      "get": {
        "summary": "Get Authenticated Identity Profile",
        "description": "Returns the authenticated user profile, organization info, active plan, and capabilities.",
        "tags": [
          "Identity"
        ],
        "responses": {
          "200": {
            "description": "Identity profile details"
          },
          "401": {
            "description": "Unauthorized"
          }
        }
      }
    },
    "/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/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.",
        "tags": [
          "Sites"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "domain"
                ],
                "properties": {
                  "domain": {
                    "type": "string",
                    "example": "example.com"
                  },
                  "originUrl": {
                    "type": "string",
                    "example": "https://198.51.100.10"
                  },
                  "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"
          },
          "409": {
            "description": "Conflict - domain already registered"
          }
        }
      }
    },
    "/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 (strict IDOR protection)"
          }
        }
      },
      "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": "Clears edge cache for the site domain.",
        "tags": [
          "Sites"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Cache purged successfully"
          },
          "404": {
            "description": "Site 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"
                  },
                  "headerName": {
                    "type": "string"
                  },
                  "secretValue": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Origin updated"
          },
          "404": {
            "description": "Site not found"
          }
        }
      }
    },
    "/v1/sites/{id}/lock": {
      "get": {
        "summary": "Get Lock & Under Attack Status",
        "tags": [
          "Origin & Lock"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Lock status"
          },
          "404": {
            "description": "Site not found"
          }
        }
      }
    },
    "/v1/sites/{id}/lock/activate": {
      "post": {
        "summary": "Activate Under Attack Mode",
        "tags": [
          "Origin & Lock"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Lock activated"
          },
          "404": {
            "description": "Site not found"
          }
        }
      }
    },
    "/v1/sites/{id}/lock/deactivate": {
      "post": {
        "summary": "Deactivate Under Attack Mode",
        "tags": [
          "Origin & Lock"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Lock deactivated"
          },
          "404": {
            "description": "Site not found"
          }
        }
      }
    },
    "/v1/sites/{id}/origin/test-lock": {
      "post": {
        "summary": "Test Origin Lock Enforcement",
        "tags": [
          "Origin & Lock"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Lock test results"
          },
          "404": {
            "description": "Site not found"
          }
        }
      }
    },
    "/v1/sites/{id}/health": {
      "get": {
        "summary": "Origin Health Check & Latency Probe",
        "tags": [
          "Origin & Lock"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Health status"
          },
          "404": {
            "description": "Site not found"
          }
        }
      }
    },
    "/v1/sites/{id}/ssl": {
      "get": {
        "summary": "Get SSL Certificate Status",
        "tags": [
          "SSL & DNS"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "SSL status"
          },
          "404": {
            "description": "Site not found"
          }
        }
      }
    },
    "/v1/sites/{id}/ssl/reissue": {
      "post": {
        "summary": "Reissue / Provision SSL Certificate",
        "tags": [
          "SSL & DNS"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "SSL issued"
          },
          "202": {
            "description": "SSL pending"
          },
          "404": {
            "description": "Site not found"
          }
        }
      }
    },
    "/v1/sites/{id}/dns": {
      "get": {
        "summary": "Get DNS Verification Records",
        "tags": [
          "SSL & DNS"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "DNS records"
          },
          "404": {
            "description": "Site not found"
          }
        }
      },
      "post": {
        "summary": "Verify DNS Resolution",
        "tags": [
          "SSL & DNS"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "DNS verification results"
          },
          "404": {
            "description": "Site not found"
          }
        }
      }
    },
    "/v1/policies": {
      "get": {
        "summary": "List Security Policies",
        "tags": [
          "Policies"
        ],
        "responses": {
          "200": {
            "description": "List of policies"
          }
        }
      },
      "post": {
        "summary": "Create / Update Site Policy",
        "tags": [
          "Policies"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "siteId"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Policy saved"
          },
          "404": {
            "description": "Site not found"
          }
        }
      }
    },
    "/v1/policies/{id}": {
      "get": {
        "summary": "Get Policy by ID / Site ID",
        "tags": [
          "Policies"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Policy configuration"
          },
          "404": {
            "description": "Policy not found"
          }
        }
      },
      "put": {
        "summary": "Update Security Policy",
        "tags": [
          "Policies"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Policy updated"
          },
          "404": {
            "description": "Policy not found"
          }
        }
      },
      "delete": {
        "summary": "Reset Policy to Defaults",
        "tags": [
          "Policies"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Policy reset"
          },
          "404": {
            "description": "Policy not found"
          }
        }
      }
    },
    "/v1/policies/simulate": {
      "post": {
        "summary": "Simulate Request Against Policy",
        "tags": [
          "Policies"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "method": {
                    "type": "string",
                    "default": "GET"
                  },
                  "path": {
                    "type": "string",
                    "default": "/"
                  },
                  "query": {
                    "type": "string"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Simulation decision (allow, block, challenge)"
          }
        }
      }
    },
    "/v1/sites/{id}/waf": {
      "get": {
        "summary": "Get WAF Status & Metrics",
        "tags": [
          "WAF"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "WAF status"
          },
          "404": {
            "description": "Site not found"
          }
        }
      },
      "patch": {
        "summary": "Update WAF Mode & Settings",
        "tags": [
          "WAF"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "WAF updated"
          },
          "404": {
            "description": "Site not found"
          }
        }
      }
    },
    "/v1/sites/{id}/waf/rules": {
      "get": {
        "summary": "List WAF Rules",
        "tags": [
          "WAF"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of rules with active status"
          },
          "404": {
            "description": "Site not found"
          }
        }
      },
      "post": {
        "summary": "Create or Toggle WAF Rule",
        "tags": [
          "WAF"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Rule updated"
          },
          "404": {
            "description": "Site not found"
          }
        }
      }
    },
    "/v1/sites/{id}/waf/test": {
      "post": {
        "summary": "Test Payload Against WAF",
        "tags": [
          "WAF"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "payload"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "WAF evaluation result"
          },
          "404": {
            "description": "Site not found"
          }
        }
      }
    },
    "/v1/sites/{id}/waf/proof": {
      "post": {
        "summary": "Run Synthetic Exploit Proof Battery",
        "tags": [
          "WAF"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Battery results across SQLi, XSS, LFI, RCE"
          },
          "404": {
            "description": "Site not found"
          }
        }
      }
    },
    "/v1/events": {
      "get": {
        "summary": "Query Security Event Logs",
        "tags": [
          "Events"
        ],
        "parameters": [
          {
            "name": "siteId",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "action",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "ip",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated security events"
          }
        }
      }
    },
    "/v1/events/facets": {
      "get": {
        "summary": "Get Aggregate Attack Facets",
        "tags": [
          "Events"
        ],
        "responses": {
          "200": {
            "description": "Attack facets (top IPs, countries, paths, rules)"
          }
        }
      }
    },
    "/v1/events/{id}": {
      "get": {
        "summary": "Get Event Details by ID",
        "tags": [
          "Events"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Event details"
          },
          "404": {
            "description": "Event not found"
          }
        }
      }
    },
    "/v1/requests/{requestId}": {
      "get": {
        "summary": "Trace Unique Request ID",
        "tags": [
          "Events"
        ],
        "parameters": [
          {
            "name": "requestId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Complete trace events for Request ID"
          },
          "404": {
            "description": "Trace not found"
          }
        }
      }
    },
    "/v1/analytics/summary": {
      "get": {
        "summary": "Get Aggregated Traffic & Threat Summary",
        "tags": [
          "Analytics"
        ],
        "responses": {
          "200": {
            "description": "Aggregated bandwidth, requests, and threat ratio"
          }
        }
      }
    },
    "/v1/analytics/timeseries": {
      "get": {
        "summary": "Get Real-Time Time-Series Stream",
        "tags": [
          "Analytics"
        ],
        "responses": {
          "200": {
            "description": "Time-bucketed request and block rates"
          }
        }
      }
    },
    "/v1/analytics/breakdown": {
      "get": {
        "summary": "Get Traffic Breakdown",
        "tags": [
          "Analytics"
        ],
        "responses": {
          "200": {
            "description": "Breakdown by country, status code, method, path"
          }
        }
      }
    },
    "/v1/zt/tunnels": {
      "get": {
        "summary": "List Zero Trust Tunnels",
        "tags": [
          "Zero Trust"
        ],
        "responses": {
          "200": {
            "description": "List of tunnels"
          }
        }
      },
      "post": {
        "summary": "Create Zero Trust Tunnel",
        "tags": [
          "Zero Trust"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Tunnel created with connector token"
          }
        }
      }
    },
    "/v1/zt/access-rules": {
      "get": {
        "summary": "List Zero Trust Access Rules",
        "tags": [
          "Zero Trust"
        ],
        "responses": {
          "200": {
            "description": "List of access rules"
          }
        }
      },
      "post": {
        "summary": "Create Zero Trust Access Rule",
        "tags": [
          "Zero Trust"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "pathPattern"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Access rule created"
          }
        }
      }
    },
    "/v1/sites/{id}/zt/users": {
      "get": {
        "summary": "List Enrolled Zero Trust Users",
        "tags": [
          "Zero Trust"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Enrolled users"
          },
          "404": {
            "description": "Site not found"
          }
        }
      },
      "post": {
        "summary": "Enroll User with 2FA / TOTP",
        "tags": [
          "Zero Trust"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "User enrolled with TOTP secret and QR code"
          },
          "404": {
            "description": "Site not found"
          }
        }
      }
    },
    "/v1/sites/{id}/zt/users/{email}": {
      "delete": {
        "summary": "Remove / Reset Zero Trust User",
        "tags": [
          "Zero Trust"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "email",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "User removed"
          },
          "404": {
            "description": "Site not found"
          }
        }
      }
    },
    "/v1/notifications/channels": {
      "get": {
        "summary": "List Alert Channels",
        "tags": [
          "Notifications"
        ],
        "responses": {
          "200": {
            "description": "List of channels (targets masked)"
          }
        }
      },
      "post": {
        "summary": "Create Alert Channel",
        "tags": [
          "Notifications"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "siteId",
                  "platform",
                  "target"
                ],
                "properties": {
                  "siteId": {
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  },
                  "platform": {
                    "type": "string",
                    "enum": [
                      "email",
                      "telegram",
                      "discord",
                      "slack",
                      "webhook"
                    ]
                  },
                  "target": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Channel created"
          }
        }
      }
    },
    "/v1/notifications/channels/{id}": {
      "get": {
        "summary": "Get Channel Details",
        "tags": [
          "Notifications"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Channel details"
          },
          "404": {
            "description": "Channel not found"
          }
        }
      },
      "put": {
        "summary": "Update Channel",
        "tags": [
          "Notifications"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Channel updated"
          },
          "404": {
            "description": "Channel not found"
          }
        }
      },
      "delete": {
        "summary": "Delete Channel",
        "tags": [
          "Notifications"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Channel deleted"
          },
          "404": {
            "description": "Channel not found"
          }
        }
      }
    },
    "/v1/notifications/channels/{id}/test": {
      "post": {
        "summary": "Send Immediate Test Alert",
        "tags": [
          "Notifications"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Test alert dispatched"
          },
          "404": {
            "description": "Channel not found"
          }
        }
      }
    },
    "/v1/notifications/history": {
      "get": {
        "summary": "Get Alert Delivery History",
        "tags": [
          "Notifications"
        ],
        "responses": {
          "200": {
            "description": "Recent alert deliveries"
          }
        }
      }
    },
    "/v1/notifications/catalog": {
      "get": {
        "summary": "Get Notification Event Catalog & Variables",
        "tags": [
          "Notifications"
        ],
        "responses": {
          "200": {
            "description": "Event catalog and template variables"
          }
        }
      }
    },
    "/v1/captcha/config": {
      "get": {
        "summary": "Get Managed CAPTCHA Configuration",
        "tags": [
          "CAPTCHA"
        ],
        "responses": {
          "200": {
            "description": "CAPTCHA config"
          }
        }
      },
      "put": {
        "summary": "Update CAPTCHA Settings",
        "tags": [
          "CAPTCHA"
        ],
        "responses": {
          "200": {
            "description": "CAPTCHA updated"
          }
        }
      }
    },
    "/v1/captcha/analytics": {
      "get": {
        "summary": "Get CAPTCHA Challenge Pass/Fail Stats & Logs",
        "tags": [
          "CAPTCHA"
        ],
        "responses": {
          "200": {
            "description": "Pass/fail analytics and challenge logs"
          }
        }
      }
    },
    "/v1/sites/{id}/captcha/keys": {
      "get": {
        "summary": "List CAPTCHA Site Keys",
        "tags": [
          "CAPTCHA"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of site keys"
          },
          "404": {
            "description": "Site not found"
          }
        }
      },
      "post": {
        "summary": "Create CAPTCHA Key Pair",
        "tags": [
          "CAPTCHA"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "label": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Key created (secret returned once)"
          },
          "404": {
            "description": "Site not found"
          }
        }
      }
    },
    "/v1/sites/{id}/captcha/keys/{siteKey}": {
      "delete": {
        "summary": "Delete CAPTCHA Key Pair",
        "tags": [
          "CAPTCHA"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "siteKey",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Key deleted"
          },
          "404": {
            "description": "Site not found"
          }
        }
      }
    },
    "/v1/tokens": {
      "get": {
        "summary": "List API Tokens",
        "tags": [
          "Tokens"
        ],
        "responses": {
          "200": {
            "description": "List of tokens without plain secrets"
          }
        }
      },
      "post": {
        "summary": "Generate New API Token",
        "tags": [
          "Tokens"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "example": "CI/CD Pipeline"
                  },
                  "scopes": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "example": [
                      "sites:read",
                      "sites:write"
                    ]
                  },
                  "ipRestrictions": {
                    "type": "string",
                    "example": "192.168.1.0/24"
                  },
                  "rateLimit": {
                    "type": "integer",
                    "default": 120
                  },
                  "expiresInDays": {
                    "type": "integer",
                    "default": 30
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Token generated (plain secret returned once)"
          }
        }
      }
    },
    "/v1/tokens/{id}": {
      "delete": {
        "summary": "Delete API Token Permanently",
        "tags": [
          "Tokens"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Token deleted"
          },
          "404": {
            "description": "Token not found"
          }
        }
      }
    },
    "/v1/tokens/{id}/revoke": {
      "post": {
        "summary": "Revoke / Deactivate API Token",
        "tags": [
          "Tokens"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Token revoked"
          },
          "404": {
            "description": "Token not found"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Token (nx_live_...)",
        "description": "Supply token via `Authorization: Bearer nx_live_...`"
      },
      "apiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Supply token via `X-API-Key: nx_live_...`"
      }
    }
  }
}