{ "openapi": "3.0.3", "info": { "title": "AgentAIShield API", "version": "2.0.0", "description": "AgentAIShield (AAIS) \u2014 AI Agent Security Platform\n\n11 security features across two integration modes:\n1. **Monitor Mode**: Fire-and-forget POST after every AI call. No latency impact.\n2. **Proxy Mode**: Route AI calls through AAIS. Intercepts, scans, and optionally blocks.\n\n## Authentication\n- **Dashboard endpoints**: JWT Bearer token (obtain via /api/auth/login)\n- **Monitor/Proxy endpoints**: API key Bearer token (format: `aais_xxx`, obtain via /api/keys)\n\n## Base URL\nSelf-hosted: `https://your-aais-instance.com`\n\n## Rate Limits\n- Auth endpoints: 20 requests per 15 minutes\n- Dashboard API: 120 requests per minute\n- Monitor ingest: 100 requests per minute per API key\n- Proxy endpoints: 600 requests per minute", "contact": { "name": "AgentAIShield Support", "url": "https://agentaishield.com" }, "license": { "name": "Proprietary" } }, "servers": [ { "url": "https://your-aais-instance.com", "description": "Self-hosted instance" }, { "url": "http://localhost:3006", "description": "Local development" } ], "components": { "securitySchemes": { "JWTBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT token obtained from /api/auth/login. Used for dashboard endpoints." }, "APIKeyBearer": { "type": "http", "scheme": "bearer", "description": "AAIS API key in format `aais_xxx`. Used for monitor/proxy endpoints." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "example": { "error": "Validation failed", "details": [ { "field": "email", "message": "Must be a valid email" } ] } }, "User": { "type": "object", "properties": { "id": { "type": "integer" }, "email": { "type": "string", "format": "email" }, "name": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "Organization": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" }, "plan": { "type": "string", "enum": [ "free", "pro", "enterprise" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "AuthResponse": { "type": "object", "properties": { "ok": { "type": "boolean" }, "token": { "type": "string", "description": "JWT access token (24h)" }, "refresh_token": { "type": "string", "description": "Refresh token (30d)" }, "user": { "$ref": "#/components/schemas/User" }, "org": { "$ref": "#/components/schemas/Organization" } } }, "MonitorIngestRequest": { "type": "object", "required": [ "app_name", "model", "provider" ], "properties": { "app_name": { "type": "string", "description": "Name of your application/agent", "example": "MyAIApp" }, "model": { "type": "string", "description": "LLM model name", "example": "gpt-4o" }, "provider": { "type": "string", "description": "LLM provider", "enum": [ "openai", "anthropic", "google", "cohere", "mistral", "other" ], "example": "openai" }, "prompt": { "type": "string", "description": "The prompt sent to the LLM (scanned for PII and injection)", "example": "Summarize this customer support ticket: ..." }, "response": { "type": "string", "description": "The LLM response (scanned for PII leakage)", "example": "Here is the summary: ..." }, "tokens_in": { "type": "integer", "description": "Number of input tokens", "example": 150 }, "tokens_out": { "type": "integer", "description": "Number of output tokens", "example": 500 }, "latency_ms": { "type": "integer", "description": "Round-trip latency in milliseconds", "example": 1200 }, "status": { "type": "string", "description": "Call status", "enum": [ "success", "error", "blocked" ], "default": "success", "example": "success" }, "reported_at": { "type": "string", "format": "date-time", "description": "When the AI call occurred (ISO 8601). Defaults to now.", "example": "2025-01-15T10:30:00Z" } }, "example": { "app_name": "CustomerSupportBot", "model": "gpt-4o", "provider": "openai", "prompt": "Help this user: John called about his order #12345", "response": "I can help with order tracking...", "tokens_in": 150, "tokens_out": 500, "latency_ms": 1200, "status": "success" } }, "DashboardStats": { "type": "object", "properties": { "period": { "type": "string", "example": "30d" }, "total_requests": { "type": "integer", "example": 12450 }, "total_cost": { "type": "number", "example": 23.45 }, "total_tokens_in": { "type": "integer", "example": 1500000 }, "total_tokens_out": { "type": "integer", "example": 800000 }, "avg_latency_ms": { "type": "integer", "example": 980 }, "blocked_requests": { "type": "integer", "example": 23 }, "error_requests": { "type": "integer", "example": 12 }, "success_requests": { "type": "integer", "example": 12415 }, "pii_detections": { "type": "integer", "example": 87 }, "violations": { "type": "integer", "example": 14 }, "threats_detected": { "type": "integer", "example": 101 }, "active_agents": { "type": "integer", "example": 5 }, "cost_by_provider": { "type": "object", "additionalProperties": { "type": "number" }, "example": { "openai": 18.5, "anthropic": 4.95 } }, "recent_requests": { "type": "array", "items": { "$ref": "#/components/schemas/RequestSummary" } }, "security_alerts": { "type": "array", "items": { "$ref": "#/components/schemas/SecurityAlert" } } } }, "RequestSummary": { "type": "object", "properties": { "id": { "type": "integer" }, "timestamp": { "type": "integer", "description": "Unix ms" }, "agent": { "type": "string" }, "provider": { "type": "string" }, "model": { "type": "string" }, "tokens": { "type": "integer" }, "latency_ms": { "type": "integer" }, "status": { "type": "string", "enum": [ "success", "error", "blocked" ] }, "pii": { "type": "boolean" }, "injection": { "type": "boolean" }, "flags": { "type": "array", "items": { "type": "string" } } } }, "SecurityAlert": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "pii", "violation" ] }, "title": { "type": "string" }, "detail": { "type": "string" }, "severity": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "timestamp": { "type": "integer", "description": "Unix ms" }, "agent": { "type": "string" } } }, "AgentProfile": { "type": "object", "properties": { "id": { "type": "integer" }, "agent_name": { "type": "string" }, "agent_description": { "type": "string" }, "agent_type": { "type": "string", "enum": [ "autonomous", "assistant", "batch", "api" ] }, "trust_score": { "type": "number", "minimum": 0, "maximum": 100, "example": 87.5 }, "trust_grade": { "type": "string", "enum": [ "A+", "A", "B+", "B", "C+", "C", "D", "F" ], "example": "A" }, "score_confidence": { "type": "number", "minimum": 0, "maximum": 1, "example": 0.92 }, "total_requests": { "type": "integer", "example": 1240 }, "status": { "type": "string", "enum": [ "active", "suspended", "probation" ] }, "badges": { "type": "array", "items": { "type": "string" } }, "first_seen_at": { "type": "string", "format": "date-time" }, "last_scored_at": { "type": "string", "format": "date-time" }, "key_prefix": { "type": "string", "example": "aais_prod_" }, "provider": { "type": "string" }, "environment": { "type": "string", "enum": [ "production", "staging", "development" ] } } }, "TrustOverview": { "type": "object", "properties": { "org_score": { "type": "number", "example": 82.3 }, "total_agents": { "type": "integer", "example": 5 }, "grade_distribution": { "type": "object", "additionalProperties": { "type": "integer" }, "example": { "A+": 1, "A": 2, "B": 1, "C": 1 } }, "agents": { "type": "array", "items": { "$ref": "#/components/schemas/AgentProfile" } } } }, "SecurityScore": { "type": "object", "properties": { "score": { "type": "integer", "minimum": 0, "maximum": 100, "example": 78 }, "grade": { "type": "string", "example": "B+" }, "breakdown": { "type": "object", "properties": { "pii_risk": { "type": "integer", "example": 85 }, "injection_risk": { "type": "integer", "example": 92 }, "data_exposure": { "type": "integer", "example": 70 }, "compliance": { "type": "integer", "example": 65 } } }, "trend": { "type": "string", "enum": [ "improving", "stable", "declining" ] }, "recommendations": { "type": "array", "items": { "type": "string" } } } }, "SanitizeRequest": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "The prompt text to sanitize (max 100,000 chars)", "example": "My SSN is 123-45-6789, call me at 555-123-4567" }, "mode": { "type": "string", "enum": [ "redact", "mask", "remove" ], "default": "redact", "description": "redact=replace with type label, mask=replace with *****, remove=delete entirely" }, "options": { "type": "object", "properties": { "pii": { "type": "boolean", "default": true, "description": "Enable PII detection" }, "injection": { "type": "boolean", "default": true, "description": "Enable injection neutralization" }, "custom_rules": { "type": "array", "items": { "type": "object", "properties": { "pattern": { "type": "string", "description": "Regex pattern" }, "replacement": { "type": "string", "description": "Replacement text" }, "label": { "type": "string", "description": "Human-readable label" } } } } } } } }, "SanitizeResponse": { "type": "object", "properties": { "original_length": { "type": "integer" }, "sanitized_text": { "type": "string" }, "modifications": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "example": "ssn" }, "original": { "type": "string" }, "replacement": { "type": "string" }, "start": { "type": "integer" }, "end": { "type": "integer" } } } }, "injection_neutralized": { "type": "boolean" }, "risk_score": { "type": "number", "minimum": 0, "maximum": 1 }, "processing_ms": { "type": "integer" } } }, "ScanOutputRequest": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "The LLM output text to scan (max 500,000 chars)" }, "context": { "type": "object", "properties": { "agent": { "type": "string", "description": "Agent/app name for logging" }, "model": { "type": "string", "description": "Model that generated this output" }, "prompt_hash": { "type": "string", "description": "SHA-256 hash of the original prompt" } } } } }, "ScanOutputResponse": { "type": "object", "properties": { "safe": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "pii_leak", "harmful_content", "code_execution", "training_data_leak", "unauthorized_claim" ] }, "severity": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "description": { "type": "string" }, "excerpt": { "type": "string" } } } }, "risk_score": { "type": "number", "minimum": 0, "maximum": 1 }, "recommendation": { "type": "string", "enum": [ "allow", "flag", "review", "block" ] }, "processing_ms": { "type": "integer" } } }, "QuarantinedAgent": { "type": "object", "properties": { "id": { "type": "integer" }, "agent_name": { "type": "string" }, "agent_type": { "type": "string" }, "trust_score": { "type": "number" }, "trust_grade": { "type": "string" }, "quarantined": { "type": "boolean" }, "quarantined_at": { "type": "string", "format": "date-time" }, "quarantine_reason": { "type": "string" }, "auto_quarantine_threshold": { "type": "number" }, "status": { "type": "string" } } }, "BudgetStatus": { "type": "object", "properties": { "agent_id": { "type": "integer" }, "agent_name": { "type": "string" }, "daily_token_limit": { "type": "integer", "nullable": true }, "monthly_token_limit": { "type": "integer", "nullable": true }, "daily_used": { "type": "integer" }, "monthly_used": { "type": "integer" }, "daily_pct": { "type": "number", "nullable": true }, "monthly_pct": { "type": "number", "nullable": true }, "status": { "type": "string", "enum": [ "Active", "Warning", "Critical", "Budget Exceeded", "No limit" ] }, "action_on_exceed": { "type": "string", "enum": [ "warn", "throttle", "block" ] } } }, "RedTeamRunRequest": { "type": "object", "required": [ "agent_id" ], "properties": { "agent_id": { "type": "integer", "description": "ID of the agent to test" }, "intensity": { "type": "string", "enum": [ "light", "standard", "thorough" ], "default": "standard" }, "categories": { "type": "array", "items": { "type": "string", "enum": [ "pii_extraction", "jailbreak", "prompt_injection", "role_override", "data_exfiltration" ] }, "description": "Attack categories to run (default: all)" } } }, "RedTeamStatus": { "type": "object", "properties": { "run_id": { "type": "string" }, "agent_id": { "type": "integer" }, "status": { "type": "string", "enum": [ "pending", "running", "completed", "failed" ] }, "progress_pct": { "type": "integer" }, "attacks_run": { "type": "integer" }, "attacks_total": { "type": "integer" }, "started_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time", "nullable": true } } }, "RedTeamReport": { "type": "object", "properties": { "run_id": { "type": "string" }, "agent_id": { "type": "integer" }, "overall_grade": { "type": "string", "enum": [ "A", "B", "C", "D", "F" ] }, "overall_score": { "type": "number", "minimum": 0, "maximum": 100 }, "vulnerabilities_found": { "type": "integer" }, "attacks_total": { "type": "integer" }, "attacks_passed": { "type": "integer" }, "category_results": { "type": "object", "additionalProperties": { "type": "object", "properties": { "passed": { "type": "integer" }, "failed": { "type": "integer" }, "score": { "type": "number" } } } }, "vulnerabilities": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string" }, "attack": { "type": "string" }, "severity": { "type": "string" }, "description": { "type": "string" }, "evidence": { "type": "string" } } } }, "completed_at": { "type": "string", "format": "date-time" } } }, "TrustVerification": { "type": "object", "properties": { "agent_id": { "type": "integer" }, "agent_name": { "type": "string" }, "trust_score": { "type": "number" }, "trust_grade": { "type": "string" }, "recommendation": { "type": "string", "enum": [ "safe_to_share", "share_with_caution", "do_not_share" ] }, "badges": { "type": "array", "items": { "type": "string" } }, "quarantined": { "type": "boolean" }, "last_checked": { "type": "string", "format": "date-time" } } }, "ThreatFeedItem": { "type": "object", "properties": { "id": { "type": "string" }, "pattern_type": { "type": "string", "enum": [ "pii_extraction", "jailbreak", "prompt_injection", "role_override", "data_exfiltration" ] }, "description": { "type": "string" }, "severity": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "occurrences": { "type": "integer" }, "first_seen": { "type": "string", "format": "date-time" }, "last_seen": { "type": "string", "format": "date-time" }, "anonymized": { "type": "boolean" } } }, "ComplianceReportRequest": { "type": "object", "required": [ "framework" ], "properties": { "framework": { "type": "string", "enum": [ "soc2", "hipaa", "gdpr", "all" ] }, "period_days": { "type": "integer", "default": 30, "description": "Lookback period in days" } } }, "ComplianceReport": { "type": "object", "properties": { "id": { "type": "string" }, "framework": { "type": "string" }, "overall_score": { "type": "number", "minimum": 0, "maximum": 100 }, "status": { "type": "string", "enum": [ "compliant", "partial", "non_compliant" ] }, "controls": { "type": "array", "items": { "type": "object", "properties": { "control_id": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string", "enum": [ "pass", "fail", "partial", "na" ] }, "score": { "type": "number" }, "findings": { "type": "array", "items": { "type": "string" } } } } }, "generated_at": { "type": "string", "format": "date-time" } } }, "FingerprintProfile": { "type": "object", "properties": { "agent_id": { "type": "integer" }, "agent_name": { "type": "string" }, "baseline_established": { "type": "boolean" }, "baseline_requests": { "type": "integer" }, "anomaly_score": { "type": "number", "minimum": 0, "maximum": 1 }, "anomaly_count_24h": { "type": "integer" }, "dimensions": { "type": "object", "properties": { "avg_tokens_in": { "type": "number" }, "avg_tokens_out": { "type": "number" }, "avg_latency_ms": { "type": "number" }, "top_model": { "type": "string" }, "error_rate": { "type": "number" } } }, "last_updated": { "type": "string", "format": "date-time" } } }, "AnomalyEvent": { "type": "object", "properties": { "id": { "type": "integer" }, "dimension": { "type": "string", "enum": [ "tokens_in", "tokens_out", "latency_ms", "model", "error_rate" ] }, "severity": { "type": "string", "enum": [ "warning", "critical" ] }, "z_score": { "type": "number" }, "observed_value": { "type": "number" }, "baseline_value": { "type": "number" }, "description": { "type": "string" }, "detected_at": { "type": "string", "format": "date-time" } } }, "MCPRequest": { "type": "object", "required": [ "jsonrpc", "method" ], "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "id": { "type": "string" }, "method": { "type": "string", "enum": [ "initialize", "tools/list", "tools/call" ] }, "params": { "type": "object", "description": "For tools/call: {name: string, arguments: object}" } } } } }, "paths": { "/api/auth/register": { "post": { "tags": [ "Authentication" ], "summary": "Register a new account", "description": "Create a new user account and organization. Returns JWT token on success.", "operationId": "register", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email", "example": "dev@mycompany.com" }, "password": { "type": "string", "minLength": 8, "example": "SecurePass123!" }, "name": { "type": "string", "example": "Jane Smith" }, "company": { "type": "string", "example": "MyCompany" } } } } } }, "responses": { "201": { "description": "Account created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Email already registered" }, "429": { "description": "Too many auth attempts" } }, "x-rate-limit": "20 per 15 minutes" } }, "/api/auth/login": { "post": { "tags": [ "Authentication" ], "summary": "Login to your account", "description": "Authenticate with email/password. Returns JWT token.", "operationId": "login", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email", "example": "dev@mycompany.com" }, "password": { "type": "string", "example": "SecurePass123!" } } } } } }, "responses": { "200": { "description": "Login successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthResponse" } } } }, "401": { "description": "Invalid credentials" }, "429": { "description": "Too many auth attempts" } }, "x-rate-limit": "20 per 15 minutes" } }, "/api/monitor/ingest": { "post": { "tags": [ "Monitor Mode" ], "summary": "Ingest an AI call report", "description": "Fire-and-forget endpoint. Report an AI/LLM call after it completes. AAIS scans for PII, injection patterns, and updates trust scores asynchronously. This endpoint responds immediately \u2014 it never adds latency to your AI pipeline.\n\n**Authentication**: API key in `Authorization: Bearer aais_xxx` header.\n\n**When to call**: After EVERY LLM call in your application. The response is instant (async processing).", "operationId": "monitorIngest", "security": [ { "APIKeyBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorIngestRequest" }, "examples": { "basic": { "summary": "Basic call report", "value": { "app_name": "CustomerSupportBot", "model": "gpt-4o", "provider": "openai", "prompt": "Help this user with their order", "response": "I'd be happy to help...", "tokens_in": 150, "tokens_out": 200, "latency_ms": 980, "status": "success" } }, "with-pii": { "summary": "Report with potential PII in prompt", "value": { "app_name": "HRAssistant", "model": "claude-3-5-sonnet-20241022", "provider": "anthropic", "prompt": "Employee John Doe (SSN 123-45-6789) submitted a leave request", "response": "Processing leave request...", "tokens_in": 320, "tokens_out": 150, "latency_ms": 1100, "status": "success" } } } } } }, "responses": { "200": { "description": "Received \u2014 async processing queued", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "received": { "type": "boolean", "example": true } } } } } }, "401": { "description": "Invalid or missing API key" }, "429": { "description": "Rate limit exceeded (100 RPM per key)" } }, "x-rate-limit": "100 per minute per API key" } }, "/api/monitor/health": { "get": { "tags": [ "Monitor Mode" ], "summary": "Monitor endpoint health check", "description": "Simple liveness probe for the monitor endpoint. No auth required.", "operationId": "monitorHealth", "responses": { "200": { "description": "Healthy", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "mode": { "type": "string", "example": "monitor" }, "version": { "type": "string", "example": "1.0.0" } } } } } } } } }, "/api/dashboard/stats": { "get": { "tags": [ "Dashboard" ], "summary": "Summary statistics", "description": "Get aggregated statistics for the org: request counts, token usage, cost, PII detections, violations, and recent activity.", "operationId": "getDashboardStats", "security": [ { "JWTBearer": [] } ], "parameters": [ { "name": "period", "in": "query", "description": "Time window for aggregation", "schema": { "type": "string", "enum": [ "24h", "7d", "30d", "90d", "all" ], "default": "30d" } } ], "responses": { "200": { "description": "Statistics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashboardStats" } } } }, "401": { "description": "Unauthorized" } } } }, "/api/dashboard/requests": { "get": { "tags": [ "Dashboard" ], "summary": "Paginated request log", "description": "List all AI requests for the org with filtering, sorting, and pagination.", "operationId": "getRequests", "security": [ { "JWTBearer": [] } ], "parameters": [ { "name": "limit", "in": "query", "description": "Results per page (max 500)", "schema": { "type": "integer", "default": 50 } }, { "name": "offset", "in": "query", "description": "Pagination offset", "schema": { "type": "integer", "default": 0 } }, { "name": "status", "in": "query", "description": "Filter by status", "schema": { "type": "string", "enum": [ "success", "error", "blocked" ] } }, { "name": "model", "in": "query", "description": "Filter by model name", "schema": { "type": "string" } }, { "name": "provider", "in": "query", "description": "Filter by provider", "schema": { "type": "string", "enum": [ "openai", "anthropic", "google", "other" ] } }, { "name": "date_from", "in": "query", "description": "Start date (Unix ms)", "schema": { "type": "integer" } }, { "name": "date_to", "in": "query", "description": "End date (Unix ms)", "schema": { "type": "integer" } }, { "name": "pii_only", "in": "query", "description": "Only requests with PII detected", "schema": { "type": "boolean" } }, { "name": "injection_only", "in": "query", "description": "Only requests with injection detected", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Request list", "content": { "application/json": { "schema": { "type": "object", "properties": { "requests": { "type": "array", "items": { "$ref": "#/components/schemas/RequestSummary" } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } } } } }, "401": { "description": "Unauthorized" } } } }, "/api/dashboard/timeline": { "get": { "tags": [ "Dashboard" ], "summary": "Request timeline / chart data", "description": "Returns time-series data for charting request volume, tokens, and cost over time.", "operationId": "getTimeline", "security": [ { "JWTBearer": [] } ], "parameters": [ { "name": "period", "in": "query", "schema": { "type": "string", "enum": [ "24h", "7d", "30d", "90d" ], "default": "7d" } }, { "name": "granularity", "in": "query", "description": "Bucket size", "schema": { "type": "string", "enum": [ "hour", "day", "week" ], "default": "day" } } ], "responses": { "200": { "description": "Timeline data points", "content": { "application/json": { "schema": { "type": "object", "properties": { "timeline": { "type": "array", "items": { "type": "object", "properties": { "ts": { "type": "integer", "description": "Bucket start (Unix ms)" }, "requests": { "type": "integer" }, "tokens": { "type": "integer" }, "cost": { "type": "number" }, "pii": { "type": "integer" }, "violations": { "type": "integer" } } } } } } } } }, "401": { "description": "Unauthorized" } } } }, "/api/dashboard/threats": { "get": { "tags": [ "Dashboard" ], "summary": "Threat intelligence summary", "description": "Returns detected threats: PII incidents, injection attempts, policy violations, and suspicious patterns.", "operationId": "getThreats", "security": [ { "JWTBearer": [] } ], "parameters": [ { "name": "period", "in": "query", "schema": { "type": "string", "enum": [ "24h", "7d", "30d" ], "default": "7d" } }, { "name": "severity", "in": "query", "schema": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] } } ], "responses": { "200": { "description": "Threat data", "content": { "application/json": { "schema": { "type": "object", "properties": { "threats": { "type": "array", "items": { "$ref": "#/components/schemas/SecurityAlert" } }, "summary": { "type": "object", "properties": { "total": { "type": "integer" }, "pii": { "type": "integer" }, "injection": { "type": "integer" }, "violations": { "type": "integer" }, "high_severity": { "type": "integer" } } } } } } } }, "401": { "description": "Unauthorized" } } } }, "/api/dashboard/pii": { "get": { "tags": [ "Dashboard" ], "summary": "PII detection report", "description": "Returns PII detection events with type breakdown (email, phone, SSN, credit card, etc.).", "operationId": "getPIIReport", "security": [ { "JWTBearer": [] } ], "parameters": [ { "name": "period", "in": "query", "schema": { "type": "string", "enum": [ "24h", "7d", "30d", "90d" ], "default": "30d" } }, { "name": "type", "in": "query", "description": "Filter by PII type", "schema": { "type": "string", "enum": [ "email", "phone", "ssn", "credit_card", "name", "address", "dob", "ip_address" ] } } ], "responses": { "200": { "description": "PII detections", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer" }, "by_type": { "type": "object", "additionalProperties": { "type": "integer" }, "example": { "email": 45, "phone": 12, "ssn": 3, "credit_card": 8 } }, "by_severity": { "type": "object", "additionalProperties": { "type": "integer" } }, "detections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "severity": { "type": "string" }, "detected_in": { "type": "string", "enum": [ "prompt", "response" ] }, "agent": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } } } } } } }, "401": { "description": "Unauthorized" } } } }, "/api/dashboard/security-score": { "get": { "tags": [ "Dashboard" ], "summary": "Composite security score", "description": "Returns a 0-100 security score with grade and breakdown by category. Factors: PII exposure rate, injection attempt rate, data leakage, compliance.", "operationId": "getSecurityScore", "security": [ { "JWTBearer": [] } ], "parameters": [ { "name": "period", "in": "query", "schema": { "type": "string", "enum": [ "7d", "30d", "90d" ], "default": "30d" } } ], "responses": { "200": { "description": "Security score", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecurityScore" } } } }, "401": { "description": "Unauthorized" } } } }, "/api/trust/overview": { "get": { "tags": [ "Trust Scores" ], "summary": "Organization trust overview", "description": "Returns the aggregate trust posture for the org: overall score, agent count, and grade distribution.", "operationId": "getTrustOverview", "security": [ { "JWTBearer": [] } ], "responses": { "200": { "description": "Trust overview", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrustOverview" } } } }, "401": { "description": "Unauthorized" } } } }, "/api/trust/agents": { "get": { "tags": [ "Trust Scores" ], "summary": "List agents with trust scores", "description": "Returns all agent profiles with their trust scores, grades, badges, and status. Each agent corresponds to one API key.", "operationId": "getTrustAgents", "security": [ { "JWTBearer": [] } ], "parameters": [ { "name": "sort", "in": "query", "description": "Sort field", "schema": { "type": "string", "enum": [ "score", "name", "grade" ], "default": "score" } }, { "name": "order", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } }, { "name": "grade", "in": "query", "description": "Filter by exact grade", "schema": { "type": "string", "enum": [ "A+", "A", "B+", "B", "C+", "C", "D", "F" ] } }, { "name": "status", "in": "query", "description": "Filter by status", "schema": { "type": "string", "enum": [ "active", "suspended", "probation" ] } } ], "responses": { "200": { "description": "Agent list", "content": { "application/json": { "schema": { "type": "object", "properties": { "agents": { "type": "array", "items": { "$ref": "#/components/schemas/AgentProfile" } }, "total": { "type": "integer" }, "sort": { "type": "string" }, "order": { "type": "string" } } } } } }, "401": { "description": "Unauthorized" } } } }, "/api/trust/agents/{id}": { "get": { "tags": [ "Trust Scores" ], "summary": "Get agent trust profile", "description": "Detailed trust profile for a single agent including score, grade, badges, and recent activity.", "operationId": "getTrustAgent", "security": [ { "JWTBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Agent profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentProfile" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Agent not found" } } } }, "/api/trust/agents/{id}/history": { "get": { "tags": [ "Trust Scores" ], "summary": "Agent trust score history", "description": "Returns the trust score time-series for an agent \u2014 useful for tracking improvement or degradation over time.", "operationId": "getTrustHistory", "security": [ { "JWTBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "period", "in": "query", "schema": { "type": "string", "enum": [ "7d", "30d", "90d" ], "default": "30d" } } ], "responses": { "200": { "description": "Score history", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "integer" }, "history": { "type": "array", "items": { "type": "object", "properties": { "ts": { "type": "integer", "description": "Unix ms" }, "score": { "type": "number" }, "grade": { "type": "string" } } } } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Agent not found" } } } }, "/api/trust/agents/{id}/events": { "get": { "tags": [ "Trust Scores" ], "summary": "Agent trust events", "description": "Returns security events (PII incidents, injections, violations) that affected this agent's trust score.", "operationId": "getTrustEvents", "security": [ { "JWTBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Events list", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "integer" }, "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "event_type": { "type": "string", "enum": [ "pii_detected", "injection_detected", "policy_violation", "score_update" ] }, "severity": { "type": "string" }, "description": { "type": "string" }, "score_delta": { "type": "number", "description": "Score change caused by this event" }, "created_at": { "type": "string", "format": "date-time" } } } }, "total": { "type": "integer" } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Agent not found" } } } }, "/v1/chat/completions": { "post": { "tags": [ "Proxy Mode" ], "summary": "OpenAI-compatible chat (proxied)", "description": "Drop-in replacement for OpenAI's `/v1/chat/completions`. Route your OpenAI SDK calls through this endpoint. AAIS will scan prompts/responses and optionally block based on your policies.\n\n**Setup**: Set `base_url` / `OPENAI_BASE_URL` to your AAIS instance URL and use your `aais_xxx` key as the API key.\n\n**Streaming**: Fully supported.", "operationId": "proxyChat", "security": [ { "APIKeyBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Standard OpenAI chat completions request body", "properties": { "model": { "type": "string", "example": "gpt-4o" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "system", "user", "assistant" ] }, "content": { "type": "string" } } } }, "stream": { "type": "boolean", "default": false } } } } } }, "responses": { "200": { "description": "OpenAI-format response (pass-through from provider)" }, "400": { "description": "Blocked by AAIS policy", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "blocked_reason": { "type": "string" }, "policy": { "type": "string" } } } } } }, "401": { "description": "Invalid API key" }, "429": { "description": "Rate limit or budget exceeded" } }, "x-rate-limit": "600 per minute" } }, "/v1/messages": { "post": { "tags": [ "Proxy Mode" ], "summary": "Anthropic-compatible messages (proxied)", "description": "Drop-in replacement for Anthropic's `/v1/messages`. Use your `aais_xxx` key as the API key and point your Anthropic SDK at your AAIS instance.", "operationId": "proxyMessages", "security": [ { "APIKeyBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Standard Anthropic messages request body" } } } }, "responses": { "200": { "description": "Anthropic-format response (pass-through)" }, "400": { "description": "Blocked by policy" }, "401": { "description": "Invalid API key" } } } }, "/health": { "get": { "tags": [ "System" ], "summary": "Server health check", "description": "No authentication required. Returns server status and uptime.", "operationId": "healthCheck", "responses": { "200": { "description": "Server healthy", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "service": { "type": "string", "example": "AgentAIShield" }, "version": { "type": "string", "example": "1.0.0" }, "timestamp": { "type": "string", "format": "date-time" }, "uptime": { "type": "integer", "description": "Uptime in seconds" }, "env": { "type": "string" } } } } } } } } }, "/api/sanitize": { "post": { "tags": [ "Sanitizer" ], "summary": "Sanitize a prompt before sending to an LLM", "description": "Pre-flight prompt sanitizer. Strips PII (12 types) and neutralizes injection attacks (8 patterns) before the prompt reaches an LLM. Supports redact, mask, and remove modes.", "security": [ { "APIKeyBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SanitizeRequest" } } } }, "responses": { "200": { "description": "Sanitized text with modification details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SanitizeResponse" } } } }, "400": { "description": "Invalid request \u2014 missing text or invalid mode" }, "401": { "description": "Invalid or missing API key" }, "429": { "description": "Rate limit exceeded (200 RPM)" } } }, "get": { "tags": [ "Sanitizer" ], "summary": "Sanitizer discovery endpoint", "description": "Returns endpoint capabilities, supported modes, and PII types.", "security": [], "responses": { "200": { "description": "Sanitizer capabilities" } } } }, "/api/scan/output": { "post": { "tags": [ "Output Scanner" ], "summary": "Scan LLM output for dangerous content", "description": "Scans AI responses for 5 threat categories: PII leaks, harmful content, code execution attempts, training data leakage, and unauthorized professional claims.", "security": [ { "APIKeyBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScanOutputRequest" } } } }, "responses": { "200": { "description": "Scan results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScanOutputResponse" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid API key" }, "429": { "description": "Rate limit exceeded (200 RPM)" } } } }, "/api/quarantine": { "get": { "tags": [ "Quarantine" ], "summary": "List all quarantined agents", "description": "Returns all agents currently in quarantine for the authenticated organization.", "security": [ { "JWTBearer": [] } ], "responses": { "200": { "description": "List of quarantined agents", "content": { "application/json": { "schema": { "type": "object", "properties": { "agents": { "type": "array", "items": { "$ref": "#/components/schemas/QuarantinedAgent" } }, "count": { "type": "integer" } } } } } } } } }, "/api/quarantine/{agentId}": { "post": { "tags": [ "Quarantine" ], "summary": "Manually quarantine an agent", "description": "Immediately isolates an agent. Quarantined agents cannot process requests through Proxy Mode.", "security": [ { "JWTBearer": [] } ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "example": "Suspected compromise \u2014 manual review required" } } } } } }, "responses": { "200": { "description": "Agent quarantined successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "agentId": { "type": "integer" }, "quarantined": { "type": "boolean" }, "quarantine_reason": { "type": "string" }, "quarantined_at": { "type": "string", "format": "date-time" } } } } } }, "404": { "description": "Agent not found" }, "409": { "description": "Agent already quarantined" } } }, "delete": { "tags": [ "Quarantine" ], "summary": "Lift quarantine from an agent", "description": "Releases an agent from quarantine and optionally resets its trust score.", "security": [ { "JWTBearer": [] } ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" }, "reset_trust_score": { "type": "boolean", "default": false } } } } } }, "responses": { "200": { "description": "Quarantine lifted" }, "404": { "description": "Agent not found or not quarantined" } } } }, "/api/quarantine/settings": { "put": { "tags": [ "Quarantine" ], "summary": "Update auto-quarantine threshold", "description": "Set the trust score threshold below which an agent is automatically quarantined.", "security": [ { "JWTBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agent_id", "threshold" ], "properties": { "agent_id": { "type": "integer" }, "threshold": { "type": "number", "minimum": 0, "maximum": 100, "description": "Auto-quarantine when trust score drops below this value" }, "enabled": { "type": "boolean", "default": true } } } } } }, "responses": { "200": { "description": "Settings updated" } } } }, "/api/budget/overview": { "get": { "tags": [ "Budget" ], "summary": "All agents budget status", "description": "Returns token budget usage and limit status for all agents in the organization.", "security": [ { "JWTBearer": [] } ], "responses": { "200": { "description": "Budget overview", "content": { "application/json": { "schema": { "type": "object", "properties": { "agents": { "type": "array", "items": { "$ref": "#/components/schemas/BudgetStatus" } }, "total_daily_used": { "type": "integer" }, "total_monthly_used": { "type": "integer" } } } } } } } } }, "/api/budget/{agentId}": { "get": { "tags": [ "Budget" ], "summary": "Single agent budget usage", "description": "Returns detailed token usage and budget status for one agent.", "security": [ { "JWTBearer": [] } ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Agent budget status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BudgetStatus" } } } } } }, "put": { "tags": [ "Budget" ], "summary": "Set budget limits for an agent", "description": "Set or update daily/monthly token limits and the action to take when exceeded (warn, throttle, block).", "security": [ { "JWTBearer": [] } ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "daily_token_limit": { "type": "integer", "nullable": true, "description": "Max tokens per day (null = no limit)" }, "monthly_token_limit": { "type": "integer", "nullable": true }, "action_on_exceed": { "type": "string", "enum": [ "warn", "throttle", "block" ], "default": "warn" } } } } } }, "responses": { "200": { "description": "Budget limits updated" } } } }, "/api/redteam/run": { "post": { "tags": [ "Red Team" ], "summary": "Start an automated red team security test", "description": "Launches an automated attack sequence against an agent to find security vulnerabilities. Tests 5 attack categories at 3 intensity levels.", "security": [ { "JWTBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedTeamRunRequest" } } } }, "responses": { "202": { "description": "Red team run started", "content": { "application/json": { "schema": { "type": "object", "properties": { "run_id": { "type": "string" }, "status": { "type": "string", "example": "pending" }, "estimated_duration_ms": { "type": "integer" } } } } } } } } }, "/api/redteam/status/{runId}": { "get": { "tags": [ "Red Team" ], "summary": "Check red team run progress", "security": [ { "JWTBearer": [] } ], "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Run status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedTeamStatus" } } } } } } }, "/api/redteam/report/{runId}": { "get": { "tags": [ "Red Team" ], "summary": "Get red team security report", "description": "Returns the full security report with grade, vulnerabilities, and per-category results.", "security": [ { "JWTBearer": [] } ], "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Security report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedTeamReport" } } } }, "404": { "description": "Run not found or not completed yet" } } } }, "/api/redteam/runs": { "get": { "tags": [ "Red Team" ], "summary": "List past red team runs", "security": [ { "JWTBearer": [] } ], "parameters": [ { "name": "agent_id", "in": "query", "schema": { "type": "integer" }, "description": "Filter by agent" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "List of past runs", "content": { "application/json": { "schema": { "type": "object", "properties": { "runs": { "type": "array", "items": { "$ref": "#/components/schemas/RedTeamStatus" } }, "count": { "type": "integer" } } } } } } } } }, "/api/trust/verify/{agentId}": { "get": { "tags": [ "Trust Verification" ], "summary": "Verify another agent's trust", "description": "Allows one agent to verify the trustworthiness of another agent before sharing data. Returns a recommendation: safe_to_share, share_with_caution, or do_not_share.", "security": [ { "APIKeyBearer": [] } ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the agent to verify" } ], "responses": { "200": { "description": "Trust verification result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrustVerification" } } } }, "404": { "description": "Agent not found" } } } }, "/api/trust/verify-history": { "get": { "tags": [ "Trust Verification" ], "summary": "Past trust verifications", "description": "Returns a log of all trust verification checks performed by this API key.", "security": [ { "APIKeyBearer": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Verification history", "content": { "application/json": { "schema": { "type": "object", "properties": { "verifications": { "type": "array", "items": { "$ref": "#/components/schemas/TrustVerification" } }, "total": { "type": "integer" } } } } } } } } }, "/api/threat-intel/feed": { "get": { "tags": [ "Threat Intelligence" ], "summary": "Shared threat pattern feed", "description": "Returns anonymized attack patterns observed across the AAIS community. Patterns are stripped of org-identifying info before sharing.", "security": [ { "JWTBearer": [] } ], "parameters": [ { "name": "severity", "in": "query", "schema": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } } ], "responses": { "200": { "description": "Threat feed", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ThreatFeedItem" } }, "count": { "type": "integer" }, "last_updated": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/threat-intel/trending": { "get": { "tags": [ "Threat Intelligence" ], "summary": "Top trending threats", "description": "Returns the most active attack patterns in the last 24 hours, sorted by occurrence count.", "security": [ { "JWTBearer": [] } ], "responses": { "200": { "description": "Trending threats", "content": { "application/json": { "schema": { "type": "object", "properties": { "trending": { "type": "array", "items": { "$ref": "#/components/schemas/ThreatFeedItem" } }, "period": { "type": "string", "example": "24h" } } } } } } } } }, "/api/threat-intel/stats": { "get": { "tags": [ "Threat Intelligence" ], "summary": "Threat intelligence statistics", "description": "Returns aggregate statistics about the global threat landscape seen by AAIS.", "security": [ { "JWTBearer": [] } ], "responses": { "200": { "description": "Threat stats", "content": { "application/json": { "schema": { "type": "object", "properties": { "total_patterns": { "type": "integer" }, "patterns_last_24h": { "type": "integer" }, "top_attack_type": { "type": "string" }, "participating_orgs": { "type": "integer" }, "attacks_blocked_total": { "type": "integer" } } } } } } } } }, "/api/compliance/report": { "post": { "tags": [ "Compliance" ], "summary": "Generate a compliance report", "description": "Generates a compliance report for SOC2, HIPAA, GDPR, or all frameworks. Analyzes audit data for the specified period.", "security": [ { "JWTBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComplianceReportRequest" } } } }, "responses": { "200": { "description": "Report generated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComplianceReport" } } } } } } }, "/api/compliance/reports": { "get": { "tags": [ "Compliance" ], "summary": "List compliance reports", "security": [ { "JWTBearer": [] } ], "parameters": [ { "name": "framework", "in": "query", "schema": { "type": "string", "enum": [ "soc2", "hipaa", "gdpr", "all" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "Report list", "content": { "application/json": { "schema": { "type": "object", "properties": { "reports": { "type": "array", "items": { "$ref": "#/components/schemas/ComplianceReport" } }, "total": { "type": "integer" } } } } } } } } }, "/api/compliance/reports/{id}": { "get": { "tags": [ "Compliance" ], "summary": "Fetch a specific compliance report", "security": [ { "JWTBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Report detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComplianceReport" } } } }, "404": { "description": "Report not found" } } }, "delete": { "tags": [ "Compliance" ], "summary": "Delete a compliance report", "security": [ { "JWTBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Report deleted" }, "404": { "description": "Report not found" } } } }, "/api/fingerprint": { "get": { "tags": [ "Fingerprinting" ], "summary": "All agents fingerprint status", "description": "Returns behavioral fingerprint status for all agents \u2014 whether baselines are established and current anomaly scores.", "security": [ { "JWTBearer": [] } ], "responses": { "200": { "description": "Fingerprint summary for all agents", "content": { "application/json": { "schema": { "type": "object", "properties": { "agents": { "type": "array", "items": { "$ref": "#/components/schemas/FingerprintProfile" } }, "count": { "type": "integer" } } } } } } } } }, "/api/fingerprint/{id}": { "get": { "tags": [ "Fingerprinting" ], "summary": "Agent behavioral fingerprint profile", "description": "Returns the full behavioral profile for one agent \u2014 baseline dimensions, anomaly score, and recent behavior.", "security": [ { "JWTBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Fingerprint profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FingerprintProfile" } } } }, "404": { "description": "Agent not found" } } } }, "/api/fingerprint/{id}/anomalies": { "get": { "tags": [ "Fingerprinting" ], "summary": "Anomaly timeline for an agent", "description": "Returns chronological anomaly events detected for this agent, with severity and Z-score details.", "security": [ { "JWTBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }, { "name": "severity", "in": "query", "schema": { "type": "string", "enum": [ "warning", "critical" ] } } ], "responses": { "200": { "description": "Anomaly events", "content": { "application/json": { "schema": { "type": "object", "properties": { "anomalies": { "type": "array", "items": { "$ref": "#/components/schemas/AnomalyEvent" } }, "count": { "type": "integer" } } } } } } } } }, "/api/fingerprint/{id}/reset": { "post": { "tags": [ "Fingerprinting" ], "summary": "Reset agent behavioral baseline", "description": "Clears the existing behavioral baseline. AAIS will rebuild from scratch using the next 500 requests.", "security": [ { "JWTBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Baseline reset \u2014 will rebuild from next 500 requests" }, "404": { "description": "Agent not found" } } } }, "/api/fingerprint/{id}/refresh": { "post": { "tags": [ "Fingerprinting" ], "summary": "Force recompute behavioral fingerprint", "description": "Immediately recomputes the behavioral profile from existing request history, without waiting for new data.", "security": [ { "JWTBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Fingerprint recomputed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FingerprintProfile" } } } }, "404": { "description": "Agent not found" } } } }, "/api/mcp": { "get": { "tags": [ "MCP Server" ], "summary": "MCP server discovery", "description": "Returns MCP server metadata and list of available tools for MCP-compatible agents.", "security": [ { "APIKeyBearer": [] } ], "responses": { "200": { "description": "MCP server info and tools", "content": { "application/json": { "schema": { "type": "object", "properties": { "protocol_version": { "type": "string", "example": "2024-11-05" }, "server_name": { "type": "string", "example": "AgentAIShield" }, "tools": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "inputSchema": { "type": "object" } } } } } } } } } } }, "post": { "tags": [ "MCP Server" ], "summary": "MCP JSON-RPC endpoint", "description": "MCP Streamable HTTP Transport (JSON-RPC 2.0). Supports initialize, tools/list, and tools/call.\n\n**Available MCP tools:**\n- `scan_prompt` \u2014 Scan a prompt for PII and injection\n- `report_interaction` \u2014 Fire-and-forget monitoring ingest\n- `get_trust_score` \u2014 Fetch agent trust score\n- `check_budget` \u2014 Check remaining token budget\n- `verify_agent` \u2014 Cross-agent trust verification", "security": [ { "APIKeyBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MCPRequest" } } } }, "responses": { "200": { "description": "JSON-RPC 2.0 response", "content": { "application/json": { "schema": { "type": "object", "properties": { "jsonrpc": { "type": "string", "example": "2.0" }, "id": { "type": "string" }, "result": { "type": "object" }, "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } } } } } } } }, "401": { "description": "Invalid API key" } } } } }, "tags": [ { "name": "Authentication", "description": "Register, login, and manage sessions" }, { "name": "Monitor Mode", "description": "Passive AI traffic ingestion \u2014 fire-and-forget, zero latency impact" }, { "name": "Dashboard", "description": "Statistics, request logs, PII reports, and security scores (JWT auth)" }, { "name": "Trust Scores", "description": "Agent Trust Score\u2122 \u2014 per-agent behavioral scoring and badges" }, { "name": "Trust Verification", "description": "Cross-agent trust verification \u2014 verify another agent's trustworthiness" }, { "name": "Sanitizer", "description": "Pre-flight prompt sanitizer \u2014 strip PII and neutralize injection before the LLM" }, { "name": "Output Scanner", "description": "Scan LLM responses for dangerous content, PII leaks, and harmful instructions" }, { "name": "Quarantine", "description": "Agent quarantine \u2014 auto-kill switch and manual isolation controls" }, { "name": "Budget", "description": "Token budget enforcement \u2014 daily/monthly limits with cost anomaly detection" }, { "name": "Red Team", "description": "Automated security testing \u2014 attack your own agents to find vulnerabilities" }, { "name": "Threat Intelligence", "description": "Cross-org anonymized threat feed \u2014 community-shared attack patterns" }, { "name": "Compliance", "description": "SOC2, HIPAA, GDPR compliance report generation" }, { "name": "Fingerprinting", "description": "Behavioral fingerprinting \u2014 baseline and anomaly detection per agent" }, { "name": "MCP Server", "description": "Model Context Protocol server \u2014 zero-code integration for MCP-compatible agents" }, { "name": "Proxy Mode", "description": "OpenAI/Anthropic-compatible proxy endpoints with inline scanning" }, { "name": "System", "description": "Health checks and service discovery" } ] }