{ "openapi": "3.0.3", "info": { "title": "Shield API", "version": "1.0.0", "description": "OWASP-aligned text validation, threat detection, and security enforcement. Validation endpoints (`/validate/*`) are public; security-management endpoints (`/security/*`) require an `X-Api-Key` header." }, "servers": [ { "url": "https://api.puglieseweb.com/shield/v1", "description": "Production" } ], "paths": { "/security/block": { "post": { "tags": [ "Security" ], "summary": "Block an IP address", "operationId": "block_ip_endpoint_security_block_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlockIpRequest" } } }, "required": true }, "responses": { "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlockResponse" } } } } } } }, "/security/blocked": { "get": { "tags": [ "Security" ], "summary": "List blocked IPs", "description": "Returns the current in-force IP blocklist. Expired entries are filtered out.", "operationId": "list_blocked_security_blocked_get", "responses": { "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlockedIpsResponse" } } } } } } }, "/security/threat-log": { "get": { "tags": [ "Security" ], "summary": "Query the threat detection log", "operationId": "query_threats_security_threat_log_get", "responses": { "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThreatsResponse" } } } } } } }, "/security/unblock": { "post": { "tags": [ "Security" ], "summary": "Unblock an IP address", "operationId": "unblock_ip_endpoint_security_unblock_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnblockIpRequest" } } }, "required": true }, "responses": { "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnblockResponse" } } } } } } }, "/validate/email": { "post": { "tags": [ "Validation" ], "summary": "Validate an email address", "operationId": "post_validate_email_validate_email_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateEmailRequest" } } }, "required": true }, "responses": { "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationResultModel" } } } } } } }, "/validate/fields": { "post": { "tags": [ "Validation" ], "summary": "Batch-validate multiple form fields", "operationId": "post_validate_fields_validate_fields_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateFieldsRequest" } } }, "required": true }, "responses": { "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FieldsResult" } } } } } } }, "/validate/text": { "post": { "tags": [ "Validation" ], "summary": "Validate a single text input", "operationId": "post_validate_text_validate_text_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateTextRequest" } } }, "required": true }, "responses": { "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationResultModel" } } } } } } } }, "components": { "schemas": { "FieldsResult": { "properties": { "safe": { "type": "boolean", "title": "Safe" }, "sanitized": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": "object", "title": "Sanitized" }, "threats": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Threats" } }, "type": "object", "required": [ "safe", "sanitized" ], "title": "FieldsResult" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ValidateEmailRequest": { "properties": { "email": { "type": "string", "title": "Email" } }, "type": "object", "required": [ "email" ], "title": "ValidateEmailRequest" }, "ValidateFieldsRequest": { "properties": { "fields": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": "object", "title": "Fields", "description": "Map of field name -> value (null allowed)" }, "max_lengths": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "Max Lengths" }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Id" } }, "type": "object", "required": [ "fields" ], "title": "ValidateFieldsRequest" }, "ValidateTextRequest": { "properties": { "text": { "type": "string", "title": "Text", "description": "Text to validate/sanitize" }, "max_length": { "type": "integer", "maximum": 1000000.0, "minimum": 1.0, "title": "Max Length", "default": 200000 }, "allow_html": { "type": "boolean", "title": "Allow Html", "default": false }, "field_name": { "type": "string", "title": "Field Name", "default": "input" }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Id" } }, "type": "object", "required": [ "text" ], "title": "ValidateTextRequest" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "ValidationResultModel": { "properties": { "safe": { "type": "boolean", "title": "Safe" }, "sanitized": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sanitized" }, "threats": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Threats" } }, "type": "object", "required": [ "safe" ], "title": "ValidationResultModel" }, "ResponseValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "ResponseValidationError" }, "BlockIpRequest": { "properties": { "ip": { "type": "string", "title": "Ip", "description": "IPv4 or IPv6 address to block" }, "reason": { "type": "string", "maxLength": 500, "title": "Reason", "default": "Manual block via admin API" }, "ttl_seconds": { "type": "integer", "maximum": 2592000.0, "minimum": 60.0, "title": "Ttl Seconds", "description": "Block duration (60s to 30 days)", "default": 86400 } }, "type": "object", "required": [ "ip" ], "title": "BlockIpRequest" }, "BlockResponse": { "properties": { "blocked": { "type": "boolean", "title": "Blocked" }, "ip": { "type": "string", "title": "Ip" }, "ttl_seconds": { "type": "integer", "title": "Ttl Seconds" } }, "type": "object", "required": [ "blocked", "ip", "ttl_seconds" ], "title": "BlockResponse" }, "BlockedIp": { "properties": { "ip": { "type": "string", "title": "Ip" }, "blocked_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Blocked At" }, "expires_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Expires At" }, "reason": { "type": "string", "title": "Reason", "default": "" }, "threat_category": { "type": "string", "title": "Threat Category", "default": "" } }, "type": "object", "required": [ "ip" ], "title": "BlockedIp" }, "BlockedIpsResponse": { "properties": { "blocked_ips": { "items": { "$ref": "#/components/schemas/BlockedIp" }, "type": "array", "title": "Blocked Ips" }, "count": { "type": "integer", "title": "Count" } }, "type": "object", "required": [ "blocked_ips", "count" ], "title": "BlockedIpsResponse" }, "ThreatEntry": { "properties": { "ip": { "type": "string", "title": "Ip" }, "timestamp": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Timestamp" }, "user_id": { "type": "string", "title": "User Id", "default": "anonymous" }, "endpoint": { "type": "string", "title": "Endpoint", "default": "" }, "max_severity": { "type": "string", "title": "Max Severity", "default": "" }, "threats": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Threats" }, "request_preview": { "type": "string", "title": "Request Preview", "default": "" } }, "type": "object", "required": [ "ip" ], "title": "ThreatEntry" }, "ThreatsResponse": { "properties": { "threats": { "items": { "$ref": "#/components/schemas/ThreatEntry" }, "type": "array", "title": "Threats" }, "count": { "type": "integer", "title": "Count" } }, "type": "object", "required": [ "threats", "count" ], "title": "ThreatsResponse" }, "UnblockIpRequest": { "properties": { "ip": { "type": "string", "title": "Ip" } }, "type": "object", "required": [ "ip" ], "title": "UnblockIpRequest" }, "UnblockResponse": { "properties": { "unblocked": { "type": "boolean", "title": "Unblocked" }, "ip": { "type": "string", "title": "Ip" } }, "type": "object", "required": [ "unblocked", "ip" ], "title": "UnblockResponse" } }, "securitySchemes": { "AdminApiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" } } } }