{ "openapi": "3.1.0", "info": { "title": "Api", "version": "1.0.0", "description": "Agent Precall - Secure Endpoint API — pre-call trust and safety layer for autonomous agents" }, "servers": [ { "url": "/api", "description": "Base API path" } ], "tags": [ { "name": "health", "description": "Health operations" }, { "name": "scan", "description": "Endpoint scanning and trust evaluation" }, { "name": "demos", "description": "Seeded demonstration scans" } ], "paths": { "/healthz": { "get": { "operationId": "healthCheck", "tags": [ "health" ], "summary": "Health check", "description": "Returns server health status", "responses": { "200": { "description": "Healthy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthStatus" } } } } } } }, "/version": { "get": { "operationId": "getVersion", "tags": [ "health" ], "summary": "Version info", "description": "Returns product version and configuration", "responses": { "200": { "description": "Version info", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionInfo" } } } } } } }, "/v1/stats": { "get": { "operationId": "getStats", "tags": [ "scan" ], "summary": "API usage statistics", "description": "Returns aggregate scan statistics", "responses": { "200": { "description": "Stats", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatsResponse" } } } } } } }, "/v1/scan": { "post": { "operationId": "scanEndpoint", "tags": [ "scan" ], "summary": "Scan an endpoint", "description": "Run a trust and safety scan on a target endpoint. Returns cached results if available.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScanRequest" } } } }, "responses": { "200": { "description": "Scan result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScanResult" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "SSRF or unsafe target rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/decision": { "get": { "operationId": "getDecision", "tags": [ "scan" ], "summary": "Get compact decision for an endpoint", "description": "Returns a compact, agent-optimized trust decision. Uses cached results when available.", "parameters": [ { "name": "target", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The target URL to evaluate" }, { "name": "force_refresh", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Bypass cache and re-scan" } ], "responses": { "200": { "description": "Decision", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionResponse" } } } }, "400": { "description": "Invalid target", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "SSRF or unsafe target rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/deep-scan": { "post": { "operationId": "deepScanEndpoint", "tags": [ "scan" ], "summary": "Premium deep scan", "description": "Run an expanded trust scan with richer protocol detection. Payment-gated in production mode.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScanRequest" } } } }, "responses": { "200": { "description": "Deep scan result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeepScanResult" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Payment required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequiredResponse" } } } }, "422": { "description": "SSRF or unsafe target rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/demos": { "get": { "operationId": "listDemos", "tags": [ "demos" ], "summary": "List seeded demo scans", "description": "Returns pre-seeded demonstration scans showing safe, caution, and unsafe endpoint examples", "responses": { "200": { "description": "Demo scans", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DemoListResponse" } } } } } } }, "/v1/demos/{demo_id}": { "get": { "operationId": "getDemo", "tags": [ "demos" ], "summary": "Get a specific demo scan", "parameters": [ { "name": "demo_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Demo scan result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScanResult" } } } }, "404": { "description": "Demo not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "components": { "schemas": { "HealthStatus": { "type": "object", "properties": { "status": { "type": "string" } }, "required": [ "status" ] }, "VersionInfo": { "type": "object", "properties": { "product": { "type": "string" }, "version": { "type": "string" }, "mock_payment_mode": { "type": "boolean" }, "cache_ttl_seconds": { "type": "integer" }, "build_time": { "type": "string" } }, "required": [ "product", "version", "mock_payment_mode", "cache_ttl_seconds", "build_time" ] }, "StatsResponse": { "type": "object", "properties": { "total_scans": { "type": "integer" }, "cached_scans": { "type": "integer" }, "unique_targets": { "type": "integer" }, "risk_distribution": { "$ref": "#/components/schemas/RiskDistribution" }, "decision_distribution": { "$ref": "#/components/schemas/DecisionDistribution" } }, "required": [ "total_scans", "cached_scans", "unique_targets", "risk_distribution", "decision_distribution" ] }, "RiskDistribution": { "type": "object", "properties": { "low": { "type": "integer" }, "medium": { "type": "integer" }, "high": { "type": "integer" }, "critical": { "type": "integer" } }, "required": [ "low", "medium", "high", "critical" ] }, "DecisionDistribution": { "type": "object", "properties": { "should_call": { "type": "integer" }, "use_caution": { "type": "integer" }, "do_not_call": { "type": "integer" } }, "required": [ "should_call", "use_caution", "do_not_call" ] }, "ScanRequest": { "type": "object", "properties": { "target": { "type": "string", "description": "URL to scan" }, "target_type": { "type": "string", "enum": [ "auto", "website", "api", "mcp", "manifest" ], "default": "auto" }, "force_refresh": { "type": "boolean", "default": false } }, "required": [ "target" ] }, "ScanFlags": { "type": "object", "properties": { "https": { "type": "boolean" }, "tls_valid": { "type": "boolean" }, "reachable": { "type": "boolean" }, "robots_txt": { "type": "boolean" }, "llms_txt": { "type": "boolean" }, "agent_policy_header": { "type": "boolean" }, "openapi_spec": { "type": "boolean" }, "mcp_server_card": { "type": "boolean" }, "oauth_metadata": { "type": "boolean" }, "requires_auth": { "type": "boolean" }, "rate_limit_headers": { "type": "boolean" }, "hsts": { "type": "boolean" }, "csp": { "type": "boolean" }, "cors_wildcard": { "type": "boolean" }, "exposed_mcp": { "type": "boolean" }, "exposed_sse": { "type": "boolean" }, "suspicious_debug_path": { "type": "boolean" }, "known_vuln_match": { "type": "boolean" }, "supports_402": { "type": "boolean" }, "supports_x402": { "type": "boolean" }, "supports_mpp": { "type": "boolean" } }, "required": [ "https", "tls_valid", "reachable", "robots_txt", "llms_txt", "agent_policy_header", "openapi_spec", "mcp_server_card", "oauth_metadata", "requires_auth", "rate_limit_headers", "hsts", "csp", "cors_wildcard", "exposed_mcp", "exposed_sse", "suspicious_debug_path", "known_vuln_match", "supports_402", "supports_x402", "supports_mpp" ] }, "RawSignals": { "type": "object", "properties": { "status_code": { "type": [ "integer", "null" ] }, "latency_ms": { "type": [ "integer", "null" ] }, "redirect_chain": { "type": "array", "items": { "type": "string" } }, "detected_paths": { "type": "array", "items": { "type": "string" } }, "detected_protocol_hints": { "type": "array", "items": { "type": "string" } }, "server_header": { "type": [ "string", "null" ] }, "content_type": { "type": [ "string", "null" ] } }, "required": [ "status_code", "latency_ms", "redirect_chain", "detected_paths", "detected_protocol_hints", "server_header", "content_type" ] }, "ScanResult": { "type": "object", "properties": { "id": { "type": "string" }, "target": { "type": "string" }, "normalized_target": { "type": "string" }, "resolved_target_type": { "type": "string", "enum": [ "website", "api", "mcp", "manifest", "unknown" ] }, "decision": { "type": "string", "enum": [ "should_call", "use_caution", "do_not_call" ] }, "should_call": { "type": "boolean" }, "confidence": { "type": "number" }, "risk_level": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "trust_score": { "type": "integer" }, "compatibility_score": { "type": "integer" }, "auth_required": { "type": "boolean" }, "payment_required": { "type": "boolean" }, "payment_protocols_supported": { "type": "array", "items": { "type": "string" } }, "certified": { "type": "boolean" }, "certification_label": { "type": [ "string", "null" ] }, "flags": { "$ref": "#/components/schemas/ScanFlags" }, "reason_codes": { "type": "array", "items": { "type": "string" } }, "recommendations": { "type": "array", "items": { "type": "string" } }, "raw_signals": { "$ref": "#/components/schemas/RawSignals" }, "cached": { "type": "boolean" }, "scanned_at": { "type": "string" } }, "required": [ "id", "target", "normalized_target", "resolved_target_type", "decision", "should_call", "confidence", "risk_level", "trust_score", "compatibility_score", "auth_required", "payment_required", "payment_protocols_supported", "certified", "certification_label", "flags", "reason_codes", "recommendations", "raw_signals", "cached", "scanned_at" ] }, "SecurityHeaders": { "type": "object", "properties": { "hsts": { "type": "boolean" }, "csp": { "type": "boolean" }, "x_content_type_options": { "type": "boolean" }, "x_frame_options": { "type": "boolean" }, "referrer_policy": { "type": "boolean" }, "cors_wildcard": { "type": "boolean" } }, "required": [ "hsts", "csp", "x_content_type_options", "x_frame_options", "referrer_policy", "cors_wildcard" ] }, "ProtocolDetection": { "type": "object", "properties": { "openapi_version": { "type": [ "string", "null" ] }, "oauth_endpoints": { "type": "array", "items": { "type": "string" } }, "mcp_endpoints": { "type": "array", "items": { "type": "string" } }, "payment_hints": { "type": "array", "items": { "type": "string" } }, "agent_compatibility_signals": { "type": "array", "items": { "type": "string" } } }, "required": [ "openapi_version", "oauth_endpoints", "mcp_endpoints", "payment_hints", "agent_compatibility_signals" ] }, "SuspiciousFindings": { "type": "object", "properties": { "exposed_admin": { "type": "boolean" }, "exposed_debug": { "type": "boolean" }, "exposed_metrics": { "type": "boolean" }, "exposed_config": { "type": "boolean" }, "directory_listing": { "type": "boolean" }, "version_banner_leaked": { "type": "boolean" }, "exposed_paths": { "type": "array", "items": { "type": "string" } } }, "required": [ "exposed_admin", "exposed_debug", "exposed_metrics", "exposed_config", "directory_listing", "version_banner_leaked", "exposed_paths" ] }, "RiskSignalMatch": { "type": "object", "properties": { "signal_id": { "type": "string" }, "description": { "type": "string" }, "severity": { "type": "string" } }, "required": [ "signal_id", "description", "severity" ] }, "DeepScanResult": { "type": "object", "properties": { "base": { "$ref": "#/components/schemas/ScanResult" }, "security_headers": { "$ref": "#/components/schemas/SecurityHeaders" }, "protocol_detection": { "$ref": "#/components/schemas/ProtocolDetection" }, "suspicious_findings": { "$ref": "#/components/schemas/SuspiciousFindings" }, "risk_signal_matches": { "type": "array", "items": { "$ref": "#/components/schemas/RiskSignalMatch" } }, "deep_scan_notes": { "type": "array", "items": { "type": "string" } }, "payment_gated": { "type": "boolean" } }, "required": [ "base", "security_headers", "protocol_detection", "suspicious_findings", "risk_signal_matches", "deep_scan_notes", "payment_gated" ] }, "DecisionResponse": { "type": "object", "properties": { "target": { "type": "string" }, "decision": { "type": "string", "enum": [ "should_call", "use_caution", "do_not_call" ] }, "should_call": { "type": "boolean" }, "confidence": { "type": "number" }, "risk_level": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "trust_score": { "type": "integer" }, "compatibility_score": { "type": "integer" }, "auth_required": { "type": "boolean" }, "payment_required": { "type": "boolean" }, "reason_codes": { "type": "array", "items": { "type": "string" } }, "cached": { "type": "boolean" }, "scanned_at": { "type": "string" } }, "required": [ "target", "decision", "should_call", "confidence", "risk_level", "trust_score", "compatibility_score", "auth_required", "payment_required", "reason_codes", "cached", "scanned_at" ] }, "DemoEntry": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "decision": { "type": "string", "enum": [ "should_call", "use_caution", "do_not_call" ] } }, "required": [ "id", "label", "description", "decision" ] }, "DemoListResponse": { "type": "object", "properties": { "demos": { "type": "array", "items": { "$ref": "#/components/schemas/DemoEntry" } } }, "required": [ "demos" ] }, "PaymentRequiredResponse": { "type": "object", "properties": { "error": { "type": "string" }, "payment": { "$ref": "#/components/schemas/PaymentInstruction" } }, "required": [ "error", "payment" ] }, "PaymentInstruction": { "type": "object", "properties": { "protocol": { "type": "string" }, "amount": { "type": "string" }, "currency": { "type": "string" }, "network": { "type": "string" }, "resource": { "type": "string" }, "instructions": { "type": "string" } }, "required": [ "protocol", "amount", "currency", "network", "resource", "instructions" ] }, "ErrorResponse": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": [ "string", "null" ] } }, "required": [ "error", "detail" ] } } } }