{ "openapi": "3.1.0", "info": { "title": "EdgeBalancer API", "description": "Control plane for deploying Cloudflare Worker load balancers and API gateways. All responses follow { success, data, message } format. Rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) are included on every response. API versioning: current version is v1. Deprecation will be signaled via Sunset header.", "version": "1.0.0", "contact": { "name": "EdgeBalancer", "url": "https://edge.nexoral.in/contact", "email": "support@nexoral.in" } }, "servers": [ { "url": "https://edge.nexoral.in", "description": "Production" }, { "url": "http://localhost:8000", "description": "Local development" } ], "security": [ { "cookieAuth": [] } ], "components": { "securitySchemes": { "cookieAuth": { "type": "apiKey", "in": "cookie", "name": "token", "description": "JWT httpOnly cookie set by POST /api/auth/google" } }, "schemas": { "SuccessResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": {}, "message": { "type": "string" } } }, "ErrorResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "data": { "type": "null" }, "message": { "type": "string" }, "code": { "type": "string", "description": "Machine-readable error code" } } }, "RateLimitHeaders": { "type": "object", "properties": { "X-RateLimit-Limit": { "type": "integer", "description": "Max requests in window" }, "X-RateLimit-Remaining": { "type": "integer", "description": "Remaining requests" }, "X-RateLimit-Reset": { "type": "integer", "description": "Seconds until window resets" } } }, "LoadBalancer": { "type": "object", "properties": { "_id": { "type": "string" }, "name": { "type": "string" }, "scriptName": { "type": "string" }, "domain": { "type": "string" }, "subdomain": { "type": "string" }, "strategy": { "type": "string", "enum": [ "round-robin", "weighted-round-robin", "ip-hash", "cookie-sticky", "weighted-cookie-sticky", "failover", "geo-steering" ] }, "origins": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "weight": { "type": "number" }, "isFallback": { "type": "boolean" }, "geo": { "type": "object" } } } }, "status": { "type": "string", "enum": [ "active", "paused", "inactive" ] }, "workerUrl": { "type": "string" }, "zoneId": { "type": "string" }, "placement": { "type": "object" }, "weightedEnabled": { "type": "boolean" }, "exposeRealOrigin": { "type": "boolean" }, "pathRoutes": { "type": "array" }, "pathRateLimits": { "type": "array" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "Gateway": { "type": "object", "properties": { "_id": { "type": "string" }, "name": { "type": "string" }, "scriptName": { "type": "string" }, "domain": { "type": "string" }, "subdomain": { "type": "string" }, "upstreams": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "weight": { "type": "number" } } } }, "status": { "type": "string", "enum": [ "active", "paused", "inactive" ] }, "workerUrl": { "type": "string" }, "jwt": { "type": "object" }, "caching": { "type": "object" }, "canary": { "type": "object" }, "ipRules": { "type": "object" }, "rateLimiting": { "type": "object" }, "headerTransforms": { "type": "object" }, "mockRoutes": { "type": "object" }, "pathRouting": { "type": "object" }, "cors": { "type": "object" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "Session": { "type": "object", "properties": { "_id": { "type": "string" }, "loadBalancerName": { "type": "string" }, "domain": { "type": "string" }, "subdomain": { "type": "string" }, "strategy": { "type": "string" }, "actionType": { "type": "string", "enum": [ "create", "edit" ] }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } } }, "AiRun": { "type": "object", "properties": { "_id": { "type": "string" }, "prompt": { "type": "string" }, "outcome": { "type": "string", "enum": [ "success", "failure" ] }, "message": { "type": "string" }, "model": { "type": "string" }, "provider": { "type": "string" }, "durationMs": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time" } } }, "CreateLoadBalancer": { "type": "object", "required": [ "name", "domain", "strategy", "origins" ], "properties": { "name": { "type": "string", "minLength": 3, "maxLength": 50, "description": "Lowercase + hyphens. Locked after creation." }, "domain": { "type": "string", "description": "Cloudflare zone domain" }, "subdomain": { "type": "string", "description": "Optional prefix" }, "strategy": { "type": "string", "enum": [ "round-robin", "weighted-round-robin", "ip-hash", "cookie-sticky", "weighted-cookie-sticky", "failover", "geo-steering" ] }, "origins": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" }, "weight": { "type": "number", "default": 1 }, "isFallback": { "type": "boolean", "default": false }, "geo": { "type": "object" } } } }, "placement": { "type": "object", "properties": { "smartPlacement": { "type": "boolean" }, "region": { "type": "string" } } }, "exposeRealOrigin": { "type": "boolean", "default": false } } }, "CreateGateway": { "type": "object", "required": [ "name", "domain", "upstreams" ], "properties": { "name": { "type": "string", "minLength": 3, "maxLength": 50 }, "domain": { "type": "string" }, "subdomain": { "type": "string" }, "upstreams": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" }, "weight": { "type": "number", "default": 1 } } } }, "jwt": { "type": "object" }, "caching": { "type": "object" }, "canary": { "type": "object" }, "ipRules": { "type": "object" }, "rateLimiting": { "type": "object" }, "headerTransforms": { "type": "object" }, "mockRoutes": { "type": "object" }, "pathRouting": { "type": "object" }, "cors": { "type": "object" } } }, "CloudflareCredentials": { "type": "object", "required": [ "cloudflareAccountId", "cloudflareApiToken" ], "properties": { "cloudflareAccountId": { "type": "string" }, "cloudflareApiToken": { "type": "string" } } } } }, "paths": { "/health": { "get": { "operationId": "health_get_health", "tags": [ "Health" ], "summary": "Readiness probe", "description": "Kubernetes readiness probe. Returns 200 when the service is ready to accept traffic.", "responses": { "200": { "description": "Service healthy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [] } }, "/live": { "get": { "operationId": "health_get_live", "tags": [ "Health" ], "summary": "Liveness probe", "description": "Kubernetes liveness probe. Returns 200 when the service process is alive.", "responses": { "200": { "description": "Service alive", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [] } }, "/api/auth/google": { "post": { "operationId": "auth_post_api_auth_google", "tags": [ "Auth" ], "summary": "Sign in with Google", "description": "Exchange a Firebase ID token for a JWT cookie. If 2FA is enabled, returns totpRequired/twoFactorRequired instead of setting the session cookie.", "responses": { "200": { "description": "JWT cookie set or 2FA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [] } }, "/api/auth/logout": { "post": { "operationId": "auth_post_api_auth_logout", "tags": [ "Auth" ], "summary": "Clear session", "description": "Clear the current session cookie and any 2FA challenge cookies.", "responses": { "200": { "description": "Session cleared", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/auth/me": { "get": { "operationId": "auth_get_api_auth_me", "tags": [ "Auth" ], "summary": "Get current user", "description": "Return the authenticated user's profile including subscription tier and Cloudflare connection status.", "responses": { "200": { "description": "User profile object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/auth/2fa/setup": { "post": { "operationId": "auth_post_api_auth_2fa_setup", "tags": [ "Auth" ], "summary": "Start TOTP enrollment", "description": "Generate a new TOTP device secret and QR code. The device is not active until confirmed with /2fa/confirm.", "responses": { "200": { "description": "Device enrollment data with otpauthUrl and qrDataUrl", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/auth/2fa/confirm": { "post": { "operationId": "auth_post_api_auth_2fa_confirm", "tags": [ "Auth" ], "summary": "Confirm TOTP device", "description": "Verify a TOTP code to activate a newly enrolled device.", "responses": { "200": { "description": "Device activated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/auth/2fa/remove": { "post": { "operationId": "auth_post_api_auth_2fa_remove", "tags": [ "Auth" ], "summary": "Remove TOTP device", "description": "Remove a TOTP device. Requires a code from a different confirmed device (or the last device's own code).", "responses": { "200": { "description": "Device removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/auth/2fa/verify": { "post": { "operationId": "auth_post_api_auth_2fa_verify", "tags": [ "Auth" ], "summary": "Verify TOTP code (login step 2)", "description": "Exchange a TOTP code + 2FA challenge cookie for a session cookie. This is the second step of login when 2FA is enabled.", "responses": { "200": { "description": "Session cookie set", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [] } }, "/api/auth/2fa/passkey/register/options": { "post": { "operationId": "auth_post_api_auth_2fa_passkey_register_options", "tags": [ "Auth" ], "summary": "WebAuthn registration options", "description": "Generate WebAuthn credential creation options for enrolling a new passkey.", "responses": { "200": { "description": "WebAuthn creation options", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/auth/2fa/passkey/register/verify": { "post": { "operationId": "auth_post_api_auth_2fa_passkey_register_verify", "tags": [ "Auth" ], "summary": "Verify WebAuthn registration", "description": "Verify the WebAuthn registration response and store the passkey.", "responses": { "200": { "description": "Passkey stored", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/auth/2fa/passkey/auth/options": { "post": { "operationId": "auth_post_api_auth_2fa_passkey_auth_options", "tags": [ "Auth" ], "summary": "WebAuthn authentication options", "description": "Generate WebAuthn credential request options for passkey login. Requires the 2FA challenge cookie.", "responses": { "200": { "description": "WebAuthn request options", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [] } }, "/api/auth/2fa/passkey/auth/verify": { "post": { "operationId": "auth_post_api_auth_2fa_passkey_auth_verify", "tags": [ "Auth" ], "summary": "Verify WebAuthn auth (login step 2)", "description": "Verify the WebAuthn authentication response and set the session cookie.", "responses": { "200": { "description": "Session cookie set", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [] } }, "/api/auth/2fa/passkey/remove": { "post": { "operationId": "auth_post_api_auth_2fa_passkey_remove", "tags": [ "Auth" ], "summary": "Remove a passkey", "description": "Remove a registered passkey by its credential ID.", "responses": { "200": { "description": "Passkey removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/auth/2fa/rename": { "post": { "operationId": "auth_post_api_auth_2fa_rename", "tags": [ "Auth" ], "summary": "Rename a credential", "description": "Rename a TOTP device or passkey. The name is user-chosen and displayed in the 2FA settings UI.", "responses": { "200": { "description": "Credential renamed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/auth/2fa/preference": { "post": { "operationId": "auth_post_api_auth_2fa_preference", "tags": [ "Auth" ], "summary": "Set preferred 2FA method", "description": "Set which 2FA method the login flow opens on (totp, passkey, or null for auto).", "responses": { "200": { "description": "Preference saved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/cloudflare/credentials": { "post": { "operationId": "cloudflare_post_api_cloudflare_credentials", "tags": [ "Cloudflare" ], "summary": "Save CF credentials", "description": "Store Cloudflare account ID and API token. Credentials are AES-256-GCM encrypted before MongoDB write.", "responses": { "200": { "description": "Credentials saved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloudflareCredentials" } } } } }, "put": { "operationId": "cloudflare_put_api_cloudflare_credentials", "tags": [ "Cloudflare" ], "summary": "Update CF credentials", "description": "Update the stored Cloudflare account ID and API token.", "responses": { "200": { "description": "Credentials updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloudflareCredentials" } } } } }, "get": { "operationId": "cloudflare_get_api_cloudflare_credentials", "tags": [ "Cloudflare" ], "summary": "Get masked credentials", "description": "Return the stored Cloudflare credentials with the API token masked (last 4 chars visible).", "responses": { "200": { "description": "Masked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/cloudflare/zones": { "get": { "operationId": "cloudflare_get_api_cloudflare_zones", "tags": [ "Cloudflare" ], "summary": "List CF zones", "description": "List all Cloudflare zones (domains) in the connected account.", "responses": { "200": { "description": "Array of zone objects", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/cloudflare/oauth/authorize": { "get": { "operationId": "cloudflare_get_api_cloudflare_oauth_authorize", "tags": [ "Cloudflare" ], "summary": "Start OAuth flow", "description": "Initiate Cloudflare OAuth to connect a Cloudflare account.", "responses": { "200": { "description": "OAuth redirect URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/cloudflare/oauth/callback": { "get": { "operationId": "cloudflare_get_api_cloudflare_oauth_callback", "tags": [ "Cloudflare" ], "summary": "OAuth callback", "description": "Cloudflare OAuth callback handler. Processes the authorization code and stores credentials.", "responses": { "200": { "description": "Account connected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [] } }, "/api/cloudflare/oauth/disconnect": { "post": { "operationId": "cloudflare_post_api_cloudflare_oauth_disconnect", "tags": [ "Cloudflare" ], "summary": "Disconnect OAuth", "description": "Disconnect the Cloudflare OAuth connection and clear stored credentials.", "responses": { "200": { "description": "Disconnected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/loadbalancers": { "get": { "operationId": "load_balancers_get_api_loadbalancers", "tags": [ "Load Balancers" ], "summary": "List load balancers", "description": "List all load balancers for the authenticated user. Returns an array of LoadBalancer objects.", "responses": { "200": { "description": "Array of LoadBalancer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "load_balancers_post_api_loadbalancers", "tags": [ "Load Balancers" ], "summary": "Create load balancer", "description": "Create a new load balancer. Validates hostname availability, deploys a Worker to the user's Cloudflare account, attaches the domain, and stores the config in MongoDB.", "responses": { "200": { "description": "Created LoadBalancer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateLoadBalancer" } } } } } }, "/api/loadbalancers/analytics": { "get": { "operationId": "load_balancers_get_api_loadbalancers_analytics", "tags": [ "Load Balancers" ], "summary": "Batch analytics", "description": "Return analytics data for all load balancers in a single request.", "responses": { "200": { "description": "Analytics data object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/loadbalancers/{id}": { "get": { "operationId": "load_balancers_get_api_loadbalancers_id", "tags": [ "Load Balancers" ], "summary": "Get load balancer", "description": "Return a single load balancer by ID.", "responses": { "200": { "description": "LoadBalancer object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Load balancer ID" } ] }, "put": { "operationId": "load_balancers_put_api_loadbalancers_id", "tags": [ "Load Balancers" ], "summary": "Update load balancer", "description": "Update a load balancer. Uses Cloudflare Worker Versions and Deployments for zero-downtime updates. Rolls back on failure.", "responses": { "200": { "description": "Updated LoadBalancer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateLoadBalancer" } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Load balancer ID" } ] }, "delete": { "operationId": "load_balancers_delete_api_loadbalancers_id", "tags": [ "Load Balancers" ], "summary": "Delete load balancer", "description": "Delete a load balancer. Removes the Cloudflare Worker and detaches the domain.", "responses": { "200": { "description": "Load balancer deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Load balancer ID" } ] } }, "/api/loadbalancers/validate-hostname": { "post": { "operationId": "load_balancers_post_api_loadbalancers_validate-hostname", "tags": [ "Load Balancers" ], "summary": "Preflight hostname check", "description": "Check if a hostname (domain + subdomain + name) is available before creating a load balancer.", "responses": { "200": { "description": "Availability check result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/loadbalancers/operations/{operationId}/cancel": { "post": { "operationId": "load_balancers_post_api_loadbalancers_operations_operationId_cancel", "tags": [ "Load Balancers" ], "summary": "Cancel in-flight operation", "description": "Cancel a running create or update operation. Triggers rollback of any partial changes.", "responses": { "200": { "description": "Operation cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "operationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Operation ID to cancel" } ] } }, "/api/loadbalancers/{id}/pause": { "post": { "operationId": "load_balancers_post_api_loadbalancers_id_pause", "tags": [ "Load Balancers" ], "summary": "Pause load balancer", "description": "Pause a load balancer. release-domain detaches the domain; keep-domain keeps it but serves a maintenance page.", "responses": { "200": { "description": "Load balancer paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Load balancer ID" } ] } }, "/api/loadbalancers/{id}/resume": { "post": { "operationId": "load_balancers_post_api_loadbalancers_id_resume", "tags": [ "Load Balancers" ], "summary": "Resume load balancer", "description": "Resume a paused load balancer. Re-attaches the domain and re-resolves origin IPs.", "responses": { "200": { "description": "Load balancer resumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Load balancer ID" } ] } }, "/api/loadbalancers/{id}/analytics": { "get": { "operationId": "load_balancers_get_api_loadbalancers_id_analytics", "tags": [ "Load Balancers" ], "summary": "LB analytics", "description": "Return request/error analytics for a specific load balancer.", "responses": { "200": { "description": "Analytics data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Load balancer ID" } ] } }, "/api/loadbalancers/{id}/origin-ip": { "get": { "operationId": "load_balancers_get_api_loadbalancers_id_origin-ip", "tags": [ "Load Balancers" ], "summary": "Resolve origin IPs", "description": "DNS-resolve all origin URLs to their IP addresses.", "responses": { "200": { "description": "Origin IP addresses", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Load balancer ID" } ] } }, "/api/loadbalancers/{id}/health/restart-origin": { "post": { "operationId": "health_checks_post_api_loadbalancers_id_health_restart-origin", "tags": [ "Health Checks" ], "summary": "Restart origin health", "description": "Reset the health check state for all origins of a load balancer, forcing immediate re-evaluation.", "responses": { "200": { "description": "Health check restarted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Load balancer ID" } ] } }, "/api/gateways": { "get": { "operationId": "gateways_get_api_gateways", "tags": [ "Gateways" ], "summary": "List gateways", "description": "List all API gateways for the authenticated user.", "responses": { "200": { "description": "Array of Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "gateways_post_api_gateways", "tags": [ "Gateways" ], "summary": "Create gateway", "description": "Create a new API gateway with JWT, caching, canary, IP rules, rate limiting, header transforms, mock routes, path routing, and/or CORS.", "responses": { "200": { "description": "Created Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateGateway" } } } } } }, "/api/gateways/{id}": { "get": { "operationId": "gateways_get_api_gateways_id", "tags": [ "Gateways" ], "summary": "Get gateway", "description": "Return a single gateway by ID.", "responses": { "200": { "description": "Gateway object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Gateway ID" } ] }, "put": { "operationId": "gateways_put_api_gateways_id", "tags": [ "Gateways" ], "summary": "Update gateway", "description": "Update a gateway configuration. Uses Worker Versions for zero-downtime updates.", "responses": { "200": { "description": "Updated Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateGateway" } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Gateway ID" } ] }, "delete": { "operationId": "gateways_delete_api_gateways_id", "tags": [ "Gateways" ], "summary": "Delete gateway", "description": "Delete a gateway. Removes the Cloudflare Worker and detaches the domain.", "responses": { "200": { "description": "Gateway deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Gateway ID" } ] } }, "/api/gateways/validate-hostname": { "post": { "operationId": "gateways_post_api_gateways_validate-hostname", "tags": [ "Gateways" ], "summary": "Preflight hostname check", "description": "Check if a gateway hostname is available before creating.", "responses": { "200": { "description": "Availability check", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/gateways/{id}/pause": { "post": { "operationId": "gateways_post_api_gateways_id_pause", "tags": [ "Gateways" ], "summary": "Pause gateway", "description": "Pause a gateway.", "responses": { "200": { "description": "Gateway paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Gateway ID" } ] } }, "/api/gateways/{id}/resume": { "post": { "operationId": "gateways_post_api_gateways_id_resume", "tags": [ "Gateways" ], "summary": "Resume gateway", "description": "Resume a paused gateway.", "responses": { "200": { "description": "Gateway resumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Gateway ID" } ] } }, "/api/sessions": { "get": { "operationId": "sessions_get_api_sessions", "tags": [ "Sessions" ], "summary": "List sessions", "description": "Cursor-paginated list of deployment history sessions. Filter by all, active, or inactive.", "responses": { "200": { "description": "Array of Session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "filter", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "all", "active", "inactive" ] }, "description": "Filter by active status" } ] } }, "/api/sessions/{id}/script": { "get": { "operationId": "sessions_get_api_sessions_id_script", "tags": [ "Sessions" ], "summary": "Download Worker script", "description": "Return the raw Worker JavaScript source code for a session.", "responses": { "200": { "description": "Worker JS source code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Session ID" } ] } }, "/api/ai/generate": { "post": { "operationId": "ai_agent_post_api_ai_generate", "tags": [ "AI Agent" ], "summary": "Generate with AI (SSE stream)", "description": "Send a natural language prompt to the AI agent. Returns an SSE stream with events: run_start, model_active, model_switch, status, tool_start, tool_result, done, error. Rate limit: 30 requests/15min per user.", "responses": { "200": { "description": "SSE event stream", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/ai/runs": { "get": { "operationId": "ai_agent_get_api_ai_runs", "tags": [ "AI Agent" ], "summary": "List AI runs", "description": "Cursor-paginated list of AI agent run history.", "responses": { "200": { "description": "Array of AiRun", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/ai/runs/{id}": { "get": { "operationId": "ai_agent_get_api_ai_runs_id", "tags": [ "AI Agent" ], "summary": "Get AI run", "description": "Return a single AI run with full execution steps.", "responses": { "200": { "description": "AiRun with steps", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Run ID" } ] } }, "/api/payments": { "post": { "operationId": "payments_post_api_payments", "tags": [ "Payments" ], "summary": "Create payment order", "description": "Create a Cashfree checkout session for a plan upgrade.", "responses": { "200": { "description": "Cashfree order session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/payments/webhook": { "post": { "operationId": "payments_post_api_payments_webhook", "tags": [ "Payments" ], "summary": "Cashfree webhook (no auth)", "description": "Cashfree payment webhook. Verified by HMAC signature. No authentication required.", "responses": { "200": { "description": "Webhook processed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [] } }, "/api/payments/upgrade": { "post": { "operationId": "payments_post_api_payments_upgrade", "tags": [ "Payments" ], "summary": "Create upgrade order", "description": "Create a discounted upgrade order from one plan to another.", "responses": { "200": { "description": "Upgrade order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/payments/verify": { "post": { "operationId": "payments_post_api_payments_verify", "tags": [ "Payments" ], "summary": "Verify payment status", "description": "Verify the status of a payment order. Used by jitter polling on the client.", "responses": { "200": { "description": "Payment status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/payments/history": { "get": { "operationId": "payments_get_api_payments_history", "tags": [ "Payments" ], "summary": "Payment history", "description": "Return the user's payment history.", "responses": { "200": { "description": "Array of payment records", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/stats": { "get": { "operationId": "stats_get_api_stats", "tags": [ "Stats" ], "summary": "Public stats (scaled x10)", "description": "Return public platform metrics scaled x10. Cached in Redis for 2 hours.", "responses": { "200": { "description": "Stats object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [] } }, "/api/stats/public": { "get": { "operationId": "stats_get_api_stats_public", "tags": [ "Stats" ], "summary": "Public stats (canonical path)", "description": "Canonical path for public stats. Same as GET /api/stats.", "responses": { "200": { "description": "Stats object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [] } }, "/api/user/profile": { "get": { "operationId": "user_get_api_user_profile", "tags": [ "User" ], "summary": "Get user profile", "description": "Return the authenticated user's full profile.", "responses": { "200": { "description": "User profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } } }