{ "openapi": "3.0.3", "info": { "title": "RustProxy Administration API", "version": "0.29.2", "description": "Administration API for the active panel origin. Sign in through the panel; the same-origin HttpOnly cookie authenticates all private operations. Mutations also require the exact Origin, X-RustProxy-Request: 1 and a session-bound X-CSRF-Token. Loopback HTTP is the default; Settings can enable HTTPS before using a non-loopback administration bind. This document contains no live configuration or credentials. Object schemas marked extensible are summaries: full configuration validation is authoritative in Rust." }, "servers": [ { "url": "/", "description": "This administrator origin only" } ], "security": [ { "AdminSession": [] } ], "components": { "securitySchemes": { "AdminSession": { "type": "apiKey", "in": "cookie", "name": "rustproxy_session", "description": "Sign in at the panel. Browser sends the HttpOnly cookie automatically; do not paste it into Swagger UI." }, "CsrfToken": { "type": "apiKey", "in": "header", "name": "X-CSRF-Token", "description": "Obtain from /api/auth/session. Swagger sends it automatically for allowed writes." }, "CertificateApiBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "opaque", "description": "Scoped external certificate automation token configured in Settings > Certificate API. New tokens are reload-only by default and are restricted to explicit certificate IDs; optional deploy permission must be granted explicitly. The token is identified by X-RustProxy-Certificate-Key." }, "CertificateApiKey": { "type": "apiKey", "in": "header", "name": "X-RustProxy-Certificate-Key", "description": "Non-secret Key ID paired with the scoped certificate Bearer token." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string" } }, "additionalProperties": false, "required": [ "error" ] }, "Health": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] } }, "additionalProperties": false, "required": [ "status" ] }, "AuthStatus": { "type": "object", "properties": { "setup_required": { "type": "boolean" } }, "additionalProperties": false, "required": [ "setup_required" ] }, "Login": { "type": "object", "properties": { "username": { "type": "string", "minLength": 3, "maxLength": 64 }, "password": { "type": "string", "format": "password", "writeOnly": true, "maxLength": 128 } }, "additionalProperties": false, "required": [ "username", "password" ] }, "Setup": { "type": "object", "properties": { "token": { "type": "string", "writeOnly": true, "minLength": 64, "maxLength": 64 }, "username": { "type": "string" }, "password": { "type": "string", "writeOnly": true, "format": "password", "minLength": 12, "maxLength": 128 } }, "additionalProperties": false, "required": [ "token", "username", "password" ] }, "PasswordChange": { "type": "object", "properties": { "current_password": { "type": "string", "format": "password", "writeOnly": true }, "new_password": { "type": "string", "format": "password", "writeOnly": true, "minLength": 12, "maxLength": 128 } }, "additionalProperties": false, "required": [ "current_password", "new_password" ] }, "Session": { "type": "object", "properties": { "username": { "type": "string" }, "csrf_token": { "type": "string", "readOnly": true, "description": "Session-bound CSRF token. Never store in a URL or persistent browser storage." }, "expires_at": { "type": "integer", "format": "int64" }, "idle_timeout_seconds": { "type": "integer", "format": "int64", "description": "Compatibility field equal to the current browser-session lifetime. RustProxy uses absolute expiry rather than a shorter idle timeout." }, "session_lifetime_seconds": { "type": "integer", "format": "int64", "description": "Current configured absolute browser-session lifetime." } }, "additionalProperties": false, "required": [ "username", "csrf_token", "expires_at", "idle_timeout_seconds", "session_lifetime_seconds" ] }, "HeaderRule": { "type": "object", "properties": { "op": { "type": "string", "enum": [ "set", "append", "remove" ] }, "name": { "type": "string", "maxLength": 128 }, "value": { "type": "string", "maxLength": 8192, "description": "Required for set/append; omit for remove. Literal, no variable substitution." } }, "additionalProperties": false, "required": [ "op", "name" ] }, "HeaderRules": { "type": "object", "properties": { "request": { "type": "array", "items": { "$ref": "#/components/schemas/HeaderRule" }, "maxItems": 32 }, "response": { "type": "array", "items": { "$ref": "#/components/schemas/HeaderRule" }, "maxItems": 32 } }, "additionalProperties": false }, "Acl": { "type": "object", "properties": { "default": { "type": "string", "enum": [ "allow", "deny" ] }, "rules": { "type": "array", "items": { "type": "object", "properties": { "network": { "type": "string" }, "action": { "type": "string", "enum": [ "allow", "deny" ] } }, "additionalProperties": false, "required": [ "network", "action" ] } } }, "additionalProperties": false }, "Location": { "type": "object", "properties": { "id": { "type": "string" }, "path_prefix": { "type": "string", "description": "Path prefix/exact path or Rust regex pattern, depending on match_type." }, "backend_id": { "type": "string", "nullable": true }, "enabled": { "type": "boolean" }, "cache": { "type": "boolean", "nullable": true }, "acl": { "allOf": [ { "$ref": "#/components/schemas/Acl" } ], "nullable": true }, "acl_profile_id": { "type": "string", "nullable": true, "description": "Optional reusable ACL profile; profile and inline location policies are cumulative." }, "country_access": { "$ref": "#/components/schemas/CountryAccess" }, "method_policy": { "$ref": "#/components/schemas/MethodPolicy" }, "headers": { "$ref": "#/components/schemas/HeaderRules" }, "match_type": { "type": "string", "enum": [ "prefix", "prefix_priority", "exact", "regex", "regex_insensitive" ], "default": "prefix", "description": "Nginx-style location matching: prefix, priority prefix (^~), exact (=), regex (~), or case-insensitive regex (~*)." }, "rewrite": { "type": "object", "additionalProperties": false, "properties": { "mode": { "type": "string", "enum": [ "preserve", "strip_prefix", "replace_prefix", "regex" ], "default": "preserve" }, "value": { "type": "string", "maxLength": 2048, "default": "", "description": "Replacement prefix or regex replacement. Regex replacements support $1-style capture expansion." } }, "description": "Optional upstream-path rewrite. Public cache identity remains based on the original client URL." }, "response": { "type": "object", "nullable": true, "additionalProperties": false, "properties": { "status": { "type": "integer", "minimum": 200, "maximum": 599, "default": 200 }, "content_type": { "type": "string", "maxLength": 256, "default": "text/plain; charset=utf-8" }, "body": { "type": "string", "maxLength": 65536, "default": "" } }, "description": "Local response returned by RustProxy without opening a backend connection." }, "source": { "$ref": "#/components/schemas/Source" }, "redirect": { "type": "object", "nullable": true, "additionalProperties": false, "properties": { "status": { "type": "integer", "enum": [ 301, 302, 303, 307, 308 ], "default": 302 }, "target": { "type": "string", "maxLength": 2048, "description": "Absolute HTTP(S) redirect target. Capture references are allowed only in path/query." }, "rewrite_pattern": { "type": "string", "maxLength": 1024, "nullable": true, "description": "Optional Rust regex applied to the matched request path before expanding captures in target." }, "preserve_query": { "type": "boolean", "default": true } }, "required": [ "target" ], "description": "Backend-less client redirect for this location." }, "internal": { "type": "boolean", "default": false, "description": "Internal named location excluded from public URI matching; reachable only by internal dispatch." }, "error_fallback": { "allOf": [ { "$ref": "#/components/schemas/ErrorFallback" } ], "nullable": true } }, "additionalProperties": false, "required": [ "id" ] }, "Vhost": { "type": "object", "properties": { "id": { "type": "string" }, "enabled": { "type": "boolean" }, "force_ssl": { "type": "boolean", "description": "Redirect cleartext requests for this vhost to the selected HTTPS listener using HTTP 308." }, "www_redirect": { "type": "boolean", "default": false, "description": "Claim the direct www/non-www companion of the selected exact DNS hostname and redirect it permanently to that hostname." }, "www_redirect_target": { "type": [ "string", "null" ], "description": "An exact hostname from frontend.hosts to use as the canonical redirect destination. Null uses the first hostname for compatibility. Other hostnames continue serving the same vhost without redirects." }, "forward_client_ip": { "type": "boolean", "default": true, "description": "Forward the effective client IP to the application using Forwarded, X-Forwarded-For and X-Real-IP. When false, RustProxy still uses the real client IP internally and for Tinyauth, but withholds those three headers from the backend." }, "websockets": { "type": "boolean" }, "frontend": { "type": "object", "properties": {}, "additionalProperties": true }, "backends": { "type": "array", "items": { "$ref": "#/components/schemas/VhostBackend" } }, "routes": { "type": "array", "items": { "$ref": "#/components/schemas/Location" } }, "headers": { "$ref": "#/components/schemas/HeaderRules" }, "acl": { "allOf": [ { "$ref": "#/components/schemas/Acl" } ], "nullable": true }, "method_policy": { "$ref": "#/components/schemas/MethodPolicy" }, "basic_auth": { "type": "object", "properties": {}, "additionalProperties": true }, "tinyauth": { "type": "object", "properties": {}, "additionalProperties": true }, "cache": { "type": "object", "properties": { "unsafe_force": { "type": "object", "additionalProperties": false, "properties": { "enabled": { "type": "boolean", "default": false }, "targets": { "type": "array", "maxItems": 32, "items": { "type": "string", "maxLength": 2048 } } }, "description": "Dangerous per-vhost-only request-side forced-cache target prefixes. Response privacy exclusions remain authoritative." } }, "additionalProperties": true }, "load_balancing": { "$ref": "#/components/schemas/LoadBalancingConfig" }, "certificate_id": { "type": "string", "nullable": true }, "http2_enabled": { "type": "boolean" }, "http3_enabled": { "type": "boolean" }, "tls_policy": { "type": "object", "properties": { "tls12": { "type": "boolean" }, "tls13": { "type": "boolean" }, "cipher_suites": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false, "nullable": true }, "acl_profile_id": { "type": "string", "nullable": true, "description": "Optional reusable ACL profile; profile and inline vhost/location policies are cumulative." }, "cloudflare_client_ip": { "type": "boolean", "default": false, "description": "Use verified Cloudflare client-IP and country headers only when the immediate peer is in the built-in Cloudflare edge ranges; country falls back to local GeoIP when unavailable or invalid." }, "timing_headers": { "type": "boolean", "default": false, "description": "Expose Server-Timing diagnostics for this vhost." }, "backend_header": { "type": "boolean", "default": false, "description": "Expose the selected backend ID as X-RustProxy-Backend on responses that contacted an origin. Responses served without origin contact do not report a backend." }, "backend_timing_header": { "type": "boolean", "default": false, "description": "Expose origin response-header latency as X-RustProxy-Backend-Time. Responses served without origin contact do not report an origin time." }, "websocket_rfc9220": { "type": "boolean", "default": false, "description": "Experimental RFC 9220 WebSocket Extended CONNECT over HTTP/3. Classic HTTP/1.1 Upgrade remains the default when WebSocket support is enabled." }, "websocket_legacy_support": { "type": "boolean", "default": false, "description": "Opt-in compatibility for legacy WebSocket origins. Forces classic HTTP/1.1 upstream handshakes, uses the configured backend authority as the WebSocket Host, aligns Origin to the matching backend scheme + authority, and tolerates legacy 101 response framing without weakening Sec-WebSocket-Accept validation. Ordinary HTTP is unchanged." }, "proxy_timeouts": { "$ref": "#/components/schemas/ProxyTimeouts" }, "transform": { "$ref": "#/components/schemas/TransformOverrides" }, "websocket_rfc8441": { "type": "boolean", "default": false, "description": "RFC 8441 WebSocket Extended CONNECT over HTTP/2. Independent opt-in alongside classic HTTP/1.1 Upgrade; requires WebSocket support and an H2-capable selected listener." }, "source": { "$ref": "#/components/schemas/Source" }, "compression": { "$ref": "#/components/schemas/CompressionOverrides" }, "error_fallback": { "allOf": [ { "$ref": "#/components/schemas/ErrorFallback" } ], "nullable": true, "description": "Error fallback for the main vhost source." } }, "additionalProperties": true, "required": [ "id", "frontend" ] }, "Config": { "type": "object", "properties": { "vhosts": { "type": "array", "items": { "$ref": "#/components/schemas/Vhost" } }, "listeners": { "type": "object", "properties": {}, "additionalProperties": true }, "http2": { "description": "Legacy HTTP/2 lifecycle fallback for listeners that do not define binding.http2_settings. Prefer listener-scoped settings in config.listeners.", "allOf": [ { "$ref": "#/components/schemas/Http2ConnectionSettings" } ] }, "streams": { "type": "array", "maxItems": 128, "items": { "$ref": "#/components/schemas/StreamHost" } }, "tls": { "type": "object", "properties": {}, "additionalProperties": true }, "cache": { "$ref": "#/components/schemas/CacheSettings" }, "compression": { "$ref": "#/components/schemas/CompressionSettings" }, "headers": { "$ref": "#/components/schemas/HeaderRules" }, "server_header": { "type": "object", "properties": {}, "additionalProperties": true }, "diagnostic_headers": { "type": "object", "properties": {}, "additionalProperties": true }, "forwarding": { "type": "object", "properties": {}, "additionalProperties": true }, "pages": { "type": "object", "properties": {}, "additionalProperties": true }, "prometheus": { "$ref": "#/components/schemas/PrometheusSettings" }, "geoip_updates": { "$ref": "#/components/schemas/GeoIpUpdateSettings" }, "host_policies": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "administration": { "type": "object", "properties": { "listen": { "type": "string", "nullable": true, "description": "Administration listen socket. Listener changes require restart." }, "tls": { "type": "boolean", "default": false }, "certificate_id": { "type": "string", "nullable": true }, "allowed_hosts": { "type": "array", "items": { "type": "string" } }, "session_days": { "type": "integer", "minimum": 7, "maximum": 30, "default": 30, "description": "Absolute browser administrator-session lifetime in days. Applies immediately and does not require restart." } }, "additionalProperties": false }, "logging": { "type": "object", "additionalProperties": true, "properties": { "file": { "type": "object", "additionalProperties": false, "properties": { "enabled": { "type": "boolean", "default": false }, "path": { "type": "string", "default": "/var/log/rustproxy/access.jsonl" }, "per_vhost": { "type": "boolean", "default": false, "description": "Write each vhost to a separate JSONL file instead of the combined file." }, "directory": { "type": "string", "default": "/var/log/rustproxy/vhosts", "description": "Directory used when per_vhost is enabled." } } }, "logstash": { "type": "object", "additionalProperties": true }, "loki": { "type": "object", "additionalProperties": true }, "format": { "type": "object", "additionalProperties": true }, "capture_user_agent": { "type": "boolean", "default": true, "description": "Capture a bounded User-Agent string in access logs and traffic analytics." }, "capture_country": { "type": "boolean", "default": false, "description": "Resolve country from GeoIP for access logs and traffic analytics. Disabled by default to avoid per-request GeoIP work unless country policy/rate-limit already requires it." } } }, "acl_profiles": { "type": "array", "items": { "$ref": "#/components/schemas/AclProfile" } }, "redirects": { "type": "array", "maxItems": 64, "items": { "$ref": "#/components/schemas/RedirectHost" } }, "not_found_hosts": { "type": "array", "maxItems": 64, "items": { "$ref": "#/components/schemas/NotFoundHost" } }, "docker_agents": { "$ref": "#/components/schemas/DockerSettings" }, "transform": { "$ref": "#/components/schemas/TransformSettings" }, "error_log": { "type": "object", "additionalProperties": false, "properties": { "enabled": { "type": "boolean", "default": false }, "path": { "type": "string", "default": "/var/log/rustproxy/error.log", "maxLength": 1024 }, "format": { "type": "string", "enum": [ "JSON", "RAW" ], "default": "JSON" } }, "description": "Optional asynchronous ERROR-only file sink. Rotation and retention are handled externally by logrotate." }, "web_services": { "type": "array", "maxItems": 128, "items": { "$ref": "#/components/schemas/WebService" } } }, "additionalProperties": true }, "Envelope": { "type": "object", "properties": { "revision": { "type": "integer", "format": "int64" }, "config": { "$ref": "#/components/schemas/Config" } }, "additionalProperties": false, "required": [ "revision", "config" ] }, "Update": { "type": "object", "properties": { "expected_revision": { "type": "integer", "format": "int64" }, "config": { "$ref": "#/components/schemas/Config" } }, "additionalProperties": false, "required": [ "expected_revision", "config" ] }, "CertificateUpload": { "type": "object", "properties": { "cert_pem": { "type": "string" }, "key_pem": { "type": "string", "writeOnly": true, "description": "Private key PEM; never returned by this endpoint." }, "hosts": { "type": "array", "items": { "type": "string" }, "minItems": 1 } }, "additionalProperties": false, "required": [ "cert_pem", "key_pem", "hosts" ] }, "BasicHash": { "type": "object", "properties": { "username": { "type": "string" }, "password": { "type": "string", "writeOnly": true, "format": "password", "minLength": 12, "maxLength": 128 } }, "additionalProperties": false, "required": [ "username", "password" ] }, "HashedUser": { "type": "object", "properties": { "username": { "type": "string" }, "password_hash": { "type": "string", "readOnly": true } }, "additionalProperties": false, "required": [ "username", "password_hash" ] }, "RenewRequest": { "type": "object", "properties": { "certificate_id": { "type": "string" }, "dry_run": { "type": "boolean", "default": false } }, "additionalProperties": false, "required": [ "certificate_id" ] }, "AcmeIssue": { "type": "object", "properties": { "certificate_id": { "type": "string" }, "provider": { "type": "string", "enum": [ "http01", "cloudflare", "ovh", "rfc2136" ] }, "domains": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "email": { "type": "string" }, "environment": { "type": "string", "enum": [ "staging", "production" ], "default": "staging" }, "agree_tos": { "type": "boolean" }, "confirm_production": { "type": "boolean" }, "api_token": { "type": "string", "writeOnly": true }, "application_key": { "type": "string", "writeOnly": true }, "application_secret": { "type": "string", "writeOnly": true }, "consumer_key": { "type": "string", "writeOnly": true }, "key_secret": { "type": "string", "writeOnly": true } }, "additionalProperties": true, "required": [ "certificate_id", "domains", "email", "agree_tos" ] }, "Status": { "type": "object", "properties": { "version": { "type": "string" }, "project": { "type": "string" }, "runtime": { "$ref": "#/components/schemas/RuntimeInformation" }, "uptime_seconds": { "type": "integer", "format": "int64" }, "revision": { "type": "integer", "format": "int64" }, "listeners": { "type": "object", "properties": {}, "additionalProperties": true }, "metrics": { "type": "object", "properties": {}, "additionalProperties": true }, "transform_metrics": { "type": "object", "properties": {}, "additionalProperties": true }, "transform_resources": { "type": "object", "properties": { "memory_reserved_bytes": { "type": "integer", "format": "int64" }, "memory_budget_bytes": { "type": "integer", "format": "int64" }, "inflight": { "type": "integer", "format": "int64" }, "max_inflight": { "type": "integer", "format": "int64" } }, "additionalProperties": false }, "memory_accounting": { "type": "object", "properties": { "process_rss_bytes": { "type": "integer", "format": "int64", "nullable": true }, "cache_hot_bytes": { "type": "integer", "format": "int64" }, "cache_hot_limit_bytes": { "type": "integer", "format": "int64" }, "cache_transient_bytes": { "type": "integer", "format": "int64" }, "cache_transient_limit_bytes": { "type": "integer", "format": "int64" }, "cache_total_bytes": { "type": "integer", "format": "int64" }, "transform_reserved_bytes": { "type": "integer", "format": "int64" }, "transform_budget_bytes": { "type": "integer", "format": "int64" }, "transform_inflight": { "type": "integer", "format": "int64" }, "transform_max_inflight": { "type": "integer", "format": "int64" }, "non_cache_rss_bytes": { "type": "integer", "format": "int64", "nullable": true }, "non_cache_rss_includes_transform": { "type": "boolean" }, "method": { "type": "string" } }, "additionalProperties": false }, "cache": { "type": "object", "properties": {}, "additionalProperties": true }, "system": { "type": "object", "properties": {}, "additionalProperties": true }, "backend_pools": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "administration": { "type": "object", "properties": {}, "additionalProperties": true }, "logging": { "type": "object", "properties": {}, "additionalProperties": true }, "tls": { "type": "object", "properties": {}, "additionalProperties": true }, "streams": { "type": "object", "properties": { "active": { "type": "array", "items": { "$ref": "#/components/schemas/StreamHost" } }, "desired": { "type": "array", "items": { "$ref": "#/components/schemas/StreamHost" } }, "restart_required": { "type": "boolean" }, "metrics": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/StreamMetrics" } } }, "required": [ "active", "desired", "restart_required", "metrics" ], "additionalProperties": false, "description": "Startup-active and desired TCP/UDP streams plus fixed-cardinality runtime counters." }, "backend_pool_domains": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Configured Docker runtime pool IDs mapped to their primary proxied hostname." }, "software_update": { "type": "object", "properties": { "current_version": { "type": "string" }, "latest_version": { "type": "string", "nullable": true }, "update_available": { "type": "boolean" }, "repository_url": { "type": "string", "format": "uri", "nullable": true } }, "required": [ "current_version", "latest_version", "update_available", "repository_url" ], "additionalProperties": false, "description": "Fail-soft release-check state. A failed check leaves the previous successful state unchanged." } }, "additionalProperties": true }, "Object": { "type": "object", "properties": {}, "additionalProperties": true }, "Logs": { "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "capacity": { "type": "integer", "format": "int64", "description": "Number of completed requests retained in the in-memory access ring." }, "window": { "type": "integer", "format": "int64", "description": "Default live snapshot size." }, "dropped": { "type": "integer", "format": "int64" } }, "additionalProperties": false }, "Audit": { "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "capacity": { "type": "integer", "format": "int64" } }, "additionalProperties": false }, "Cache": { "type": "object", "properties": { "settings": { "type": "object", "properties": {}, "additionalProperties": true }, "metrics": { "type": "object", "properties": {}, "additionalProperties": true }, "vhosts": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "dashboard": { "type": "object", "properties": {}, "additionalProperties": true }, "bans": { "type": "array", "items": { "$ref": "#/components/schemas/CacheBan" } } }, "additionalProperties": false }, "MethodPolicy": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "off", "allow", "block" ], "default": "off" }, "methods": { "type": "array", "maxItems": 32, "items": { "type": "string", "maxLength": 32 }, "default": [] } }, "additionalProperties": false, "description": "HTTP method policy. allow permits only listed methods; block rejects listed methods." }, "CountryAccess": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "off", "block", "allow" ], "default": "off" }, "countries": { "type": "array", "maxItems": 128, "items": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "default": [] } }, "additionalProperties": false, "description": "Country access policy evaluated against the verified effective client IP." }, "AclProfile": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "acl": { "allOf": [ { "$ref": "#/components/schemas/Acl" } ], "nullable": true }, "country_access": { "$ref": "#/components/schemas/CountryAccess" } }, "additionalProperties": false, "required": [ "id", "name" ] }, "StreamHost": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "name": { "type": "string", "maxLength": 96 }, "enabled": { "type": "boolean" }, "protocol": { "type": "string", "enum": [ "tcp", "udp" ] }, "listen": { "type": "string", "description": "Dedicated TCP/UDP listener as IP:port." }, "upstream": { "type": "string", "description": "Single raw upstream as IP:port." }, "connect_timeout_seconds": { "type": "integer", "minimum": 1, "maximum": 300 }, "idle_timeout_seconds": { "type": "integer", "minimum": 1, "maximum": 86400 }, "max_connections": { "type": "integer", "minimum": 1, "maximum": 65535 } }, "required": [ "id", "protocol", "listen", "upstream" ], "additionalProperties": false, "description": "Layer-4 stream host. It bypasses the HTTP vhost/ACL/cache/header/compression pipeline." }, "StreamMetrics": { "type": "object", "properties": { "sessions_total": { "type": "integer", "format": "int64", "minimum": 0 }, "sessions_completed": { "type": "integer", "format": "int64", "minimum": 0 }, "active": { "type": "integer", "format": "int64", "minimum": 0 }, "rejected": { "type": "integer", "format": "int64", "minimum": 0 }, "errors": { "type": "integer", "format": "int64", "minimum": 0 }, "bytes_in": { "type": "integer", "format": "int64", "minimum": 0 }, "bytes_out": { "type": "integer", "format": "int64", "minimum": 0 }, "packets_in": { "type": "integer", "format": "int64", "minimum": 0 }, "packets_out": { "type": "integer", "format": "int64", "minimum": 0 } }, "additionalProperties": false, "description": "Monotonic Layer-4 counters for one startup-active stream. active is a gauge." }, "ConfigSectionUpdate": { "type": "object", "properties": { "expected_revision": { "type": "integer", "format": "int64", "description": "Revision returned by the latest GET /api/config." }, "value": { "description": "Complete value of the selected configuration section. This is a section replacement, not a merge patch." } }, "additionalProperties": false, "required": [ "expected_revision", "value" ] }, "CacheSettings": { "type": "object", "description": "Shared hot/cold cache settings. Idle age, maximum hot-tier age, LRU eviction and graceful shutdown can independently demote objects to disk.", "properties": { "enabled": { "type": "boolean", "default": true }, "memory_preset": { "type": "string", "nullable": true, "enum": [ "conservative", "recommended", "performance" ], "description": "Last cache memory sizing preset explicitly selected in Settings. Numeric limits remain authoritative." }, "max_bytes": { "type": "integer", "format": "int64", "minimum": 65536, "default": 268435456, "description": "Hard HOT RAM budget charged by retained body allocation plus entry metadata." }, "max_object_bytes": { "type": "integer", "format": "int64", "minimum": 1024, "default": 16777216, "description": "Maximum logical response body accepted by one cache fill." }, "max_entries": { "type": "integer", "minimum": 1, "maximum": 16384 }, "transient_max_bytes": { "type": "integer", "format": "int64", "minimum": 65536, "default": 67108864, "description": "Hard byte budget for in-progress fills and full bodies moving between HOT and COLD." }, "cold_queue_max_bytes": { "type": "integer", "format": "int64", "minimum": 65536, "default": 33554432, "description": "Byte ceiling for demoted objects waiting for the COLD writer. Must not exceed transient_max_bytes." }, "hot_eviction_max_objects": { "type": "integer", "minimum": 1, "maximum": 4096, "default": 64, "description": "Maximum LRU removals attempted to make room for one HOT admission." }, "cold_enabled": { "type": "boolean", "default": false }, "cold_preset": { "type": "string", "nullable": true, "enum": [ "recommended" ], "description": "Last COLD policy preset explicitly selected in Settings." }, "cold_path": { "type": "string", "default": "cache/cold" }, "cold_max_bytes": { "type": "integer", "format": "int64", "minimum": 65536 }, "cold_max_entries": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "cold_after_seconds": { "type": "integer", "minimum": 5, "maximum": 604800, "default": 300 }, "cold_on_idle": { "type": "boolean", "default": true, "description": "Move objects idle for cold_after_seconds from hot RAM to cold storage." }, "cold_on_lru": { "type": "boolean", "default": true, "description": "Move objects evicted by the hot LRU/budget to cold storage." }, "cold_on_shutdown": { "type": "boolean", "default": true, "description": "Best-effort flush of remaining hot objects to cold storage during graceful shutdown/restart." }, "default_ttl_seconds": { "type": "integer", "minimum": 0, "maximum": 604800 }, "max_ttl_seconds": { "type": "integer", "minimum": 1, "maximum": 604800 }, "bypass_query": { "type": "boolean" }, "bypass_prefixes": { "type": "array", "items": { "type": "string" }, "maxItems": 64 }, "static_ignore_cookies": { "type": "boolean" }, "static_extensions": { "type": "array", "items": { "type": "string" }, "maxItems": 64 }, "expose_status": { "type": "boolean" }, "expose_hits": { "type": "boolean" }, "expose_cache_status": { "type": "boolean" }, "expose_resident_age": { "type": "boolean" }, "via_header": { "type": "string", "nullable": true, "maxLength": 256, "default": "RustProxy", "description": "Optional response Via field value appended by RustProxy cache handling. Null disables the header. This response-only setting does not invalidate cached objects." }, "cold_max_hot_seconds": { "type": "integer", "minimum": 5, "maximum": 2592000, "default": 3600, "description": "Maximum total RAM residency before age-based demotion when cold_on_age is enabled." }, "cold_on_age": { "type": "boolean", "default": false, "description": "Move objects to cold storage after cold_max_hot_seconds even when they are still being accessed." }, "cold_gc_interval_seconds": { "type": "integer", "minimum": 5, "maximum": 86400, "default": 60, "description": "Automatic cold-cache GC interval." }, "cold_gc_max_delete": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 256, "description": "Maximum objects removed by one automatic GC pass." }, "collapse_enabled": { "type": "boolean", "default": true, "description": "Collapse concurrent foreground fills for the same cache key." }, "collapse_wait_timeout_ms": { "type": "integer", "minimum": 10, "maximum": 60000, "default": 1500 }, "collapse_timeout_fallback": { "type": "string", "enum": [ "origin", "stale_if_available" ], "default": "origin" }, "stale_if_error_timeout": { "type": "boolean", "default": true }, "stale_if_error_connection": { "type": "boolean", "default": true }, "stale_if_error_dns": { "type": "boolean", "default": true }, "stale_if_error_tls": { "type": "boolean", "default": true }, "stale_if_error_statuses": { "type": "array", "maxItems": 32, "items": { "type": "integer", "minimum": 500, "maximum": 599 }, "default": [ 500, 502, 503, 504 ] }, "proactive_refresh_enabled": { "type": "boolean", "default": false }, "proactive_refresh_before_expiry_seconds": { "type": "integer", "minimum": 1, "maximum": 604800, "default": 15 }, "proactive_refresh_percent": { "type": "integer", "minimum": 0, "maximum": 100, "default": 10 }, "proactive_refresh_max_inflight": { "type": "integer", "minimum": 1, "maximum": 64, "default": 4 }, "hot_auto_trim_enabled": { "type": "boolean", "default": true, "description": "When HOT exceeds the configured target, periodically remove only sufficiently idle objects in bounded passes." }, "hot_auto_trim_after_seconds": { "type": "integer", "minimum": 5, "maximum": 86400, "default": 300, "description": "Minimum idle age before an object is eligible for automatic HOT trimming." }, "hot_auto_trim_target_percent": { "type": "integer", "minimum": 10, "maximum": 95, "default": 80, "description": "HOT usage waterline targeted by automatic idle trimming." } }, "additionalProperties": false }, "VhostBackend": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string", "description": "HTTP(S) origin URL without path/query/fragment." }, "weight": { "type": "integer", "minimum": 1, "maximum": 256 }, "max_concurrent_requests": { "type": "integer", "minimum": 0, "maximum": 1000000, "default": 0, "description": "Maximum number of complete proxy exchanges assigned to this backend. Zero means unlimited." }, "queue_timeout_ms": { "type": "integer", "minimum": 0, "maximum": 60000, "default": 0, "description": "Maximum time to wait for backend request capacity before returning HTTP 503. Zero rejects immediately." }, "enabled": { "type": "boolean" }, "pool_eligible": { "type": "boolean" }, "backup": { "type": "boolean" }, "drain": { "type": "boolean" }, "allow_private": { "type": "boolean" }, "preserve_host": { "type": "boolean", "default": true }, "protocol": { "type": "string", "enum": [ "http1", "http2", "auto" ], "default": "http1" }, "address_allowlist": { "type": "array", "items": { "type": "string" } }, "tls_server_name": { "type": "string", "nullable": true, "description": "DNS name used for TLS SNI/certificate identity when it differs from the connection target. Must not be an IP address." }, "tls_verify": { "type": "boolean", "default": false, "description": "For HTTPS origins, validate the certificate chain and hostname when explicitly enabled. Disabled when omitted; TLS encryption still applies and backend address/DNS protections remain active." }, "tls_ca_pem": { "type": "string", "nullable": true, "description": "Additional private CA PEM used only when tls_verify=true." }, "accept_local_listener_risk": { "type": "boolean", "default": false, "description": "Explicitly allow this backend to resolve to a local RustProxy listener, including a listener using port 9090. This can create a proxy loop or expose the administration plane. Loopback/private targets still require allow_private=true." } }, "additionalProperties": true, "required": [ "id", "url" ] }, "CertificateInventoryEntry": { "type": "object", "properties": { "id": { "type": "string" }, "hosts": { "type": "array", "items": { "type": "string" }, "description": "Active/configured SNI bindings." }, "covered_hosts": { "type": "array", "items": { "type": "string" }, "description": "DNS SubjectAltName values extracted from the leaf certificate. Inventory inspects the configured public certificate PEM so in-place renewals are reflected immediately, falling back to persisted upload/ACME metadata only if the file cannot be read. Empty when the certificate contains no DNS SANs or coverage is unavailable." }, "cert_file": { "type": "string" }, "key_file": { "type": "string" }, "issuer": { "type": "object", "nullable": true, "additionalProperties": true }, "certificate_issuer": { "type": "string", "nullable": true, "description": "Issuer distinguished name parsed from the current leaf certificate." }, "not_before": { "type": "string", "nullable": true, "description": "Certificate notBefore value normalized as an ISO-like timestamp." }, "not_after": { "type": "string", "nullable": true, "description": "Certificate notAfter value normalized as an ISO-like timestamp." }, "not_before_unix": { "type": "integer", "format": "int64", "nullable": true }, "not_after_unix": { "type": "integer", "format": "int64", "nullable": true }, "days_remaining": { "type": "integer", "format": "int64", "nullable": true }, "expiry_status": { "type": "string", "enum": [ "ok", "warning", "expired", "unknown" ] }, "renewal": { "nullable": true }, "renewal_status": { "type": "string", "nullable": true }, "last_renewal_attempt": { "type": "integer", "format": "int64", "nullable": true }, "last_renewal_error": { "type": "string", "nullable": true }, "default": { "type": "boolean" }, "assigned_vhosts": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "additionalProperties": false, "required": [ "id", "hosts", "covered_hosts", "cert_file", "key_file", "default", "assigned_vhosts", "certificate_issuer", "not_before", "not_after", "not_before_unix", "not_after_unix", "days_remaining", "expiry_status", "renewal_status", "last_renewal_attempt", "last_renewal_error" ] }, "CertificateInventory": { "type": "object", "properties": { "revision": { "type": "integer", "format": "int64" }, "certificates": { "type": "array", "items": { "$ref": "#/components/schemas/CertificateInventoryEntry" } }, "acme": { "type": "boolean" }, "providers": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false, "required": [ "revision", "certificates", "acme", "providers" ] }, "StagedCertificate": { "type": "object", "properties": { "issuer": { "type": "object", "nullable": true, "additionalProperties": true }, "id": { "type": "string" }, "covered_hosts": { "type": "array", "items": { "type": "string" } }, "hosts": { "type": "array", "items": { "type": "string" } }, "cert_file": { "type": "string" }, "key_file": { "type": "string" } }, "additionalProperties": false, "required": [ "id", "covered_hosts", "hosts", "cert_file", "key_file" ] }, "CertificateUploadResult": { "type": "object", "properties": { "certificate": { "$ref": "#/components/schemas/StagedCertificate" }, "staged": { "type": "boolean" } }, "additionalProperties": false, "required": [ "certificate", "staged" ] }, "RedirectRule": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "enabled": { "type": "boolean", "default": true }, "source_scheme": { "type": "string", "enum": [ "any", "http", "https" ], "default": "any" }, "match_type": { "type": "string", "enum": [ "prefix", "exact" ], "default": "prefix" }, "path_prefix": { "type": "string", "default": "/" }, "target_type": { "type": "string", "enum": [ "url", "host", "path" ], "default": "url" }, "target": { "type": "string", "maxLength": 2048 }, "target_scheme": { "type": "string", "enum": [ "preserve", "http", "https" ], "default": "preserve", "description": "Used by target_type=host." }, "path_mode": { "type": "string", "enum": [ "append", "strip_prefix", "replace" ], "default": "append" }, "query_mode": { "type": "string", "enum": [ "preserve", "drop" ], "default": "preserve" }, "status_code": { "type": "integer", "enum": [ 301, 302, 303, 307, 308 ], "default": 308 }, "cache_seconds": { "type": "integer", "minimum": 0, "maximum": 31536000, "default": 0 } }, "required": [ "id", "target" ] }, "RedirectHost": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "name": { "type": "string", "maxLength": 96 }, "enabled": { "type": "boolean", "default": true }, "http2_enabled": { "type": "boolean", "default": true }, "http3_enabled": { "type": "boolean", "default": true }, "frontend": { "type": "object", "additionalProperties": false, "properties": { "hosts": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "listener_ids": { "type": "array", "minItems": 1, "maxItems": 16, "items": { "type": "string" } } }, "required": [ "hosts", "listener_ids" ] }, "certificate_id": { "type": "string", "nullable": true }, "rules": { "type": "array", "maxItems": 64, "items": { "$ref": "#/components/schemas/RedirectRule" } } }, "required": [ "id", "frontend" ] }, "LocalResponsePage": { "type": "object", "additionalProperties": false, "properties": { "kind": { "type": "string", "enum": [ "welcome", "empty", "html" ], "default": "welcome" }, "status": { "type": "integer", "nullable": true, "description": "Local HTTP response status for a 404 Host. Final application statuses 200..599 are supported; 204, 205 and 304 require empty mode.", "minimum": 200, "maximum": 599 }, "html": { "type": "string", "maxLength": 32768, "default": "" } } }, "NotFoundHost": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "name": { "type": "string", "maxLength": 96 }, "enabled": { "type": "boolean", "default": true }, "http2_enabled": { "type": "boolean", "default": true }, "http3_enabled": { "type": "boolean", "default": true }, "frontend": { "type": "object", "additionalProperties": false, "properties": { "hosts": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "listener_ids": { "type": "array", "minItems": 1, "maxItems": 16, "items": { "type": "string" } } }, "required": [ "hosts", "listener_ids" ] }, "certificate_id": { "type": "string", "nullable": true }, "page": { "$ref": "#/components/schemas/LocalResponsePage" } }, "required": [ "id", "frontend" ] }, "GeoIpUpdateSettings": { "type": "object", "additionalProperties": false, "properties": { "enabled": { "type": "boolean", "default": true }, "format": { "type": "string", "enum": [ "csv_pair", "mmdb" ], "default": "csv_pair", "description": "GeoIP database format. csv_pair uses separate IPv4/IPv6 range files; mmdb uses one native MaxMind DB file." }, "ipv4_url": { "type": "string", "format": "uri", "default": "https://github.com/sapics/ip-location-db/releases/download/latest/user-country-ipv4.csv", "description": "Direct HTTPS URL for the IPv4 CSV database." }, "ipv6_url": { "type": "string", "format": "uri", "default": "https://github.com/sapics/ip-location-db/releases/download/latest/user-country-ipv6.csv", "description": "Direct HTTPS URL for the IPv6 CSV database." }, "mmdb_url": { "type": "string", "default": "https://github.com/sapics/ip-location-db/releases/download/latest/user-country.mmdb", "description": "Direct HTTPS URL for a native MaxMind DB. May be empty only when MMDB automatic updates are disabled and country.mmdb is managed locally." }, "ipv4_checksum_url": { "type": "string", "format": "uri", "nullable": true, "default": null, "description": "Optional HTTPS URL containing the publisher SHA-256 for the IPv4 CSV." }, "ipv6_checksum_url": { "type": "string", "format": "uri", "nullable": true, "default": null, "description": "Optional HTTPS URL containing the publisher SHA-256 for the IPv6 CSV." }, "mmdb_checksum_url": { "type": "string", "format": "uri", "nullable": true, "default": null, "description": "Optional HTTPS URL containing the publisher SHA-256 for the MMDB file." }, "max_bytes": { "type": "integer", "format": "int64", "minimum": 1048576, "maximum": 268435456, "default": 268435456 }, "interval_seconds": { "type": "integer", "format": "int64", "minimum": 60, "maximum": 2678400, "default": 86400 }, "release_url": { "type": "string", "format": "uri", "nullable": true, "deprecated": true, "description": "Legacy release base URL accepted for migration from pre-direct-source GeoIP settings." }, "checksum_url": { "type": "string", "format": "uri", "nullable": true, "deprecated": true, "description": "Legacy checksum base URL accepted for migration. The former sapics checksum default is migrated to optional/no publisher checksum." } }, "required": [ "enabled", "format", "ipv4_url", "ipv6_url", "mmdb_url", "ipv4_checksum_url", "ipv6_checksum_url", "mmdb_checksum_url", "max_bytes", "interval_seconds" ] }, "PrometheusSettings": { "type": "object", "additionalProperties": false, "properties": { "enabled": { "type": "boolean", "default": false }, "listen": { "type": "string", "default": "127.0.0.1:9191" }, "path": { "type": "string", "default": "/metrics", "pattern": "^/" }, "allowed_cidrs": { "type": "array", "minItems": 1, "maxItems": 32, "items": { "type": "string" }, "default": [ "127.0.0.0/8", "::1/128" ], "description": "Matched against the actual transport peer. Forwarded headers are ignored." }, "bearer_token_env": { "type": "string", "nullable": true, "description": "Environment-variable name only; the token value is never stored in configuration." }, "allow_trusted_network_without_token": { "type": "boolean", "default": false, "description": "Allow an actual peer already matched by allowed_cidrs to scrape without a bearer token. Explicit /0 CIDRs are rejected when enabled." }, "include_system": { "type": "boolean", "default": true }, "include_vhosts": { "type": "boolean", "default": true }, "include_traffic": { "type": "boolean", "default": true, "description": "Export bounded Traffic analytics aggregates. Raw client IPs, request paths and full User-Agent strings are intentionally excluded." }, "include_backends": { "type": "boolean", "default": true }, "include_docker_vhosts": { "type": "boolean", "default": true, "description": "Export Docker discovery/vhost/backend metrics under the dedicated rust_proxy_docker_* metric families." }, "include_cache_domains": { "type": "boolean", "default": true }, "include_streams": { "type": "boolean", "default": true }, "include_logging": { "type": "boolean", "default": true } } }, "DockerAssignment": { "type": "object", "additionalProperties": false, "properties": { "service_key": { "type": "string", "maxLength": 256 }, "hostname": { "type": "string", "maxLength": 253, "description": "Primary Docker vhost name. A single DNS label is expanded under the agent base_domain; an FQDN is used as-is." }, "aliases": { "type": "array", "items": { "type": "string", "maxLength": 253 }, "description": "Additional labels or FQDN aliases for the same dynamic vhost." }, "target_ip": { "type": "string", "nullable": true, "description": "Optional per-service Docker host IP. When unset, the agent default or automatic binding/address selection is used." }, "enabled": { "type": "boolean", "default": true }, "scheme": { "type": "string", "enum": [ "http", "https" ], "default": "http" }, "preserve_host": { "type": "boolean", "default": true }, "force_ssl": { "type": "boolean", "nullable": true, "default": true, "description": "Per-app HTTP to HTTPS redirect. New dashboard assignments default to true; null preserves the pre-0.18.8 behavior for assignments saved before this switch existed." }, "websockets": { "type": "boolean", "default": true, "description": "Enable classic HTTP/1.1 WebSocket Upgrade forwarding for this generated Docker vhost." }, "cache_enabled": { "type": "boolean", "default": false, "description": "Enable the normal RustProxy cache policy for this generated Docker vhost." }, "health_check": { "$ref": "#/components/schemas/DockerHealthCheck" }, "passive_health": { "$ref": "#/components/schemas/PassiveHealthConfig", "description": "Passive backend health is opt-in and defaults to disabled." }, "acl_profile_id": { "type": "string", "nullable": true, "description": "Optional reusable ACL profile. Profile and inline ACL are cumulative." }, "acl": { "allOf": [ { "$ref": "#/components/schemas/Acl" } ], "nullable": true }, "proxy_timeouts": { "$ref": "#/components/schemas/ProxyTimeouts" }, "transform_enabled": { "type": "boolean", "default": false, "description": "Enable the configured static-response transform engine for the generated Docker vhost. Global transform must also be enabled." }, "compression_enabled": { "type": "boolean", "nullable": true, "default": null, "description": "Single per-Docker-vhost dynamic compression switch. null inherits the global policy; true/false enables or disables compression for this publication. Codec availability and priority come from global Response settings." }, "compression_zstd": { "type": "boolean", "nullable": true, "default": null, "description": "Legacy compatibility field accepted when loading older 0.27.0 pre-release configuration. Ignored for Docker vhosts; Zstandard availability is controlled by global Response settings.", "deprecated": true }, "compression_br": { "type": "boolean", "nullable": true, "default": null, "description": "Legacy compatibility field accepted when loading older 0.27.0 pre-release configuration. Ignored for Docker vhosts; Brotli availability is controlled by global Response settings.", "deprecated": true }, "compression_gzip": { "type": "boolean", "nullable": true, "default": null, "description": "Legacy compatibility field accepted when loading older 0.27.0 pre-release configuration. Ignored for Docker vhosts; gzip availability is controlled by global Response settings.", "deprecated": true }, "compression_deflate": { "type": "boolean", "nullable": true, "default": null, "description": "Legacy compatibility field accepted when loading older 0.27.0 pre-release configuration. Ignored for Docker vhosts; deflate availability is controlled by global Response settings.", "deprecated": true } }, "required": [ "service_key", "hostname" ] }, "DockerAgent": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "maxLength": 64 }, "name": { "type": "string", "maxLength": 96 }, "enabled": { "type": "boolean", "default": true }, "endpoint": { "type": "string", "format": "uri", "description": "Base HTTP(S) URL of the standalone RustProxy Docker Agent." }, "token": { "type": "string", "minLength": 24, "maxLength": 512, "description": "Bearer token shared only with this Docker agent." }, "base_domain": { "type": "string", "description": "Per-agent DNS suffix such as docker1.lab.local. Short Docker vhost names are expanded below this domain; full FQDNs may use any operator-controlled domain." }, "default_target_ip": { "type": "string", "nullable": true, "description": "Optional default Docker host IPv4/IPv6 address. A Docker vhost can override this per service." }, "listener_ids": { "type": "array", "maxItems": 16, "items": { "type": "string" } }, "assignments": { "type": "array", "maxItems": 128, "items": { "$ref": "#/components/schemas/DockerAssignment" } }, "tls_fingerprint_sha256": { "type": "string", "nullable": true, "minLength": 64, "maxLength": 95, "description": "Optional SHA-256 pin for an HTTPS agent certificate. The default self-signed Docker agent certificate should be pinned here; leave empty only when normal public-CA validation should be used." }, "poll_interval_seconds": { "type": "integer", "minimum": 5, "maximum": 3600, "default": 30, "description": "How often RustProxy polls this agent for Docker inventory. Manual refresh bypasses this interval." }, "certificate_id": { "type": "string", "nullable": true, "maxLength": 64, "description": "Optional configured TLS certificate assigned to every generated vhost for this Docker agent." }, "acl_profile_id": { "type": "string", "nullable": true, "maxLength": 64, "description": "Optional default ACL profile inherited by generated Docker vhosts whose assignment does not select its own ACL profile." } }, "required": [ "id", "name", "endpoint", "token", "base_domain", "listener_ids" ] }, "DockerSettings": { "type": "object", "additionalProperties": false, "properties": { "agents": { "type": "array", "maxItems": 16, "items": { "$ref": "#/components/schemas/DockerAgent" } } } }, "DockerService": { "type": "object", "additionalProperties": false, "properties": { "key": { "type": "string" }, "technical_name": { "type": "string" }, "container_id": { "type": "string" }, "container_name": { "type": "string" }, "image": { "type": "string" }, "private_port": { "type": "integer", "minimum": 1, "maximum": 65535 }, "protocol": { "type": "string" }, "bindings": { "type": "array", "maxItems": 32, "items": { "$ref": "#/components/schemas/DockerBinding" } } }, "required": [ "key", "technical_name", "container_id", "container_name", "image", "private_port", "protocol", "bindings" ] }, "DockerInventory": { "type": "object", "additionalProperties": false, "properties": { "agent_version": { "type": "string" }, "hostname": { "type": "string" }, "public_ip": { "type": "string", "description": "Preferred/primary host address retained for compatibility and automatic fallback." }, "public_ip_source": { "type": "string", "description": "Discovery source of the preferred/primary host address." }, "observed_at": { "type": "string" }, "services": { "type": "array", "items": { "$ref": "#/components/schemas/DockerService" } }, "addresses": { "type": "array", "maxItems": 64, "items": { "$ref": "#/components/schemas/DockerHostAddress" }, "description": "Usable addresses detected on the Docker host, including interface, routed, public-API and explicit advertised addresses." }, "certificate_sha256": { "type": "string", "description": "SHA-256 fingerprint of the certificate used by the agent HTTPS listener. Empty only when the agent is intentionally running without TLS." } }, "required": [ "agent_version", "hostname", "public_ip", "public_ip_source", "certificate_sha256", "addresses", "observed_at", "services" ] }, "DockerObservation": { "type": "object", "additionalProperties": false, "properties": { "agent_id": { "type": "string" }, "ok": { "type": "boolean" }, "checked_at_unix_ms": { "type": "integer", "format": "int64" }, "error": { "type": "string", "nullable": true }, "inventory": { "allOf": [ { "$ref": "#/components/schemas/DockerInventory" } ], "nullable": true } }, "required": [ "agent_id", "ok", "checked_at_unix_ms" ] }, "DockerObservationResponse": { "type": "object", "additionalProperties": false, "properties": { "observations": { "type": "array", "items": { "$ref": "#/components/schemas/DockerObservation" } }, "pools": { "type": "array", "items": { "$ref": "#/components/schemas/DockerRuntimePool" } }, "pool_routes": { "type": "array", "items": { "$ref": "#/components/schemas/DockerPoolRoute" } } }, "required": [ "observations", "pools", "pool_routes" ] }, "DockerBinding": { "type": "object", "additionalProperties": false, "properties": { "bind_ip": { "type": "string", "description": "Docker published bind address. 0.0.0.0/:: means wildcard on that address family." }, "public_port": { "type": "integer", "minimum": 1, "maximum": 65535 } }, "required": [ "bind_ip", "public_port" ] }, "DockerHostAddress": { "type": "object", "additionalProperties": false, "properties": { "ip": { "type": "string" }, "source": { "type": "string", "description": "Discovery sources, for example interface, route, public_api or override." }, "interface": { "type": "string" }, "scope": { "type": "string", "description": "Address scope reported by the agent, for example private or public." } }, "required": [ "ip", "source", "interface", "scope" ] }, "DockerHealthCheck": { "type": "object", "additionalProperties": false, "properties": { "mode": { "type": "string", "enum": [ "off", "tcp", "http" ], "default": "tcp" }, "path": { "type": "string", "default": "/" }, "host": { "type": "string", "nullable": true, "description": "Optional HTTP Host override. When null for an HTTP vhost probe, RustProxy uses the first exact vhost DNS hostname; if none exists it falls back to the backend host." }, "interval_ms": { "type": "integer", "minimum": 250, "maximum": 300000, "default": 5000 }, "timeout_ms": { "type": "integer", "minimum": 50, "maximum": 60000, "default": 2000 }, "slow_response_ms": { "type": "integer", "minimum": 0, "maximum": 60000, "default": 1500 }, "fall": { "type": "integer", "minimum": 1, "maximum": 20, "default": 3 }, "rise": { "type": "integer", "minimum": 1, "maximum": 20, "default": 2 }, "expected_status_min": { "type": "integer", "minimum": 100, "maximum": 599, "default": 200 }, "expected_status_max": { "type": "integer", "minimum": 100, "maximum": 599, "default": 399 } } }, "DockerPoolRoute": { "type": "object", "additionalProperties": false, "properties": { "agent_id": { "type": "string" }, "service_key": { "type": "string" }, "pool_id": { "type": "string" } }, "required": [ "agent_id", "service_key", "pool_id" ] }, "DockerRuntimePool": { "type": "object", "description": "Live backend-pool diagnostics for a generated Docker vhost. Shape matches entries returned by /api/backends.", "additionalProperties": true, "properties": { "id": { "type": "string" }, "health_mode": { "type": "string", "enum": [ "off", "tcp", "http" ] }, "members": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "required": [ "id", "members" ] }, "ProxyTimeouts": { "type": "object", "additionalProperties": false, "properties": { "connect_timeout_seconds": { "type": "integer", "minimum": 1, "maximum": 300, "nullable": true, "default": 10, "description": "Backend TCP/TLS connect timeout. Missing values default to 10 seconds; explicit null inherits the runtime fallback." }, "response_header_timeout_seconds": { "type": "integer", "minimum": 1, "maximum": 86400, "nullable": true, "default": 120, "description": "Deadline until upstream response headers arrive. Missing values default to 120 seconds; explicit null inherits the startup value." }, "read_timeout_seconds": { "type": "integer", "minimum": 1, "maximum": 86400, "nullable": true, "default": 60, "description": "Maximum idle gap while reading the upstream response body." }, "send_timeout_seconds": { "type": "integer", "minimum": 1, "maximum": 86400, "nullable": true, "default": 60, "description": "Maximum idle gap while streaming the request body upstream." } } }, "AdminPreferences": { "type": "object", "additionalProperties": false, "properties": { "live_log_columns": { "type": "array", "minItems": 1, "maxItems": 13, "uniqueItems": true, "items": { "type": "string", "enum": [ "time", "request", "host", "source_ip", "vhost", "backend", "status", "duration", "cache", "outcome", "transport", "websocket", "upstream_error" ] }, "description": "Account-scoped Live Logs columns shown in the dashboard. JSON log export still contains every field present in each entry." }, "file_log_columns": { "type": "array", "minItems": 1, "maxItems": 64, "uniqueItems": true, "items": { "type": "string", "minLength": 1, "maxLength": 128 }, "default": [ "time", "event", "status", "client_ip", "vhost", "record", "source" ], "description": "Account-scoped Stored Logs explorer columns shown in the dashboard. Field names may be discovered dynamically from bounded JSON/JSONL records." }, "theme": { "type": "string", "enum": [ "dark", "light" ], "default": "dark", "description": "Account-scoped administration interface theme. Existing accounts and omitted values default to the current dark theme." }, "language": { "type": "string", "minLength": 1, "maxLength": 64, "default": "auto", "description": "Account-scoped administration language id, or auto to follow the browser language when a matching language pack exists." }, "ui_scale": { "type": "integer", "minimum": 70, "maximum": 125, "default": 100, "description": "Account-scoped administration workspace scale in percent." }, "time_format": { "type": "string", "enum": [ "24h", "12h" ], "default": "24h", "description": "Account-scoped administration timestamp display preference used by dashboard log and diagnostics views." }, "chart_style": { "type": "string", "enum": [ "default", "soft", "technical", "high_contrast", "neon", "monochrome", "warm", "cool" ], "default": "default", "description": "Account-scoped visual presentation preset applied consistently to administration charts." }, "button_style": { "type": "string", "enum": [ "normal", "compact" ], "default": "normal", "description": "Account-scoped administration button sizing. Normal uses the refreshed controls; Compact restores the smaller source-style button dimensions." }, "table_density": { "type": "string", "enum": [ "normal", "compact", "ultra" ], "default": "normal", "description": "Account-scoped table and log row density independent from whole-interface scale." }, "dashboard_density": { "type": "string", "enum": [ "normal", "compact", "ultra" ], "default": "compact", "description": "Account-scoped Overview telemetry-card density." }, "dashboard_widgets": { "type": "array", "minItems": 1, "maxItems": 12, "uniqueItems": true, "items": { "type": "string", "enum": [ "requests", "active", "bandwidth", "errors", "cache", "memory", "websocket", "http2", "http3", "tls", "http_protocol", "websocket_protocol" ] }, "default": [ "requests", "active", "bandwidth", "errors", "cache", "memory", "websocket", "http2", "http3", "tls", "http_protocol", "websocket_protocol" ], "description": "Account-scoped order for configurable Overview telemetry cards." }, "dashboard_hidden_widgets": { "type": "array", "maxItems": 12, "uniqueItems": true, "items": { "type": "string", "enum": [ "requests", "active", "bandwidth", "errors", "cache", "memory", "websocket", "http2", "http3", "tls", "http_protocol", "websocket_protocol" ] }, "default": [], "description": "Account-scoped Overview telemetry cards hidden from the dashboard." }, "backend_table_columns": { "type": "array", "minItems": 1, "maxItems": 14, "uniqueItems": true, "items": { "type": "string", "enum": [ "vhost", "backend", "status", "active", "requests", "errors", "latency", "traffic", "generation", "generationRequests", "generationAge", "rotations", "lastFailure", "lastRecovery" ] }, "default": [ "vhost", "backend", "status", "active", "requests", "errors", "latency", "traffic", "generation", "generationRequests", "generationAge", "rotations", "lastFailure", "lastRecovery" ], "description": "Account-scoped Backends diagnostics columns shown in the dashboard." }, "backend_table_sort": { "type": "string", "enum": [ "vhost", "backend", "status", "active", "requests", "errors", "latency", "traffic", "generation", "generationRequests", "generationAge", "rotations", "lastFailure", "lastRecovery" ], "default": "vhost", "description": "Account-scoped sort key for the Backends diagnostics table." }, "backend_table_descending": { "type": "boolean", "default": false, "description": "Account-scoped sort direction for the Backends diagnostics table." }, "vhost_list_sort": { "type": "string", "enum": [ "id", "hostname", "status", "listeners", "certificate", "backends" ], "default": "id", "description": "Account-scoped sort key for the Vhosts list." }, "vhost_list_descending": { "type": "boolean", "default": false, "description": "Account-scoped sort direction for the Vhosts list." }, "docker_vhost_sort": { "type": "string", "enum": [ "service", "hostname", "status", "backend", "scheme", "published" ], "default": "service", "description": "Account-scoped sort key for Docker vhost service rows." }, "docker_vhost_descending": { "type": "boolean", "default": false, "description": "Account-scoped sort direction for Docker vhost service rows." }, "redirect_list_sort": { "type": "string", "enum": [ "id", "name", "hostname", "status", "target", "rules", "listeners", "certificate" ], "default": "id", "description": "Account-scoped sort key for the Redirect hosts list." }, "redirect_list_descending": { "type": "boolean", "default": false, "description": "Account-scoped sort direction for the Redirect hosts list." }, "notfound_list_sort": { "type": "string", "enum": [ "id", "name", "hostname", "status", "mode", "listeners", "certificate" ], "default": "id", "description": "Account-scoped sort key for the 404 hosts list." }, "notfound_list_descending": { "type": "boolean", "default": false, "description": "Account-scoped sort direction for the 404 hosts list." }, "stream_list_sort": { "type": "string", "enum": [ "name", "id", "protocol", "listen", "upstream", "status", "maxConnections", "idleTimeout" ], "default": "name", "description": "Account-scoped sort key for the Streams list." }, "stream_list_descending": { "type": "boolean", "default": false, "description": "Account-scoped sort direction for the Streams list." } }, "required": [ "live_log_columns" ] }, "TransformSettings": { "type": "object", "additionalProperties": false, "description": "Global static-response transformation settings. The global engine and the individual vhost must both opt in.", "properties": { "enabled": { "type": "boolean", "default": false }, "preset": { "type": "string", "nullable": true, "enum": [ "conservative", "recommended", "performance", "uber" ], "description": "Last resource preset selected in the administration UI. Numeric limits remain authoritative." }, "javascript": { "type": "boolean", "default": true }, "css": { "type": "boolean", "default": true }, "html": { "type": "boolean", "default": false }, "svg": { "type": "boolean", "default": false }, "json": { "type": "boolean", "default": false }, "extensions": { "type": "array", "maxItems": 64, "items": { "type": "string", "pattern": "^[A-Za-z0-9]{1,16}$" }, "default": [ "js", "mjs", "cjs", "css", "html", "htm", "svg", "json" ] }, "max_body_bytes": { "type": "integer", "minimum": 1024, "maximum": 33554432, "default": 2097152 }, "memory_budget_bytes": { "type": "integer", "minimum": 1048576, "maximum": 2147483648, "default": 134217728, "description": "Process-wide ceiling for estimated temporary transform buffers. The budget is not pre-allocated." }, "max_inflight": { "type": "integer", "minimum": 1, "maximum": 1024, "default": 32, "description": "Process-wide maximum number of active transformation attempts. Excess work fails open unchanged." } } }, "TransformOverrides": { "type": "object", "additionalProperties": false, "description": "Per-vhost transform opt-in. enabled defaults to false even when the global engine is enabled; format fields inherit when null/omitted.", "properties": { "enabled": { "type": "boolean", "default": false }, "javascript": { "type": "boolean", "nullable": true }, "css": { "type": "boolean", "nullable": true }, "html": { "type": "boolean", "nullable": true }, "svg": { "type": "boolean", "nullable": true }, "json": { "type": "boolean", "nullable": true }, "extensions": { "type": "array", "nullable": true, "maxItems": 64, "items": { "type": "string", "pattern": "^[A-Za-z0-9]{1,16}$" } } } }, "ColdCleanupRequest": { "type": "object", "additionalProperties": false, "description": "Select cold-cache objects with the same eviction machinery used by automatic GC. At least one criterion is required.", "properties": { "unused_for_seconds": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 31536000, "nullable": true }, "oldest": { "type": "integer", "minimum": 1, "maximum": 10000, "nullable": true, "description": "Maximum number of oldest matching objects to remove." }, "hits_zero": { "type": "boolean", "default": false } } }, "ColdCleanupJob": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "integer", "format": "int64" }, "status": { "type": "string", "enum": [ "queued", "running", "done", "failed" ] }, "removed_entries": { "type": "integer", "format": "int64" }, "freed_bytes": { "type": "integer", "format": "int64" }, "error": { "type": "string", "nullable": true } }, "required": [ "id", "status", "removed_entries", "freed_bytes" ] }, "LoadBalancingConfig": { "type": "object", "additionalProperties": false, "properties": { "algorithm": { "type": "string", "enum": [ "round_robin", "least_connections", "least_traffic", "adaptive", "ip_hash" ], "default": "least_connections" }, "health_check": { "$ref": "#/components/schemas/DockerHealthCheck", "description": "Active TCP/HTTP health-check policy. Independent from passive health." }, "passive_health": { "$ref": "#/components/schemas/PassiveHealthConfig", "description": "Opt-in health decisions based on ordinary user traffic. Defaults to disabled." }, "keepalive": { "type": "object", "additionalProperties": false, "properties": { "enabled": { "type": "boolean", "default": true }, "idle_timeout_seconds": { "type": "integer", "minimum": 1, "maximum": 3600, "default": 30 }, "max_idle_per_host": { "type": "integer", "minimum": 1, "maximum": 64, "default": 4 }, "tcp_keepalive_seconds": { "type": "integer", "minimum": 1, "maximum": 3600, "default": 30 }, "pool_recycle_requests": { "type": "integer", "minimum": 0, "maximum": 10000000, "default": 25000, "description": "Maximum requests handled by one backend Hyper client generation before its connection pool is recycled. 0 disables request-count recycling; nonzero values below 1000 are rejected by configuration validation." }, "pool_recycle_seconds": { "type": "integer", "minimum": 0, "maximum": 604800, "default": 3600, "description": "Maximum age in seconds of one backend Hyper client generation. 0 disables age-based recycling; nonzero values below 60 are rejected by configuration validation." }, "http1_max_buffer_bytes": { "type": "integer", "minimum": 8192, "maximum": 1048576, "default": 131072, "description": "Maximum adaptive read-buffer size per upstream HTTP/1 connection." } } }, "retry": { "type": "object", "additionalProperties": false, "description": "Safe failover retry policy. Applies only to body-free GET/HEAD/OPTIONS requests and always selects a different healthy pool member.", "properties": { "max_retries": { "type": "integer", "minimum": 0, "maximum": 3, "default": 1 }, "retry_connect_errors": { "type": "boolean", "default": true }, "retry_timeouts": { "type": "boolean", "default": true }, "retry_statuses": { "type": "array", "maxItems": 8, "items": { "type": "integer", "minimum": 500, "maximum": 599 }, "default": [ 502, 503, 504 ] } } }, "sticky": { "type": "object", "additionalProperties": false, "properties": { "mode": { "type": "string", "enum": [ "off", "cookie", "ip_hash" ], "default": "off" }, "cookie_name": { "type": "string", "nullable": true }, "ttl_seconds": { "type": "integer", "minimum": 60, "maximum": 604800, "default": 3600 } } }, "slow_start_seconds": { "type": "integer", "minimum": 0, "maximum": 300, "default": 10 } } }, "PassiveHealthConfig": { "type": "object", "additionalProperties": false, "properties": { "enabled": { "type": "boolean", "default": false, "description": "Opt-in switch. When false, ordinary user traffic never changes shared backend healthy/unhealthy state." }, "count_connect_errors": { "type": "boolean", "default": true }, "count_timeouts": { "type": "boolean", "default": true }, "count_io_errors": { "type": "boolean", "default": true }, "count_http_5xx": { "type": "boolean", "default": true }, "count_slow_responses": { "type": "boolean", "default": false }, "fall": { "type": "integer", "minimum": 1, "maximum": 20, "nullable": true, "description": "Optional passive failure threshold override; null inherits health_check.fall." }, "rise": { "type": "integer", "minimum": 1, "maximum": 20, "nullable": true, "description": "Optional passive recovery threshold override; null inherits health_check.rise." } } }, "TransformCounters": { "type": "object", "additionalProperties": false, "properties": { "examined": { "type": "integer", "minimum": 0 }, "applied": { "type": "integer", "minimum": 0 }, "skipped": { "type": "integer", "minimum": 0 }, "errors": { "type": "integer", "minimum": 0 }, "cache_hits": { "type": "integer", "minimum": 0 }, "original_bytes": { "type": "integer", "minimum": 0 }, "transformed_bytes": { "type": "integer", "minimum": 0 }, "saved_bytes": { "type": "integer", "minimum": 0 }, "duration_us": { "type": "integer", "minimum": 0 }, "by_kind": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } }, "reasons": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } } }, "required": [ "examined", "applied", "skipped", "errors", "cache_hits", "original_bytes", "transformed_bytes", "saved_bytes", "duration_us", "by_kind", "reasons" ] }, "TransformScopeCounters": { "type": "object", "additionalProperties": false, "properties": { "vhost": { "type": "string" }, "examined": { "type": "integer", "minimum": 0 }, "applied": { "type": "integer", "minimum": 0 }, "skipped": { "type": "integer", "minimum": 0 }, "errors": { "type": "integer", "minimum": 0 }, "cache_hits": { "type": "integer", "minimum": 0 }, "original_bytes": { "type": "integer", "minimum": 0 }, "transformed_bytes": { "type": "integer", "minimum": 0 }, "saved_bytes": { "type": "integer", "minimum": 0 }, "duration_us": { "type": "integer", "minimum": 0 }, "by_kind": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } }, "reasons": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } } }, "required": [ "vhost", "examined", "applied", "skipped", "errors", "cache_hits", "original_bytes", "transformed_bytes", "saved_bytes", "duration_us", "by_kind", "reasons" ] }, "TransformStatus": { "type": "object", "additionalProperties": false, "properties": { "settings": { "$ref": "#/components/schemas/TransformSettings" }, "resources": { "type": "object", "additionalProperties": false, "properties": { "memory_reserved_bytes": { "type": "integer", "format": "int64" }, "memory_budget_bytes": { "type": "integer", "format": "int64" }, "inflight": { "type": "integer", "format": "int64" }, "max_inflight": { "type": "integer", "format": "int64" } }, "required": [ "memory_reserved_bytes", "memory_budget_bytes", "inflight", "max_inflight" ] }, "metrics": { "type": "object", "additionalProperties": false, "properties": { "total": { "$ref": "#/components/schemas/TransformCounters" }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/TransformScopeCounters" } } }, "required": [ "total", "scopes" ] }, "vhosts": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "hosts": { "type": "array", "items": { "type": "string" } }, "settings": { "$ref": "#/components/schemas/TransformSettings" } }, "required": [ "id", "hosts" ] } } }, "required": [ "settings", "resources", "metrics", "vhosts" ] }, "CacheInvalidationRequest": { "type": "object", "additionalProperties": false, "required": [ "operation", "selector", "value" ], "properties": { "operation": { "type": "string", "enum": [ "purge", "ban" ] }, "selector": { "type": "string", "enum": [ "exact", "prefix", "tag", "regex", "cache_key" ] }, "value": { "type": "string", "maxLength": 8192 }, "host": { "type": "string", "maxLength": 253, "nullable": true }, "vhost": { "type": "string", "maxLength": 64, "nullable": true }, "ttl_seconds": { "type": "integer", "minimum": 1, "maximum": 604800, "nullable": true, "description": "BAN only; defaults to 3600 seconds." }, "confirm_wide": { "type": "boolean", "default": false, "description": "Required for every regex operation and every root-prefix / operation." } }, "description": "Selective cache invalidation. exact/prefix accept either /path?query or an absolute HTTP(S) URL. Regex is length- and compiled-size-bounded." }, "CacheInvalidationResult": { "type": "object", "additionalProperties": false, "required": [ "operation", "selector", "value", "affected_entries", "elapsed_ms", "status" ], "properties": { "operation": { "type": "string", "enum": [ "purge", "ban" ] }, "selector": { "type": "string", "enum": [ "exact", "prefix", "tag", "regex", "cache_key" ] }, "value": { "type": "string" }, "host": { "type": "string", "nullable": true }, "vhost": { "type": "string", "nullable": true }, "affected_entries": { "type": "integer", "minimum": 0 }, "ban_id": { "type": "integer", "minimum": 1, "nullable": true }, "elapsed_ms": { "type": "integer", "minimum": 0 }, "status": { "type": "string", "enum": [ "completed", "active" ] } } }, "CacheBan": { "type": "object", "additionalProperties": false, "required": [ "id", "selector", "value", "created_at_ms", "expires_at_ms" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "selector": { "type": "string", "enum": [ "exact", "prefix", "tag", "regex", "cache_key" ] }, "value": { "type": "string" }, "scheme": { "type": "string", "nullable": true }, "host": { "type": "string", "nullable": true }, "vhost": { "type": "string", "nullable": true }, "created_at_ms": { "type": "integer", "minimum": 0 }, "expires_at_ms": { "type": "integer", "minimum": 0 } } }, "CacheInvalidationResponse": { "type": "object", "additionalProperties": false, "required": [ "result", "metrics", "bans" ], "properties": { "result": { "$ref": "#/components/schemas/CacheInvalidationResult" }, "metrics": { "type": "object", "additionalProperties": true }, "bans": { "type": "array", "items": { "$ref": "#/components/schemas/CacheBan" } } } }, "CacheBansResponse": { "type": "object", "additionalProperties": false, "required": [ "bans" ], "properties": { "bans": { "type": "array", "items": { "$ref": "#/components/schemas/CacheBan" } } } }, "TunnelInfo": { "type": "object", "additionalProperties": false, "required": [ "id", "client", "host", "upstream", "protocol", "duration_ms", "rx_bytes", "tx_bytes" ], "properties": { "id": { "type": "integer", "format": "uint64" }, "client": { "type": "string" }, "host": { "type": "string" }, "upstream": { "type": "string" }, "protocol": { "type": "string", "description": "Frontend/upstream tunnel transport, for example h1-upgrade, h2-rfc8441-h1-upstream, h2-rfc8441-h2-upstream or h3-rfc9220." }, "duration_ms": { "type": "integer", "format": "uint64" }, "rx_bytes": { "type": "integer", "format": "uint64", "description": "Bytes from client toward upstream." }, "tx_bytes": { "type": "integer", "format": "uint64", "description": "Bytes from upstream toward client." } } }, "TunnelListResponse": { "type": "object", "additionalProperties": false, "required": [ "tunnels" ], "properties": { "tunnels": { "type": "array", "items": { "$ref": "#/components/schemas/TunnelInfo" } } } }, "TunnelKillRequest": { "type": "object", "additionalProperties": false, "properties": { "reason": { "type": "string", "maxLength": 256, "nullable": true } } }, "TunnelKillResponse": { "type": "object", "additionalProperties": false, "required": [ "closed", "reason" ], "properties": { "closed": { "$ref": "#/components/schemas/TunnelInfo" }, "reason": { "type": "string" } } }, "CertificateReloadResult": { "type": "object", "properties": { "reloaded": { "type": "boolean" }, "revision": { "type": "integer", "minimum": 0 }, "public_tls": { "type": "boolean" }, "http3_new_handshakes": { "type": "boolean" }, "administration_restart_required": { "type": "boolean" } }, "additionalProperties": false, "required": [ "reloaded", "revision", "public_tls", "http3_new_handshakes", "administration_restart_required" ] }, "CertificateDeploy": { "type": "object", "properties": { "certificate_id": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]+$" }, "cert_pem": { "type": "string" }, "key_pem": { "type": "string", "writeOnly": true, "description": "Private key PEM; never returned or persisted in API/audit payloads." } }, "additionalProperties": false, "required": [ "certificate_id", "cert_pem", "key_pem" ] }, "CertificateDeployResult": { "type": "object", "properties": { "deployed": { "type": "boolean" }, "operation": { "type": "string", "enum": [ "created", "updated", "metadata-updated", "unchanged" ] }, "created": { "type": "boolean" }, "changed": { "type": "boolean" }, "certificate_id": { "type": "string" }, "revision": { "type": "integer", "minimum": 0 }, "cert_file": { "type": "string" }, "key_file": { "type": "string" }, "covered_hosts": { "type": "array", "items": { "type": "string" } }, "public_tls": { "type": "boolean" }, "http3_new_handshakes": { "type": "boolean" }, "administration_restart_required": { "type": "boolean" } }, "additionalProperties": false, "required": [ "deployed", "operation", "created", "changed", "certificate_id", "revision", "cert_file", "key_file", "covered_hosts", "public_tls", "http3_new_handshakes", "administration_restart_required" ] }, "CertificateApiStatus": { "type": "object", "additionalProperties": false, "properties": { "configured": { "type": "boolean" }, "key_id": { "type": "string", "nullable": true }, "created_at": { "type": "integer", "nullable": true }, "last_used_at": { "type": "integer", "nullable": true }, "scopes": { "type": "array", "items": { "type": "string" } }, "credentials": { "type": "array", "items": { "$ref": "#/components/schemas/CertificateApiCredential" } }, "max_credentials": { "type": "integer", "minimum": 1 } }, "required": [ "configured", "key_id", "created_at", "last_used_at", "scopes", "credentials", "max_credentials" ] }, "CertificateApiRotate": { "type": "object", "additionalProperties": false, "properties": { "key_id": { "type": "string", "maxLength": 64, "nullable": true, "minLength": 3 }, "token": { "type": "string", "minLength": 32, "maxLength": 128, "writeOnly": true, "nullable": true }, "comment": { "type": "string", "maxLength": 256, "nullable": true, "description": "Human-readable non-secret note identifying the automation or owner." }, "certificate_ids": { "type": "array", "minItems": 1, "maxItems": 32, "items": { "type": "string" }, "description": "Certificate IDs this token may operate on. Wildcards are not accepted for newly created credentials." }, "allow_deploy": { "type": "boolean", "default": false, "description": "Also authorize certificate deploy for the allowlisted IDs. Leave false for renewal/reload hooks." } }, "required": [ "certificate_ids" ] }, "CertificateApiRotateResult": { "type": "object", "additionalProperties": false, "properties": { "configured": { "type": "boolean" }, "key_id": { "type": "string", "nullable": true }, "created_at": { "type": "integer", "nullable": true }, "last_used_at": { "type": "integer", "nullable": true }, "scopes": { "type": "array", "items": { "type": "string" } }, "token": { "type": "string", "description": "Returned only once after rotation.", "readOnly": true }, "generated": { "type": "boolean", "readOnly": true }, "credentials": { "type": "array", "items": { "$ref": "#/components/schemas/CertificateApiCredential" } }, "max_credentials": { "type": "integer", "minimum": 1 }, "credential": { "$ref": "#/components/schemas/CertificateApiCredential" } }, "required": [ "configured", "key_id", "created_at", "last_used_at", "scopes", "token", "generated", "credentials", "max_credentials", "credential" ] }, "Http2ConnectionSettings": { "type": "object", "description": "Per-listener HTTP/2/H2C connection lifecycle limits. Idle and lifetime both use graceful GOAWAY -> drain -> TCP close. The top-level config.http2 object is retained only as a compatibility fallback for listeners without explicit binding.http2_settings.", "properties": { "idle_timeout_seconds": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 86400, "default": 300, "description": "Idle timeout for an unused connection. Active streams or frame traffic postpone idle shutdown." }, "max_connection_lifetime_seconds": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 2592000, "default": 0, "description": "Absolute connection lifetime. Zero disables the lifetime limit." }, "drain_timeout_seconds": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 3600, "default": 10, "description": "Maximum drain period after GOAWAY before the TCP transport is closed." } }, "required": [ "idle_timeout_seconds", "max_connection_lifetime_seconds", "drain_timeout_seconds" ], "additionalProperties": false }, "RuntimeInformation": { "type": "object", "description": "Low-risk runtime metadata returned only by the authenticated administrator status endpoint.", "properties": { "platform": { "type": "string" }, "statistics_source": { "type": "string" }, "data_directory": { "type": "string", "nullable": true }, "database_path": { "type": "string", "nullable": true }, "certificate_runtime": { "type": "object", "description": "Python/pip/Certbot capability used by managed certificate automation.", "properties": { "status": { "type": "string", "enum": [ "checking", "initializing", "ready", "unavailable" ] }, "mode": { "type": "string", "enum": [ "none", "managed", "system" ] }, "message": { "type": "string" }, "managed_directory": { "type": "string", "nullable": true }, "python": { "type": "boolean" }, "pip": { "type": "boolean" }, "certbot": { "type": "boolean" } }, "required": [ "status", "mode", "message", "managed_directory", "python", "pip", "certbot" ] } }, "required": [ "platform", "statistics_source", "data_directory", "database_path", "certificate_runtime" ] }, "CertificateApiCredential": { "type": "object", "additionalProperties": false, "properties": { "key_id": { "type": "string" }, "comment": { "type": "string", "maxLength": 256 }, "created_at": { "type": "integer" }, "last_used_at": { "type": "integer", "nullable": true }, "allow_deploy": { "type": "boolean" }, "certificate_ids": { "type": "array", "items": { "type": "string" } } }, "required": [ "key_id", "comment", "created_at", "last_used_at", "allow_deploy", "certificate_ids" ] }, "CertificateReloadOneResult": { "type": "object", "additionalProperties": false, "properties": { "reloaded": { "type": "boolean" }, "certificate_id": { "type": "string" }, "revision": { "type": "integer", "minimum": 0 }, "public_tls": { "type": "boolean" }, "http3_new_handshakes": { "type": "boolean" }, "administration_restart_required": { "type": "boolean" } }, "required": [ "reloaded", "certificate_id", "revision", "public_tls", "http3_new_handshakes", "administration_restart_required" ] }, "Source": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "reverse_proxy" ] } }, "required": [ "type" ] }, { "type": "object", "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "web_server" ] }, "web_service_id": { "type": "string", "description": "ID of a reusable Web Service from config.web_services." } }, "required": [ "type", "web_service_id" ] } ], "description": "Request source. Missing in older configuration documents is treated as Reverse Proxy." }, "WebService": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "maxLength": 64 }, "name": { "type": "string", "maxLength": 96 }, "document_root": { "type": "string", "description": "Absolute local filesystem directory forming the static-file access boundary." }, "index": { "type": "array", "maxItems": 16, "items": { "type": "string", "maxLength": 128 }, "description": "Optional ordered index file names. An empty list skips index lookup; directory listing/error behavior applies directly." }, "directory_listing": { "type": "boolean", "default": false }, "mime_types": { "type": "object", "maxProperties": 64, "additionalProperties": { "type": "string", "maxLength": 256 }, "description": "Optional file-extension to Content-Type overrides. Extensions are stored without a leading dot." }, "default_mime_type": { "type": "string", "maxLength": 256, "default": "application/octet-stream", "description": "Fallback Content-Type for extensions not covered by an override or RustProxy built-ins." }, "cache_control": { "type": "string", "nullable": true, "maxLength": 1024, "description": "Optional default Cache-Control header for files served by this Web Service. Vhost/location response-header rules remain authoritative and may override it." }, "cache_rules": { "type": "array", "maxItems": 64, "default": [], "items": { "type": "object", "additionalProperties": false, "required": [ "matcher", "cache_control" ], "properties": { "matcher": { "type": "string", "description": "ext: or mime:" }, "cache_control": { "type": "string", "maxLength": 1024 } } }, "description": "Ordered per-extension/per-MIME Cache-Control rules evaluated before cache_control." }, "response_headers": { "type": "object", "maxProperties": 32, "default": {}, "additionalProperties": { "type": "string", "maxLength": 8192 }, "description": "Fixed Web Service response headers. Framing/transport headers are rejected; vhost/location response rules run later." }, "try_files": { "type": "array", "maxItems": 16, "default": [], "items": { "type": "string", "maxLength": 512 }, "description": "Ordered nginx-style file candidates. Supports $uri, $query_string and a final =status." }, "rewrites": { "type": "array", "maxItems": 32, "default": [], "items": { "type": "object", "additionalProperties": false, "required": [ "pattern", "replacement" ], "properties": { "pattern": { "type": "string", "maxLength": 512 }, "replacement": { "type": "string", "maxLength": 1024 }, "status": { "type": "integer", "nullable": true, "enum": [ 301, 302, 307, 308 ] } } }, "description": "Regex internal rewrites or explicit redirects evaluated before try_files." }, "precompressed": { "type": "object", "additionalProperties": false, "default": { "enabled": false, "brotli": true, "gzip": true }, "properties": { "enabled": { "type": "boolean", "default": false }, "brotli": { "type": "boolean", "default": true }, "gzip": { "type": "boolean", "default": true } } }, "download_extensions": { "type": "array", "maxItems": 64, "default": [], "items": { "type": "string", "maxLength": 32 }, "description": "Extensions served with Content-Disposition: attachment." }, "symlink_policy": { "type": "string", "enum": [ "deny", "inside_root" ], "default": "deny", "description": "deny is portable/default. inside_root is a Linux-only opt-in and cannot currently be combined with PHP-FPM." }, "php": { "type": "object", "additionalProperties": false, "properties": { "enabled": { "type": "boolean", "default": false }, "extensions": { "type": "array", "maxItems": 16, "default": [ "php" ], "items": { "type": "string", "maxLength": 32 } }, "endpoint": { "type": "string", "description": "unix:/path or loopback tcp:literal-IP:port, for example tcp:127.0.0.1:9000 or tcp:[::1]:9000" }, "connect_timeout_ms": { "type": "integer", "format": "uint64", "minimum": 50, "maximum": 60000, "default": 1000 }, "request_timeout_ms": { "type": "integer", "format": "uint64", "minimum": 100, "maximum": 3600000, "default": 30000 }, "max_concurrent_requests": { "type": "integer", "minimum": 1, "maximum": 4096, "default": 64 }, "pass_authorization": { "type": "boolean", "default": true, "description": "Forward inbound Authorization as HTTP_AUTHORIZATION to PHP-FPM." }, "max_request_body_bytes": { "type": "integer", "format": "uint64", "minimum": 0, "maximum": 8589934592, "default": 0, "description": "RustProxy-side streaming PHP request body limit. 0 disables this additional limit." }, "max_response_header_bytes": { "type": "integer", "minimum": 4096, "maximum": 1048576, "default": 65536 }, "stderr_log_bytes": { "type": "integer", "minimum": 0, "maximum": 65536, "default": 4096, "description": "Maximum PHP-FPM stderr bytes retained per request for diagnostics." }, "custom_params": { "type": "object", "maxProperties": 64, "default": {}, "additionalProperties": { "type": "string", "maxLength": 8192 }, "description": "Trusted static FastCGI NAME=value parameters. Core CGI, HTTP_* and PHP control names are reserved." }, "php_values": { "type": "object", "maxProperties": 64, "default": {}, "additionalProperties": { "type": "string", "maxLength": 8192 }, "description": "Trusted php.ini directive/value overrides combined into the FastCGI PHP_VALUE parameter. PHP_ADMIN_VALUE is not exposed." }, "path_info": { "type": "boolean", "default": false, "description": "Safely split /script.php/extra/path into SCRIPT_FILENAME/SCRIPT_NAME for the existing script plus PATH_INFO." }, "php_admin_values": { "type": "object", "maxProperties": 64, "default": {}, "additionalProperties": { "type": "string", "maxLength": 8192 }, "description": "Trusted operator PHP-FPM administrative php.ini directives packed into PHP_ADMIN_VALUE. Restrict access to FastCGI endpoints." } }, "description": "Optional bounded direct FastCGI connection to a PHP-FPM pool." }, "htaccess": { "type": "object", "additionalProperties": false, "default": { "enabled": false, "filename": ".htaccess", "scan_subdirectories": true, "strict": false }, "properties": { "enabled": { "type": "boolean", "default": false, "description": "Compile the bounded RustProxy .htaccess compatibility subset for this Web Service." }, "filename": { "type": "string", "maxLength": 64, "default": ".htaccess", "description": "Plain configuration file name searched from the document root." }, "scan_subdirectories": { "type": "boolean", "default": true, "description": "Compile matching files in subdirectories, bounded to depth 16 and 128 files." }, "strict": { "type": "boolean", "default": false, "description": "Reject Apply when an unsupported directive is found instead of logging and ignoring it." } }, "description": "Migration-oriented Apache .htaccess subset compiled at Web Service apply time; never parsed per request." }, "hardening": { "type": "object", "additionalProperties": false, "default": { "block_common_attacks": false, "strip_unnecessary_headers": false }, "properties": { "block_common_attacks": { "type": "boolean", "default": false, "description": "Reject high-confidence exploit probes, sensitive dot/control/backup paths and unsafe TRACE/CONNECT/TRACK methods for this Web Service." }, "strip_unnecessary_headers": { "type": "boolean", "default": false, "description": "Remove common implementation/fingerprint response headers such as Server and X-Powered-By after Web Service/.htaccess processing." } }, "description": "Optional Web Service hardening. This is a bounded deterministic compatibility/security layer, not a generic WAF." }, "compression": { "$ref": "#/components/schemas/CompressionOverrides" } }, "required": [ "id", "name", "document_root" ] }, "TrafficTopEntry": { "type": "object", "additionalProperties": false, "required": [ "value", "count" ], "properties": { "value": { "type": "string" }, "count": { "type": "integer", "format": "int64", "minimum": 0 } } }, "TrafficCounters": { "type": "object", "additionalProperties": false, "properties": { "requests": { "type": "integer", "format": "int64" }, "errors": { "type": "integer", "format": "int64" }, "duration_ms": { "type": "integer", "format": "int64" }, "request_bytes": { "type": "integer", "format": "int64" }, "response_bytes": { "type": "integer", "format": "int64" }, "mean_duration_ms": { "type": "number", "format": "double", "nullable": true }, "countries": { "type": "array", "items": { "$ref": "#/components/schemas/TrafficTopEntry" } }, "user_agents": { "type": "array", "items": { "$ref": "#/components/schemas/TrafficTopEntry" } }, "user_agent_families": { "type": "array", "description": "Fixed-cardinality User-Agent families used by Prometheus; raw User-Agent top values remain available only in the authenticated Traffic API/UI.", "items": { "$ref": "#/components/schemas/TrafficTopEntry" } }, "client_ips": { "type": "array", "items": { "$ref": "#/components/schemas/TrafficTopEntry" } }, "methods": { "type": "array", "items": { "$ref": "#/components/schemas/TrafficTopEntry" } }, "method_families": { "type": "array", "description": "Fixed-cardinality common HTTP method families with all extension methods folded into OTHER.", "items": { "$ref": "#/components/schemas/TrafficTopEntry" } }, "sources": { "type": "array", "description": "Fixed serving-source families: reverse_proxy, web_server, local_response or unresolved.", "items": { "$ref": "#/components/schemas/TrafficTopEntry" } }, "statuses": { "type": "array", "items": { "$ref": "#/components/schemas/TrafficTopEntry" } }, "routes": { "type": "array", "items": { "$ref": "#/components/schemas/TrafficTopEntry" } }, "paths": { "type": "array", "items": { "$ref": "#/components/schemas/TrafficTopEntry" } }, "cache": { "type": "array", "items": { "$ref": "#/components/schemas/TrafficTopEntry" } } } }, "TrafficAnalytics": { "type": "object", "additionalProperties": false, "properties": { "scope": { "type": "string" }, "approximate_top_lists": { "type": "boolean" }, "queue_capacity": { "type": "integer" }, "queue_dropped": { "type": "integer", "format": "int64" }, "data": { "$ref": "#/components/schemas/TrafficCounters" } } }, "TrafficStatus": { "type": "object", "additionalProperties": false, "properties": { "scope": { "type": "string" }, "since": { "type": "string", "enum": [ "process_start" ] }, "settings": { "type": "object", "additionalProperties": false, "properties": { "capture_user_agent": { "type": "boolean" }, "capture_country": { "type": "boolean" } } }, "geoip": { "type": "object", "additionalProperties": true }, "analytics": { "$ref": "#/components/schemas/TrafficAnalytics" }, "vhosts": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "FileLogSource": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "kind": { "type": "string", "enum": [ "access", "error" ] }, "path": { "type": "string", "description": "Configured server-side path. Clients cannot supply filesystem paths." }, "enabled": { "type": "boolean" }, "format": { "type": "string", "enum": [ "JSONL", "RAW" ] }, "exists": { "type": "boolean" }, "size": { "type": "integer", "format": "int64" }, "modified_ms": { "type": "integer", "format": "int64" } }, "additionalProperties": false }, "FileLogsInventory": { "type": "object", "properties": { "sources": { "type": "array", "items": { "$ref": "#/components/schemas/FileLogSource" } }, "limits": { "type": "object", "additionalProperties": { "type": "integer", "format": "int64" } } }, "additionalProperties": false }, "FileLogsQuery": { "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "total": { "type": "integer", "format": "int64" }, "offset": { "type": "integer", "format": "int64" }, "limit": { "type": "integer", "format": "int64" }, "truncated": { "type": "boolean" }, "scanned_bytes": { "type": "integer", "format": "int64" }, "scanned_lines": { "type": "integer", "format": "int64" }, "fields": { "type": "array", "description": "Bounded discovered leaf field names available for dynamic Stored Logs columns.", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/FileLogSource" } } }, "additionalProperties": false }, "CompressionSettings": { "type": "object", "additionalProperties": false, "properties": { "gzip": { "type": "boolean", "default": true }, "br": { "type": "boolean", "default": true }, "zstd": { "type": "boolean", "default": true }, "deflate": { "type": "boolean", "default": false }, "min_bytes": { "type": "integer", "format": "uint64", "minimum": 32, "maximum": 1048576, "default": 1024 } }, "description": "Global downstream compression codecs and minimum size. Client q-values win; equal-quality codecs use zstd, then br, gzip and deflate. Existing Content-Encoding is never recompressed." }, "CompressionOverrides": { "type": "object", "additionalProperties": false, "properties": { "enabled": { "type": "boolean", "nullable": true, "default": null, "description": "null inherits the enclosing policy; true/false explicitly enables or disables dynamic compression at this scope." }, "zstd": { "type": "boolean", "nullable": true, "default": null, "description": "Optional Zstandard override at this scope. null inherits; true is effective only when the codec is enabled globally; false disables it." }, "br": { "type": "boolean", "nullable": true, "default": null, "description": "Optional Brotli override at this scope. null inherits; true is effective only when the codec is enabled globally; false disables it." }, "gzip": { "type": "boolean", "nullable": true, "default": null, "description": "Optional gzip override at this scope. null inherits; true is effective only when the codec is enabled globally; false disables it." }, "deflate": { "type": "boolean", "nullable": true, "default": null, "description": "Optional deflate override at this scope. null inherits; true is effective only when the codec is enabled globally; false disables it." } }, "description": "Scoped dynamic-compression policy. The enabled switch and individual codecs inherit by default; global Response codec switches are the hard availability ceiling and min_bytes remains global." }, "GeoIpView": { "type": "object", "additionalProperties": false, "properties": { "loaded": { "type": "boolean" }, "ipv4_ranges": { "type": "integer", "minimum": 0 }, "ipv6_ranges": { "type": "integer", "minimum": 0 }, "source": { "type": "string" }, "format": { "type": "string", "enum": [ "csv_pair", "mmdb" ] } }, "required": [ "loaded", "ipv4_ranges", "ipv6_ranges", "source", "format" ] }, "GeoIpUpdateResult": { "type": "object", "additionalProperties": false, "properties": { "outcome": { "type": "string", "enum": [ "updated", "current", "busy" ] }, "updated_files": { "type": "array", "items": { "type": "string" } }, "database": { "$ref": "#/components/schemas/GeoIpView" } }, "required": [ "outcome", "updated_files", "database" ] }, "ErrorFallback": { "type": "object", "additionalProperties": false, "properties": { "target": { "type": "string", "maxLength": 64, "description": "Enabled internal Custom Location ID in the same vhost." }, "statuses": { "type": "array", "minItems": 1, "maxItems": 6, "uniqueItems": true, "default": [ 404 ], "items": { "type": "integer", "enum": [ 403, 404, 500, 502, 503, 504 ] } } }, "required": [ "target" ], "description": "Nginx-style internal error fallback. The original request is internally dispatched without a client redirect." } } }, "paths": { "/healthz": { "get": { "summary": "Minimal liveness", "tags": [ "Public bootstrap" ], "operationId": "get_healthz", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } } }, "401": { "description": "Authentication required or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host, origin or CSRF validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Bounded worker/session/rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Control-plane storage/worker unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "/api/auth/status": { "get": { "summary": "First-account setup requirement only", "tags": [ "Public bootstrap" ], "operationId": "get_api_auth_status", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthStatus" } } } }, "401": { "description": "Authentication required or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host, origin or CSRF validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Bounded worker/session/rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Control-plane storage/worker unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "/api/auth/setup": { "post": { "summary": "Create the first administrator", "tags": [ "Authentication" ], "operationId": "post_api_auth_setup", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Object" } } } }, "401": { "description": "Authentication required or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host, origin or CSRF validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Bounded worker/session/rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Control-plane storage/worker unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting revision or job state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds the endpoint body limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Configuration/input validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "One-time local capability required. Rejected after initialization. Not executable from Swagger UI.", "security": [], "parameters": [ { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Exact http://HOST:ADMIN_PORT. Set automatically by same-origin browser POST/PUT." }, { "name": "X-RustProxy-Request", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "1" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Setup" } } } } } }, "/api/auth/login": { "post": { "summary": "Create an administrator session", "tags": [ "Authentication" ], "operationId": "post_api_auth_login", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } } }, "401": { "description": "Authentication required or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host, origin or CSRF validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Bounded worker/session/rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Control-plane storage/worker unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting revision or job state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds the endpoint body limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Configuration/input validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Sets an HttpOnly SameSite=Strict session cookie. Browser sessions use the configured 7–30 day absolute lifetime. Use the panel sign-in page. No bearer token or URL token is accepted.", "security": [], "parameters": [ { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Exact http://HOST:ADMIN_PORT. Set automatically by same-origin browser POST/PUT." }, { "name": "X-RustProxy-Request", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "1" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Login" } } } } } }, "/api/auth/session": { "get": { "summary": "Read this session and its CSRF token", "tags": [ "Authentication" ], "operationId": "get_api_auth_session", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } } }, "401": { "description": "Authentication required or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host, origin or CSRF validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Bounded worker/session/rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Control-plane storage/worker unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/auth/logout": { "post": { "summary": "Revoke this session", "tags": [ "Authentication" ], "operationId": "post_api_auth_logout", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Object" } } } }, "401": { "description": "Authentication required or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host, origin or CSRF validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Bounded worker/session/rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Control-plane storage/worker unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting revision or job state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds the endpoint body limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Configuration/input validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Exact http://HOST:ADMIN_PORT. Set automatically by same-origin browser POST/PUT." }, { "name": "X-RustProxy-Request", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "1" ] } } ], "security": [ { "AdminSession": [], "CsrfToken": [] } ] } }, "/api/auth/logout-all": { "post": { "summary": "Revoke all administrator sessions", "tags": [ "Authentication" ], "operationId": "post_api_auth_logout_all", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Object" } } } }, "401": { "description": "Authentication required or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host, origin or CSRF validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Bounded worker/session/rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Control-plane storage/worker unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting revision or job state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds the endpoint body limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Configuration/input validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Exact http://HOST:ADMIN_PORT. Set automatically by same-origin browser POST/PUT." }, { "name": "X-RustProxy-Request", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "1" ] } } ], "security": [ { "AdminSession": [], "CsrfToken": [] } ] } }, "/api/auth/password": { "post": { "summary": "Change password and revoke sessions", "tags": [ "Authentication" ], "operationId": "post_api_auth_password", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Object" } } } }, "401": { "description": "Authentication required or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host, origin or CSRF validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Bounded worker/session/rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Control-plane storage/worker unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting revision or job state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds the endpoint body limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Configuration/input validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Exact http://HOST:ADMIN_PORT. Set automatically by same-origin browser POST/PUT." }, { "name": "X-RustProxy-Request", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "1" ] } } ], "security": [ { "AdminSession": [], "CsrfToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasswordChange" } } } } } }, "/api/status": { "get": { "summary": "Application, listener, system and traffic status", "tags": [ "Monitoring" ], "operationId": "get_api_status", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } }, "401": { "description": "Authentication required or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host, origin or CSRF validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Bounded worker/session/rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Control-plane storage/worker unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/backends": { "get": { "summary": "Backend pool health and active/desired frontends", "tags": [ "Monitoring" ], "operationId": "get_api_backends", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Object" } } } }, "401": { "description": "Authentication required or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host, origin or CSRF validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Bounded worker/session/rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Control-plane storage/worker unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/config": { "get": { "summary": "Read the revisioned configuration", "tags": [ "Configuration" ], "operationId": "get_api_config", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Authentication required or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host, origin or CSRF validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Bounded worker/session/rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Control-plane storage/worker unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "summary": "Replace the entire configuration atomically", "tags": [ "Configuration" ], "operationId": "put_api_config", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Authentication required or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host, origin or CSRF validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Bounded worker/session/rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Control-plane storage/worker unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting revision or job state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds the endpoint body limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Configuration/input validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "NOT a patch or merge. First GET /api/config, edit config and PUT with the current expected_revision. On conflict reload instead of overwriting. Header rules live in config.vhosts[].routes[].headers (global -> vhost -> location). Protocol and verified identity policies run last. Only the longest matching prefix applies. Full-document PUT remains supported for atomic multi-section changes; prefer /api/config/{section} for a normal settings-page save so unrelated sections are not resent.", "parameters": [ { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Exact http://HOST:ADMIN_PORT. Set automatically by same-origin browser POST/PUT." }, { "name": "X-RustProxy-Request", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "1" ] } } ], "security": [ { "AdminSession": [], "CsrfToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Update" } } } } } }, "/api/certificates": { "get": { "summary": "Certificate inventory and renewal state", "tags": [ "Certificates" ], "operationId": "get_api_certificates", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CertificateInventory" } } } }, "401": { "description": "Authentication required or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host, origin or CSRF validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Bounded worker/session/rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Control-plane storage/worker unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Returns active SNI bindings and covered_hosts metadata. Public certificate PEM files are inspected on a bounded blocking worker so current DNS SAN coverage is shown even for older/manual entries or in-place renewals; private keys are never read for inventory." } }, "/api/certificates/upload": { "post": { "summary": "Validate and stage a PEM pair", "tags": [ "Certificates" ], "operationId": "post_api_certificates_upload", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CertificateUploadResult" } } } }, "401": { "description": "Authentication required or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host, origin or CSRF validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Bounded worker/session/rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Control-plane storage/worker unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting revision or job state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds the endpoint body limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Configuration/input validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Maximum body 300 KiB. Staging does not assign a vhost; publish the returned certificate through a revisioned config update. Private key material is never returned. The returned certificate includes covered_hosts extracted from the staged leaf certificate DNS SubjectAltName extension.", "parameters": [ { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Exact http://HOST:ADMIN_PORT. Set automatically by same-origin browser POST/PUT." }, { "name": "X-RustProxy-Request", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "1" ] } } ], "security": [ { "AdminSession": [], "CsrfToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CertificateUpload" } } } } } }, "/api/acme": { "get": { "summary": "Latest ACME job and renewal observations", "tags": [ "Certificates" ], "operationId": "get_api_acme", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Object" } } } }, "401": { "description": "Authentication required or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host, origin or CSRF validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Bounded worker/session/rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Control-plane storage/worker unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/acme/issue": { "post": { "summary": "Start a bounded issuance job", "tags": [ "Certificates" ], "operationId": "post_api_acme_issue", "responses": { "202": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Object" } } } }, "401": { "description": "Authentication required or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host, origin or CSRF validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Bounded worker/session/rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Control-plane storage/worker unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting revision or job state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds the endpoint body limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Configuration/input validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Maximum body 16 KiB. Staging by default. Production requires explicit consent. Provider fields depend on the selected provider; see docs/ACME_PROVIDERS.md. Poll GET /api/acme.", "parameters": [ { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Exact http://HOST:ADMIN_PORT. Set automatically by same-origin browser POST/PUT." }, { "name": "X-RustProxy-Request", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "1" ] } } ], "security": [ { "AdminSession": [], "CsrfToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcmeIssue" } } } } } }, "/api/acme/renew": { "post": { "summary": "Check/renew a managed certificate", "tags": [ "Certificates" ], "operationId": "post_api_acme_renew", "responses": { "202": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Object" } } } }, "401": { "description": "Authentication required or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host, origin or CSRF validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Bounded worker/session/rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Control-plane storage/worker unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting revision or job state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds the endpoint body limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Configuration/input validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Exact http://HOST:ADMIN_PORT. Set automatically by same-origin browser POST/PUT." }, { "name": "X-RustProxy-Request", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "1" ] } } ], "security": [ { "AdminSession": [], "CsrfToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenewRequest" } } } } } }, "/api/basic-auth/hash": { "post": { "summary": "Hash credentials for a vhost", "tags": [ "Configuration" ], "operationId": "post_api_basic_auth_hash", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HashedUser" } } } }, "401": { "description": "Authentication required or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host, origin or CSRF validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Bounded worker/session/rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Control-plane storage/worker unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting revision or job state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds the endpoint body limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Configuration/input validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Maximum body 4 KiB. Plaintext password is input-only; store the returned Argon2id hash in vhost configuration, not this request.", "parameters": [ { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Exact http://HOST:ADMIN_PORT. Set automatically by same-origin browser POST/PUT." }, { "name": "X-RustProxy-Request", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "1" ] } } ], "security": [ { "AdminSession": [], "CsrfToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicHash" } } } } } }, "/api/cache": { "get": { "summary": "Cache metrics, domains and paginated objects", "tags": [ "Cache" ], "operationId": "get_api_cache", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cache" } } } }, "401": { "description": "Authentication required or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host, origin or CSRF validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Bounded worker/session/rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Control-plane storage/worker unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "vhost", "in": "query", "required": false, "description": "Configured vhost ID. Omit to select all scopes.", "schema": { "type": "string" } }, { "name": "offset", "in": "query", "required": false, "description": "", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "description": "", "schema": { "type": "integer", "minimum": 1, "default": 50 } } ] } }, "/api/transform": { "get": { "summary": "Transformation runtime metrics and per-vhost effectiveness", "tags": [ "Transform" ], "operationId": "get_api_transform", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformStatus" } } } }, "401": { "description": "Authentication required or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host, origin or CSRF validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Bounded worker/session/rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Control-plane storage/worker unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/geoip/update": { "post": { "summary": "Check, download and hot-reload GeoIP country databases now", "description": "Download the configured direct GeoIP source(s), optionally verify publisher SHA-256 values, validate the selected CSV/MMDB format, atomically publish changed files and hot-reload future GeoIP lookups.", "tags": [ "Settings" ], "operationId": "post_api_geoip_update", "responses": { "200": { "description": "GeoIP check completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeoIpUpdateResult" } } } }, "401": { "description": "Authentication required or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host, origin or CSRF validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Publisher check, download, validation or reload failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "AdminSession": [], "CsrfToken": [] } ] } }, "/api/cache/purge": { "post": { "summary": "Purge all cache entries or one vhost", "tags": [ "Cache" ], "operationId": "post_api_cache_purge", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Object" } } } }, "401": { "description": "Authentication required or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host, origin or CSRF validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Bounded worker/session/rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Control-plane storage/worker unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting revision or job state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds the endpoint body limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Configuration/input validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Invalidates stored entries and pending fills in the selected scope. Select the vhost in the QUERY STRING, not the body.", "parameters": [ { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Exact http://HOST:ADMIN_PORT. Set automatically by same-origin browser POST/PUT." }, { "name": "X-RustProxy-Request", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "1" ] } }, { "name": "vhost", "in": "query", "required": false, "description": "Configured vhost ID. Omit to select all scopes.", "schema": { "type": "string" } } ], "security": [ { "AdminSession": [], "CsrfToken": [] } ] } }, "/api/logs": { "get": { "summary": "Recent completed requests, filtered", "tags": [ "Monitoring" ], "operationId": "get_api_logs", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Logs" } } } }, "401": { "description": "Authentication required or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host, origin or CSRF validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Bounded worker/session/rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Control-plane storage/worker unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "vhost", "in": "query", "required": false, "description": "Configured vhost ID. Omit to select all scopes.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "", "schema": { "type": "string", "maxLength": 256 } }, { "name": "status", "in": "query", "required": false, "description": "", "schema": { "type": "integer", "minimum": 100, "maximum": 599 } }, { "name": "cache", "in": "query", "required": false, "description": "", "schema": { "type": "string", "enum": [ "HIT", "MISS", "BYPASS", "-" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Number of retained completed requests to return. Live UI snapshots use 256; an expanded Live Logs window can request up to 4096.", "schema": { "type": "integer", "minimum": 1, "maximum": 4096, "default": 256 } } ] } }, "/api/audit": { "get": { "summary": "Recent administrator audit events", "tags": [ "Monitoring" ], "operationId": "get_api_audit", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Audit" } } } }, "401": { "description": "Authentication required or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host, origin or CSRF validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Bounded worker/session/rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Control-plane storage/worker unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/events": { "get": { "summary": "Live SSE status and log snapshots", "tags": [ "Monitoring" ], "operationId": "get_api_events", "responses": { "200": { "description": "Successful response", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication required or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host, origin or CSRF validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Bounded worker/session/rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Control-plane storage/worker unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Bounded snapshot every approximately 2 seconds. Session/revocation rechecked before every snapshot. Not executed in Swagger because it is an unbounded stream." } }, "/metrics": { "get": { "summary": "Authenticated Prometheus text exposition", "tags": [ "Monitoring" ], "operationId": "get_metrics", "responses": { "200": { "description": "Successful response", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication required or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host, origin or CSRF validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Bounded worker/session/rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Control-plane storage/worker unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Requires the admin session on THIS listener. The optional dedicated exporter uses independent CIDR/bearer policy; it is disabled by default." } }, "/api/metrics": { "get": { "summary": "Authenticated Prometheus text exposition", "tags": [ "Monitoring" ], "operationId": "get_api_metrics", "responses": { "200": { "description": "Successful response", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication required or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host, origin or CSRF validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Bounded worker/session/rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Control-plane storage/worker unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Requires the admin session on THIS listener. The optional dedicated exporter uses independent CIDR/bearer policy; it is disabled by default." } }, "/docs/openapi.json": { "get": { "summary": "This protected OpenAPI document", "tags": [ "Documentation" ], "operationId": "get_docs_openapi.json", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Object" } } } }, "401": { "description": "Authentication required or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host, origin or CSRF validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Bounded worker/session/rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Control-plane storage/worker unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/config/{section}": { "put": { "summary": "Replace one configuration section atomically", "tags": [ "Configuration" ], "operationId": "put_api_config_section", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Authentication required or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host, origin or CSRF validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Bounded worker/session/rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Control-plane storage/worker unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting revision or job state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds the endpoint body limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Configuration/input validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Preferred UI/control-plane save path. Replaces only the selected section while preserving every other section from the current revision. This is not a merge patch. Cache identity is independent from the global configuration revision: logging, listeners, TLS inventory, metrics and administration saves do not purge cached objects. Changes which can alter origin requests or cached responses (cache/transform/response/forwarding/vhosts) rotate the cache compatibility identity and purge incompatible hot/cold objects. Supported section names include docker-agents, vhosts, redirects, not_found_hosts, streams, listeners, http2, tls, pages, cache, transform, logging, forwarding, headers, prometheus, geoip, administration, acl-profiles, host-policies and response.", "parameters": [ { "name": "section", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "listeners", "docker-agents", "response", "pages", "cache", "transform", "logging", "forwarding", "headers", "prometheus", "geoip", "administration", "http2", "tls", "vhosts", "redirects", "not_found_hosts", "streams", "acl-profiles", "host-policies" ] }, "description": "Configuration section to replace." }, { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Exact http://HOST:ADMIN_PORT. Set automatically by same-origin browser POST/PUT." }, { "name": "X-RustProxy-Request", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "1" ] } } ], "security": [ { "AdminSession": [], "CsrfToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigSectionUpdate" } } } } } }, "/api/docker": { "get": { "summary": "Read cached Docker agent observations", "tags": [ "Docker" ], "operationId": "get_api_docker", "responses": { "200": { "description": "Current Docker agent observations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DockerObservationResponse" } } } }, "401": { "description": "Authentication required or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host, origin or CSRF validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Control-plane unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "AdminSession": [] } ] } }, "/api/docker/refresh": { "post": { "summary": "Poll Docker agents now and rebuild dynamic Docker vhosts", "description": "Observed inventory remains in memory. Only configured Docker assignments are persisted; a refresh does not create a configuration revision.", "tags": [ "Docker" ], "operationId": "post_api_docker_refresh", "responses": { "200": { "description": "Current Docker agent observations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DockerObservationResponse" } } } }, "401": { "description": "Authentication required or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host, origin or CSRF validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Control-plane unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Docker observation cannot be reconciled into the active routing snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-RustProxy-Request", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "1" ] } } ], "security": [ { "AdminSession": [], "CsrfToken": [] } ] } }, "/api/preferences": { "get": { "summary": "Read administrator view preferences", "tags": [ "Administration" ], "operationId": "get_api_preferences", "responses": { "200": { "description": "Current account-scoped view preferences", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminPreferences" } } } }, "401": { "description": "Authentication required or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host, origin or CSRF validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Control-plane storage unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "summary": "Save administrator view preferences", "description": "Persists dashboard-only preferences for the signed-in administrator. This does not change the proxy configuration revision.", "tags": [ "Administration" ], "operationId": "put_api_preferences", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminPreferences" } } } }, "responses": { "200": { "description": "Saved view preferences", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminPreferences" } } } }, "422": { "description": "Invalid preference value", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host, origin or CSRF validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Control-plane storage unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/cache/cold/cleanup": { "post": { "summary": "Start selective asynchronous Cold Cache cleanup", "tags": [ "Cache" ], "operationId": "post_api_cache_cold_cleanup", "responses": { "401": { "description": "Authentication required or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host, origin or CSRF validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Bounded worker/session/rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Control-plane storage/worker unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting revision or job state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds the endpoint body limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Configuration/input validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "202": { "description": "Cleanup job accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "job": { "$ref": "#/components/schemas/ColdCleanupJob" } }, "required": [ "job" ] } } } } }, "description": "Queues selective cleanup using the same eviction selector as automatic cold-cache GC. Existing full purge endpoints remain unchanged.", "parameters": [ { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Exact http://HOST:ADMIN_PORT. Set automatically by same-origin browser POST/PUT." }, { "name": "X-RustProxy-Request", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "1" ] } } ], "security": [ { "AdminSession": [], "CsrfToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ColdCleanupRequest" } } } } } }, "/api/cache/cold/cleanup/{id}": { "get": { "summary": "Read selective Cold Cache cleanup job status", "tags": [ "Cache" ], "operationId": "get_api_cache_cold_cleanup_job", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "minimum": 1 } } ], "responses": { "200": { "description": "Cleanup job", "content": { "application/json": { "schema": { "type": "object", "properties": { "job": { "$ref": "#/components/schemas/ColdCleanupJob" } }, "required": [ "job" ] } } } }, "401": { "description": "Authentication required or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host, origin or CSRF validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown cleanup job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "AdminSession": [] } ] } }, "/api/cache/invalidate": { "post": { "summary": "Selectively PURGE cached objects or add a lazy BAN rule", "tags": [ "Cache" ], "operationId": "post_api_cache_invalidate", "description": "PURGE removes matching RAM and cold-cache variants immediately. Every selective PURGE also blocks any fill that started before the operation from publishing afterward; matching single-flight waiters are released. BAN registers a TTL-bounded rule and is evaluated lazily during lookup/GC without synchronously scanning storage. Regex operations and prefix / require confirm_wide=true.", "parameters": [ { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Exact http://HOST:ADMIN_PORT. Set automatically by same-origin browser POST/PUT/DELETE." }, { "name": "X-RustProxy-Request", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "1" ] } } ], "security": [ { "AdminSession": [], "CsrfToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CacheInvalidationRequest" } } } }, "responses": { "200": { "description": "Invalidation accepted/completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CacheInvalidationResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host, origin or CSRF validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds the endpoint body limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Configuration/input validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Bounded worker/session/rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Control-plane storage/worker unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/cache/bans": { "get": { "summary": "List active cache BAN rules", "tags": [ "Cache" ], "operationId": "get_api_cache_bans", "responses": { "200": { "description": "Active BAN rules", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CacheBansResponse" } } } }, "401": { "description": "Authentication required or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host, origin or CSRF validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Bounded worker/session/rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Control-plane storage/worker unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/cache/bans/{id}": { "delete": { "summary": "Remove one cache BAN rule", "tags": [ "Cache" ], "operationId": "delete_api_cache_ban", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Exact http://HOST:ADMIN_PORT. Set automatically by same-origin browser POST/PUT/DELETE." }, { "name": "X-RustProxy-Request", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "1" ] } } ], "security": [ { "AdminSession": [], "CsrfToken": [] } ], "responses": { "200": { "description": "BAN removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CacheBansResponse" } } } }, "401": { "description": "Authentication required or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host, origin or CSRF validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "BAN rule does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Bounded worker/session/rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Control-plane storage/worker unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/tunnels": { "get": { "summary": "List active WebSocket/Extended CONNECT tunnels", "tags": [ "Monitoring" ], "operationId": "get_api_tunnels", "responses": { "200": { "description": "Active WebSocket/Extended CONNECT tunnels", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TunnelListResponse" } } } }, "401": { "description": "Authentication required or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host, origin or CSRF validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Bounded worker/session/rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Control-plane storage/worker unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/tunnels/{id}/kill": { "post": { "summary": "Cancel one active WebSocket/Extended CONNECT tunnel", "tags": [ "Monitoring" ], "operationId": "post_api_tunnel_kill", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Exact http://HOST:ADMIN_PORT. Set automatically by same-origin browser POST/PUT/DELETE." }, { "name": "X-RustProxy-Request", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "1" ] } } ], "security": [ { "AdminSession": [], "CsrfToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TunnelKillRequest" } } } }, "responses": { "200": { "description": "Tunnel cancellation requested and audited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TunnelKillResponse" } } } }, "401": { "description": "Authentication required or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host, origin or CSRF validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Tunnel is no longer active", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid close reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Bounded worker/session/rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Control-plane storage/worker unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/certificates/reload": { "post": { "summary": "Reload configured certificate files from disk", "description": "Rebuilds and hot-publishes the public TLS routing snapshot from the currently configured certificate/key files without changing the configuration revision. New public TLS/H2/H3 handshakes use the refreshed keys. Administration TLS remains startup-fixed and reports when a restart is required. The operation can be authenticated either by the normal administrator session+CSRF flow or by the scoped Certificate API Key ID + Bearer Token. External token use requires HTTPS unless the request originates from loopback. Certificate API tokens are intentionally not accepted here; automation must use the targeted per-certificate reload endpoint.", "tags": [ "Certificates" ], "operationId": "post_api_certificates_reload", "responses": { "200": { "description": "Certificates revalidated and hot-reloaded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CertificateReloadResult" } } } }, "401": { "description": "Authentication required or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host, origin or CSRF validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Configured certificate files failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Control-plane storage/worker unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "AdminSession": [], "CsrfToken": [] } ] } }, "/api/certificates/deploy": { "post": { "summary": "Reconcile an externally issued pair with a manual certificate id", "description": "Maximum body 300 KiB. Convergently reconciles an externally issued PEM pair for one manual certificate id. Administrator session+CSRF is always accepted. Certificate API authentication is accepted only when that credential explicitly grants deploy permission and allowlists the requested certificate ID. New Certificate API credentials default to reload-only.", "tags": [ "Certificates" ], "operationId": "post_api_certificates_deploy", "parameters": [ { "name": "Origin", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Exact http://HOST:ADMIN_PORT. Set automatically by same-origin browser/CLI mutation clients." }, { "name": "X-RustProxy-Request", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ] } } ], "security": [ { "AdminSession": [], "CsrfToken": [] }, { "CertificateApiBearer": [], "CertificateApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CertificateDeploy" } } } }, "responses": { "200": { "description": "Certificate generation staged and published", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CertificateDeployResult" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host, origin or CSRF validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Configured certificate id does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Certificate is RustProxy-managed or the configuration changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds the endpoint body limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Certificate/key/configuration validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Bounded certificate/configuration worker queue is full", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Control-plane storage/worker unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/certificate-api": { "get": { "summary": "Inspect scoped external certificate API tokens", "tags": [ "Certificates" ], "operationId": "get_api_certificate_api", "security": [ { "AdminSession": [] } ], "responses": { "200": { "description": "Configured token metadata (never cleartext secrets)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CertificateApiStatus" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "summary": "Generate, add, or rotate a scoped external certificate API token", "tags": [ "Certificates" ], "operationId": "put_api_certificate_api", "security": [ { "AdminSession": [], "CsrfToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CertificateApiRotate" } } } }, "responses": { "200": { "description": "Token added/rotated; cleartext token is returned once", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CertificateApiRotateResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "CSRF/origin validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid Key ID, token, or comment format", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Certificate API token capacity reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Revoke all scoped external certificate API tokens", "tags": [ "Certificates" ], "operationId": "delete_api_certificate_api", "security": [ { "AdminSession": [], "CsrfToken": [] } ], "responses": { "200": { "description": "All configured certificate API tokens revoked" }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "CSRF/origin validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/live-logs": { "get": { "summary": "Stream live access-log entries as authenticated SSE", "description": "Bounded live stream used by rust-proxy --livelogs. Events are named log; a gap event reports how many entries a slow receiver lost. Browser/CLI session revocation and expiry are revalidated periodically.", "tags": [ "Logging" ], "operationId": "get_api_live_logs", "security": [ { "AdminSession": [] } ], "responses": { "200": { "description": "text/event-stream of complete access-log JSON entries", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many live viewers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/certificate-api/{key_id}": { "delete": { "summary": "Revoke one scoped external certificate API token", "tags": [ "Certificates" ], "operationId": "delete_api_certificate_api_key_id", "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 3, "maxLength": 64 } } ], "security": [ { "AdminSession": [], "CsrfToken": [] } ], "responses": { "200": { "description": "Token revoked" }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "CSRF/origin validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Token Key ID not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/certificates/{certificate_id}/reload": { "post": { "summary": "Reload one manual/file-backed certificate from disk", "description": "Targets one configured certificate ID that is not ACME-managed. RustProxy revalidates and atomically republishes its immutable TLS snapshot without changing the configuration revision. The scoped Certificate API token is accepted for this operation, making it suitable for external certificate renewal hooks. Managed ACME certificate IDs are rejected because their renewal pipeline owns those files. Certificate API tokens must be explicitly allowlisted for this certificate ID.", "tags": [ "Certificates" ], "operationId": "post_api_certificates_certificate_id_reload", "parameters": [ { "name": "certificate_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Certificate files validated and TLS snapshot republished", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CertificateReloadOneResult" } } } }, "401": { "description": "Authentication required or token revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host, origin, CSRF, or external HTTP restriction failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Certificate ID not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Certificate is application-managed and cannot be manually reloaded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Certificate/key files failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Control-plane storage/worker unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "AdminSession": [], "CsrfToken": [] }, { "CertificateApiBearer": [], "CertificateApiKey": [] } ] } }, "/api/traffic": { "get": { "summary": "Bounded per-vhost traffic analytics", "tags": [ "Traffic" ], "operationId": "get_api_traffic", "parameters": [ { "name": "vhost", "in": "query", "required": false, "description": "Configured vhost ID or * for all vhosts.", "schema": { "type": "string", "default": "*" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrafficStatus" } } } }, "401": { "description": "Authentication required or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host, origin or CSRF validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown vhost scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Bounded worker/session/rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Control-plane storage/worker unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/config/history": { "get": { "summary": "Browse retained manual configuration revisions", "description": "Returns up to 512 retained revision metadata entries, or one revision with its previous retained configuration for diff rendering.", "tags": [ "Configuration" ], "operationId": "get_api_config_history", "parameters": [ { "name": "revision", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "Return one retained revision and its previous retained configuration." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 512, "default": 512 }, "description": "Maximum metadata entries when revision is omitted." } ], "responses": { "200": { "description": "Revision history or revision detail", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Authentication required or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host, origin or CSRF validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Bounded worker/session/rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Control-plane storage/worker unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Requested revision is not retained", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/config/history/restore": { "post": { "summary": "Restore a retained configuration revision as a new revision", "description": "Loads one retained configuration document, validates it through the normal full configuration update path, and saves it as a new revision. expected_revision must match the current configuration revision; the selected source revision must be older. Existing history is preserved.", "tags": [ "Configuration" ], "operationId": "post_api_config_history_restore", "parameters": [ { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Exact http://HOST:ADMIN_PORT. Set automatically by same-origin browser POST." }, { "name": "X-RustProxy-Request", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "1" ] } } ], "security": [ { "AdminSession": [], "CsrfToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "revision", "expected_revision" ], "properties": { "revision": { "type": "integer", "format": "int64", "minimum": 0, "description": "Older retained revision to restore." }, "expected_revision": { "type": "integer", "format": "int64", "minimum": 0, "description": "Current revision observed by the caller." } } } } } }, "responses": { "200": { "description": "Configuration restored and published as a new revision", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid restore request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host, origin or CSRF validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Requested revision is not retained", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Configuration changed; reload before restoring", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds the endpoint body limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Restored configuration failed current validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Bounded worker/session/rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Control-plane storage/worker unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/file-logs": { "get": { "summary": "Configured on-disk log sources", "description": "Lists only RustProxy log paths from the active configuration. This endpoint is independent from the Live Logs memory buffer and does not accept a filesystem path.", "tags": [ "Monitoring" ], "operationId": "get_api_file_logs", "responses": { "200": { "description": "Configured file-log inventory", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileLogsInventory" } } } }, "401": { "description": "Authentication required or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host, origin or CSRF validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Bounded worker/session/rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Control-plane storage/worker unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/file-logs/query": { "get": { "summary": "Query configured on-disk logs", "description": "Reads bounded tails of configured RustProxy access/error log files using server-side source IDs only. The query never accepts arbitrary paths, follows no symlink on Unix, and is separate from /api/logs and /api/live-logs.", "tags": [ "Monitoring" ], "operationId": "get_api_file_logs_query", "parameters": [ { "name": "source", "in": "query", "required": false, "description": "Source ID returned by /api/file-logs, or all. Never a filesystem path.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Case-insensitive field query. Supports field:value, AND, ! negation, quoted values, wildcards and numeric comparisons; bare terms search all values.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "event", "in": "query", "required": false, "description": "Event class.", "schema": { "type": "string", "enum": [ "all", "request", "protocol_error", "error" ] } }, { "name": "status_class", "in": "query", "required": false, "description": "HTTP status class.", "schema": { "type": "string", "enum": [ "all", "1xx", "2xx", "3xx", "4xx", "5xx" ] } }, { "name": "client_ip", "in": "query", "required": false, "description": "Client IP substring filter.", "schema": { "type": "string", "maxLength": 128 } }, { "name": "vhost", "in": "query", "required": false, "description": "Vhost substring filter.", "schema": { "type": "string", "maxLength": 256 } }, { "name": "offset", "in": "query", "required": false, "description": "Result offset within the bounded scan.", "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } } ], "responses": { "200": { "description": "Bounded filtered page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileLogsQuery" } } } }, "400": { "description": "Invalid filter or unknown source", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Host, origin or CSRF validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Bounded worker/session/rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Control-plane storage/worker unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } } }