{"openapi":"3.0.3","info":{"title":"Execlave API","description":"AI Agent Governance Platform — Comprehensive API for managing agents, policies, traces, incidents, and more.\n\n## Authentication\nAll protected endpoints require one of:\n- **Bearer JWT** — Logto-issued JWT in `Authorization: Bearer <token>`\n- **API Key** — Execlave API key in `X-API-Key` header or `Authorization: Bearer exe_*`\n\n## Multi-tenancy\nAll data is scoped to the authenticated organization via PostgreSQL Row-Level Security.","version":"1.0.0","contact":{"name":"Execlave Team"},"license":{"name":"MIT"}},"servers":[{"url":"/api/v1","description":"API v1 (current)"},{"url":"/api","description":"Unversioned (deprecated — use /api/v1)"}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Logto JWT token"},"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Execlave API Key (exe_*)"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"NOT_FOUND"},"message":{"type":"string","example":"Resource not found"},"fields":{"type":"object","additionalProperties":{"type":"string"},"description":"Validation field errors (only on 422)"}}}}},"PaginationMeta":{"type":"object","properties":{"total":{"type":"integer","example":42},"limit":{"type":"integer","example":50},"offset":{"type":"integer","example":0}}},"Webhook":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"url":{"type":"string","format":"uri"},"eventTypes":{"type":"array","items":{"type":"string","enum":["agent_registered","agent_updated","agent_deleted","trace_completed","trace_error","policy_violated","kill_switch_triggered","limit_exceeded","prompt_approved","prompt_deployed","budget_warning","budget_exceeded","alert_triggered","custom_validator_invoked","custom_validator_denied","custom_validator_failed"]}},"agentIds":{"type":"array","items":{"type":"string","format":"uuid"},"nullable":true,"description":"Scope webhook to specific agents (null = all)"},"isActive":{"type":"boolean"},"maxRetries":{"type":"integer"},"retryBackoffSeconds":{"type":"integer"},"timeoutSeconds":{"type":"integer"},"customHeaders":{"type":"object","additionalProperties":{"type":"string"}},"successCount":{"type":"integer"},"failureCount":{"type":"integer"},"lastTriggeredAt":{"type":"string","format":"date-time","nullable":true},"lastSuccessAt":{"type":"string","format":"date-time","nullable":true},"lastFailureAt":{"type":"string","format":"date-time","nullable":true},"lastFailureReason":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"},"nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"type":"string"}}},"CreateWebhookInput":{"type":"object","required":["name","url","eventTypes"],"properties":{"name":{"type":"string","minLength":1},"description":{"type":"string"},"url":{"type":"string","format":"uri"},"eventTypes":{"type":"array","items":{"type":"string","enum":["agent_registered","agent_updated","agent_deleted","trace_completed","trace_error","policy_violated","kill_switch_triggered","limit_exceeded","prompt_approved","prompt_deployed","budget_warning","budget_exceeded","alert_triggered","custom_validator_invoked","custom_validator_denied","custom_validator_failed"]},"minItems":1},"agentIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Optional list of agent UUIDs to scope webhook"},"maxRetries":{"type":"integer","default":5},"retryBackoffSeconds":{"type":"integer","default":60},"timeoutSeconds":{"type":"integer","default":30},"customHeaders":{"type":"object","additionalProperties":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}},"notes":{"type":"string"}}},"UpdateWebhookInput":{"type":"object","description":"All fields optional — only provided fields are updated.","properties":{"name":{"type":"string"},"description":{"type":"string"},"url":{"type":"string","format":"uri"},"eventTypes":{"type":"array","items":{"type":"string"},"minItems":1},"agentIds":{"type":"array","items":{"type":"string","format":"uuid"}},"isActive":{"type":"boolean"},"maxRetries":{"type":"integer"},"retryBackoffSeconds":{"type":"integer"},"timeoutSeconds":{"type":"integer"},"customHeaders":{"type":"object","additionalProperties":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}},"notes":{"type":"string"}}},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"webhookId":{"type":"string","format":"uuid"},"eventType":{"type":"string"},"payload":{"type":"object"},"statusCode":{"type":"integer","nullable":true},"responseBody":{"type":"string","nullable":true},"success":{"type":"boolean"},"attemptNumber":{"type":"integer"},"errorMessage":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"Trace":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"traceId":{"type":"string","description":"External trace identifier"},"agentId":{"type":"string","format":"uuid"},"parentTraceId":{"type":"string","nullable":true},"timestamp":{"type":"string","format":"date-time"},"durationMs":{"type":"integer","nullable":true},"status":{"type":"string","enum":["success","error","timeout","policy_blocked","limit_exceeded"]},"input":{"type":"object","nullable":true},"output":{"type":"object","nullable":true},"errorMessage":{"type":"string","nullable":true},"errorType":{"type":"string","nullable":true},"modelName":{"type":"string","nullable":true},"promptTokens":{"type":"integer","nullable":true},"completionTokens":{"type":"integer","nullable":true},"totalTokens":{"type":"integer","nullable":true},"costUsd":{"type":"number","nullable":true},"environment":{"type":"string","enum":["development","staging","production"]},"version":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"},"nullable":true},"metadata":{"type":"object","nullable":true},"userId":{"type":"string","nullable":true},"sessionId":{"type":"string","nullable":true},"spanType":{"type":"string","enum":["root","agent","llm_call","tool_call","retrieval","middleware","custom"]},"spanName":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"IngestTracesInput":{"type":"object","required":["traces"],"properties":{"traces":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"object","required":["traceId"],"properties":{"traceId":{"type":"string","minLength":1},"agentId":{"type":"string","description":"External agent ID"},"agentUuid":{"type":"string","format":"uuid","description":"Internal agent UUID (alternative to agentId)"},"parentTraceId":{"type":"string","nullable":true},"timestamp":{"type":"string","format":"date-time"},"durationMs":{"type":"integer","nullable":true},"status":{"type":"string","enum":["success","error","timeout","policy_blocked","limit_exceeded"]},"input":{"type":"object","nullable":true},"output":{"type":"object","nullable":true},"errorMessage":{"type":"string","nullable":true},"errorType":{"type":"string","nullable":true},"modelName":{"type":"string","nullable":true},"promptTokens":{"type":"integer","nullable":true},"completionTokens":{"type":"integer","nullable":true},"totalTokens":{"type":"integer","nullable":true},"costUsd":{"type":"number","nullable":true},"environment":{"type":"string","enum":["development","staging","production"]},"version":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"},"nullable":true},"metadata":{"type":"object","nullable":true},"userId":{"type":"string","nullable":true},"sessionId":{"type":"string","nullable":true},"spanType":{"type":"string","enum":["root","agent","llm_call","tool_call","retrieval","middleware","custom"]},"spanName":{"type":"string","maxLength":255,"nullable":true}}}}}},"Team":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"memberCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"TeamMember":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"name":{"type":"string"},"role":{"type":"string"},"addedAt":{"type":"string","format":"date-time"}}},"CreateTeamInput":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string","maxLength":500}}},"UpdateTeamInput":{"type":"object","description":"All fields optional","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string","maxLength":500}}},"SavedFilter":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"userId":{"type":"string"},"name":{"type":"string"},"resourceType":{"type":"string","enum":["agents","incidents","traces","policies","executions"]},"filterConfig":{"type":"object","additionalProperties":true,"description":"Arbitrary filter configuration"},"isDefault":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"CreateSavedFilterInput":{"type":"object","required":["name","resource_type"],"properties":{"name":{"type":"string","minLength":1,"maxLength":100},"resource_type":{"type":"string","enum":["agents","incidents","traces","policies","executions"]},"filter_config":{"type":"object","additionalProperties":true,"default":{}},"is_default":{"type":"boolean","default":false}}},"UpdateSavedFilterInput":{"type":"object","description":"All fields optional","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"filter_config":{"type":"object","additionalProperties":true},"is_default":{"type":"boolean"}}},"PromptVersion":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"agentId":{"type":"string","format":"uuid"},"versionNumber":{"type":"integer"},"versionTag":{"type":"string","nullable":true},"promptTemplate":{"type":"string"},"systemMessage":{"type":"string","nullable":true},"modelName":{"type":"string","nullable":true},"temperature":{"type":"number","nullable":true},"maxTokens":{"type":"integer","nullable":true},"otherParams":{"type":"object","additionalProperties":true},"approvalStatus":{"type":"string","enum":["pending","approved","rejected"]},"submittedBy":{"type":"string"},"submittedByName":{"type":"string","nullable":true},"submittedAt":{"type":"string","format":"date-time"},"approvedBy":{"type":"string","nullable":true},"approvedAt":{"type":"string","format":"date-time","nullable":true},"rejectedBy":{"type":"string","nullable":true},"rejectedAt":{"type":"string","format":"date-time","nullable":true},"rejectionReason":{"type":"string","nullable":true},"deployedBy":{"type":"string","nullable":true},"deployedAt":{"type":"string","format":"date-time","nullable":true},"deploymentEnvironment":{"type":"string","nullable":true},"isActive":{"type":"boolean"},"previousVersionId":{"type":"string","format":"uuid","nullable":true},"changeSummary":{"type":"string","nullable":true},"testResults":{"type":"object","nullable":true},"testPassed":{"type":"boolean","nullable":true},"notes":{"type":"string","nullable":true},"agentName":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"CreatePromptVersionInput":{"type":"object","required":["agentId","promptTemplate"],"properties":{"agentId":{"type":"string","format":"uuid"},"promptTemplate":{"type":"string","minLength":1},"systemMessage":{"type":"string"},"modelName":{"type":"string"},"temperature":{"type":"number","minimum":0,"maximum":2},"maxTokens":{"type":"integer","minimum":1},"otherParams":{"type":"object","additionalProperties":true},"changeSummary":{"type":"string"},"versionTag":{"type":"string","maxLength":100},"notes":{"type":"string"},"testResults":{"type":"object"}}},"PolicyViolation":{"type":"object","description":"One policy match from an enforcement decision. The same shape is used for blocking matches and for non-blocking warnings — `enforcementMode` is what distinguishes them.\n","properties":{"policyId":{"type":"string","format":"uuid"},"policyName":{"type":"string"},"policyType":{"type":"string","description":"One of the built-in policy types, e.g. injection_scan, pii_access."},"message":{"type":"string","description":"Human-readable reason this policy matched."},"enforcementMode":{"type":"string","enum":["block","warn","monitor","require_approval"]}}},"Policy":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"policyType":{"type":"string","enum":["access_control","data_restriction","action_approval","cost_limit","quality_threshold","budget_cap","injection_scan","output_classifier","custom"]},"appliesToAgents":{"type":"array","items":{"type":"string","format":"uuid"}},"appliesToEnvironments":{"type":"array","items":{"type":"string","enum":["development","staging","production"]}},"ruleDefinition":{"type":"object","description":"Flexible JSONB rule definition"},"enforcementMode":{"type":"string","enum":["block","warn","monitor"]},"isActive":{"type":"boolean"},"alertOnViolation":{"type":"boolean"},"alertChannels":{"type":"array","items":{"type":"string"}},"complianceFrameworks":{"type":"array","items":{"type":"string"}},"complianceControls":{"type":"array","items":{"type":"string"}},"severity":{"type":"string","enum":["info","warning","critical"]},"actions":{"type":"array","items":{"type":"string","enum":["log","block","notify","alert"]}},"agentId":{"type":"string","format":"uuid","nullable":true},"priority":{"type":"integer"},"maxRequests":{"type":"integer","nullable":true},"timeWindowSeconds":{"type":"integer","nullable":true},"notifyWebhookUrl":{"type":"string","nullable":true},"notifyEmail":{"type":"array","items":{"type":"string","format":"email"}},"notes":{"type":"string","nullable":true},"createdBy":{"type":"string","format":"uuid"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"tags":{"type":"array","items":{"type":"string"}}}},"CreatePolicyInput":{"type":"object","required":["name","policyType","ruleDefinition","enforcementMode"],"properties":{"name":{"type":"string","minLength":1,"maxLength":255},"description":{"type":"string"},"policyType":{"type":"string","enum":["access_control","data_restriction","action_approval","cost_limit","quality_threshold","budget_cap","injection_scan","output_classifier","custom"]},"appliesToAgents":{"type":"array","items":{"type":"string","format":"uuid"},"default":[]},"appliesToEnvironments":{"type":"array","items":{"type":"string","enum":["development","staging","production"]},"default":[]},"ruleDefinition":{"type":"object","description":"Flexible JSONB rule definition"},"enforcementMode":{"type":"string","enum":["block","warn","monitor"]},"isActive":{"type":"boolean","default":true},"alertOnViolation":{"type":"boolean","default":true},"alertChannels":{"type":"array","items":{"type":"string"},"default":[]},"complianceFrameworks":{"type":"array","items":{"type":"string"},"default":[]},"complianceControls":{"type":"array","items":{"type":"string"},"default":[]},"severity":{"type":"string","enum":["info","warning","critical"],"default":"warning"},"actions":{"type":"array","items":{"type":"string","enum":["log","block","notify","alert"]},"default":["log"]},"agentId":{"type":"string","format":"uuid","nullable":true},"priority":{"type":"integer","minimum":0,"default":100},"maxRequests":{"type":"integer","nullable":true},"timeWindowSeconds":{"type":"integer","nullable":true},"notifyWebhookUrl":{"type":"string","format":"uri","maxLength":500,"nullable":true},"notifyEmail":{"type":"array","items":{"type":"string","format":"email"},"default":[]},"notes":{"type":"string","nullable":true}}},"UpdatePolicyInput":{"type":"object","description":"All fields from CreatePolicyInput, all optional","properties":{"name":{"type":"string"},"description":{"type":"string"},"policyType":{"type":"string","enum":["access_control","data_restriction","action_approval","cost_limit","quality_threshold","budget_cap","injection_scan","output_classifier","custom"]},"enforcementMode":{"type":"string","enum":["block","warn","monitor"]},"isActive":{"type":"boolean"},"severity":{"type":"string","enum":["info","warning","critical"]},"priority":{"type":"integer","minimum":0}}},"SecuritySettings":{"type":"object","properties":{"ipAllowlist":{"type":"array","items":{"type":"string","format":"ip"},"description":"List of allowed IP addresses"},"allowedEnvironments":{"type":"array","items":{"type":"string"},"example":["production","staging","development"]},"defaultKeyExpiryDays":{"type":"integer","minimum":1,"maximum":365,"default":30},"enforceMfa":{"type":"boolean","default":false},"dashboardWidgets":{"type":"array","items":{"type":"string"},"example":["stats","actions","activity","hardening"]}}},"UpdateSecuritySettingsInput":{"type":"object","description":"All fields optional — only provided fields are updated.","properties":{"ip_allowlist":{"type":"array","items":{"type":"string","format":"ip"}},"allowed_environments":{"type":"array","items":{"type":"string"}},"default_key_expiry_days":{"type":"integer","minimum":1,"maximum":365},"enforce_mfa":{"type":"boolean"},"dashboard_widgets":{"type":"array","items":{"type":"string"}}}},"OrgSettings":{"type":"object","properties":{"plan":{"type":"string","enum":["free","starter","professional","enterprise"]},"complianceFrameworks":{"type":"array","items":{"type":"string"},"description":"e.g. SOC2, HIPAA, GDPR"},"dataResidency":{"type":"string","enum":["us","eu","ap","global"]}}},"UpdateOrgSettingsInput":{"type":"object","description":"All fields optional — only provided fields are updated.","properties":{"plan":{"type":"string","enum":["free","starter","professional","enterprise"]},"compliance_frameworks":{"type":"array","items":{"type":"string"}},"data_residency":{"type":"string","enum":["us","eu","ap","global"]}}},"Orchestration":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"graph":{"$ref":"#/components/schemas/OrchestrationGraph"},"rootAgentId":{"type":"string","format":"uuid"},"enabled":{"type":"boolean"},"metadata":{"type":"object","additionalProperties":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"OrchestrationGraph":{"type":"object","properties":{"nodes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"agentId":{"type":"string","format":"uuid"},"label":{"type":"string"},"type":{"type":"string","enum":["agent","tool","router","aggregator"]},"config":{"type":"object","additionalProperties":true}}}},"edges":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"target":{"type":"string"},"condition":{"type":"string"},"label":{"type":"string"}}}}}},"CreateOrchestrationInput":{"type":"object","required":["name","graph","rootAgentId"],"properties":{"name":{"type":"string","minLength":1,"maxLength":255},"description":{"type":"string","maxLength":2000},"graph":{"$ref":"#/components/schemas/OrchestrationGraph"},"rootAgentId":{"type":"string","format":"uuid"},"enabled":{"type":"boolean","default":true},"metadata":{"type":"object","additionalProperties":true}}},"UpdateOrchestrationInput":{"type":"object","description":"All fields optional. If graph is updated, it will be re-validated.","properties":{"name":{"type":"string","minLength":1,"maxLength":255},"description":{"type":"string","maxLength":2000},"graph":{"$ref":"#/components/schemas/OrchestrationGraph"},"rootAgentId":{"type":"string","format":"uuid"},"enabled":{"type":"boolean"},"metadata":{"type":"object","additionalProperties":true}}},"NotificationChannel":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"name":{"type":"string"},"channelType":{"type":"string","enum":["email","slack","pagerduty","webhook"]},"configuration":{"type":"object","additionalProperties":true},"isActive":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"Incident":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"severity":{"type":"string","enum":["critical","high","medium","low"]},"status":{"type":"string","enum":["open","investigating","resolved","closed","false_positive"]},"category":{"type":"string","enum":["performance","error","error_spike","hallucination","security","policy_violation","data_quality","other"],"nullable":true},"agentId":{"type":"string","format":"uuid","nullable":true},"agentName":{"type":"string","nullable":true},"traceId":{"type":"string","nullable":true},"assignedTeamId":{"type":"string","format":"uuid","nullable":true},"assignedUserId":{"type":"string","format":"uuid","nullable":true},"firstOccurredAt":{"type":"string","format":"date-time","nullable":true},"detectedAt":{"type":"string","format":"date-time","nullable":true},"resolvedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"CreateIncidentInput":{"type":"object","required":["title","severity"],"properties":{"title":{"type":"string","minLength":1,"maxLength":500},"description":{"type":"string"},"severity":{"type":"string","enum":["critical","high","medium","low"]},"category":{"type":"string","enum":["performance","error","error_spike","hallucination","security","policy_violation","data_quality","other"]},"agentId":{"type":"string","format":"uuid"},"traceId":{"type":"string"}}},"UpdateIncidentInput":{"type":"object","properties":{"status":{"type":"string","enum":["open","investigating","resolved","closed","false_positive"]},"severity":{"type":"string","enum":["critical","high","medium","low"]},"assignedTeamId":{"type":"string","format":"uuid","nullable":true},"assignedUserId":{"type":"string","format":"uuid","nullable":true},"resolution":{"type":"string","description":"Resolution notes (when closing/resolving)"}}},"HealthResponse":{"type":"object","properties":{"status":{"type":"string","enum":["healthy","degraded","unhealthy"],"description":"healthy = all systems operational, degraded = partial failure (DB or Redis), unhealthy = both DB and Redis unreachable\n"},"timestamp":{"type":"string","format":"date-time"},"service":{"type":"string","example":"execlave-backend"},"version":{"type":"string","example":"0.1.0"},"database":{"type":"string","enum":["connected","disconnected"]},"redis":{"type":"string","enum":["connected","disconnected"]}}},"AuditLogEntry":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"userId":{"type":"string"},"userName":{"type":"string","nullable":true},"userEmail":{"type":"string","nullable":true},"action":{"type":"string","description":"Action identifier (e.g. agent.created, policy.updated)"},"resourceType":{"type":"string"},"resourceId":{"type":"string","nullable":true},"beforeState":{"type":"object","nullable":true,"description":"Resource state before the action"},"afterState":{"type":"object","nullable":true,"description":"Resource state after the action"},"metadata":{"type":"object","nullable":true},"ipAddress":{"type":"string","nullable":true},"userAgent":{"type":"string","nullable":true},"result":{"type":"string","enum":["success","failure"],"nullable":true},"errorMessage":{"type":"string","nullable":true},"checksum":{"type":"string","description":"SHA-256 checksum for tamper detection"},"timestamp":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"}}},"ApiKey":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"keyPrefix":{"type":"string","description":"First 15 characters of the key for identification","example":"exe_prod_abc1234"},"environment":{"type":"string","enum":["development","staging","production"]},"scopes":{"type":"array","items":{"type":"string","enum":["agent:read","agent:write","trace:read","trace:write","policy:read","policy:write","analytics:read"]}},"expiresAt":{"type":"string","format":"date-time","nullable":true},"lastUsedAt":{"type":"string","format":"date-time","nullable":true},"usageCount":{"type":"integer"},"isActive":{"type":"boolean"},"ipAllowlist":{"type":"array","items":{"type":"string"},"nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"type":"string"}}},"CreateApiKeyInput":{"type":"object","required":["name","environment"],"properties":{"name":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string","maxLength":500,"nullable":true},"environment":{"type":"string","enum":["development","staging","production"]},"scopes":{"type":"array","items":{"type":"string","enum":["agent:read","agent:write","trace:read","trace:write","policy:read","policy:write","analytics:read"]},"description":"Defaults to agent + trace read/write"},"expiresAt":{"type":"string","format":"date-time","nullable":true,"description":"Must be in the future if provided"},"ipAllowlist":{"type":"array","items":{"type":"string","description":"IPv4 address or CIDR"},"nullable":true}}},"AnomalyConfig":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"agentId":{"type":"string","format":"uuid","nullable":true},"metricName":{"type":"string"},"enabled":{"type":"boolean"},"sensitivity":{"type":"string","enum":["low","medium","high","custom"]},"zThreshold":{"type":"number"},"minSamples":{"type":"integer"},"seasonal":{"type":"boolean"},"autoIncident":{"type":"boolean"},"cooldownMinutes":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"UpsertAnomalyConfigInput":{"type":"object","required":["metricName"],"properties":{"agentId":{"type":"string","format":"uuid","nullable":true,"description":"Scope config to a specific agent (null for org-wide)"},"metricName":{"type":"string","minLength":1,"maxLength":64},"enabled":{"type":"boolean","default":true},"sensitivity":{"type":"string","enum":["low","medium","high","custom"],"default":"medium"},"zThreshold":{"type":"number","minimum":1,"maximum":10,"default":3},"minSamples":{"type":"integer","minimum":5,"maximum":1000,"default":30},"seasonal":{"type":"boolean","default":true},"autoIncident":{"type":"boolean","default":false},"cooldownMinutes":{"type":"integer","minimum":1,"maximum":1440,"default":30}}},"RunDetectionInput":{"type":"object","properties":{"agentId":{"type":"string","format":"uuid"},"metric":{"type":"string","enum":["duration_ms","estimated_cost_usd","total_tokens"],"default":"duration_ms"},"sensitivity":{"type":"string","enum":["low","medium","high","custom"],"default":"medium"},"zThreshold":{"type":"number","minimum":1,"maximum":10,"default":3},"timeWindowHours":{"type":"integer","minimum":1,"maximum":720,"default":24},"learn":{"type":"boolean","default":true}}},"RunRCAInput":{"type":"object","required":["incidentId"],"properties":{"incidentId":{"type":"string","format":"uuid"},"windowHours":{"type":"integer","minimum":1,"maximum":48,"default":4}}},"RunForecastInput":{"type":"object","properties":{"agentId":{"type":"string","format":"uuid"},"metric":{"type":"string","enum":["duration_ms","estimated_cost_usd","total_tokens"],"default":"duration_ms"},"forecastHorizonHours":{"type":"integer","minimum":1,"maximum":168,"default":24},"threshold":{"type":"number","description":"Optional threshold for breach probability calculation"},"modelType":{"type":"string","enum":["ewma","linear","holt_winters","ensemble"],"default":"ensemble"},"lookbackHours":{"type":"integer","minimum":1,"maximum":720,"default":168}}},"RebuildBaselinesInput":{"type":"object","properties":{"agentId":{"type":"string","format":"uuid","description":"Optional — rebuild only for this agent"},"metrics":{"type":"array","items":{"type":"string","enum":["duration_ms","estimated_cost_usd","total_tokens"]},"default":["duration_ms","estimated_cost_usd","total_tokens"]},"lookbackHours":{"type":"integer","minimum":1,"maximum":720,"default":168}}},"AlertRule":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"name":{"type":"string"},"type":{"type":"string"},"metric":{"type":"string"},"threshold":{"type":"number"},"windowMinutes":{"type":"integer"},"severity":{"type":"string","enum":["critical","high","medium","low"]},"enabled":{"type":"boolean"},"notifyChannels":{"type":"array","items":{"type":"string"}},"agentId":{"type":"string","format":"uuid","nullable":true},"description":{"type":"string","nullable":true},"createdBy":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"CreateAlertRuleInput":{"type":"object","required":["name","type","metric","threshold"],"properties":{"name":{"type":"string","minLength":1,"maxLength":255},"type":{"type":"string","minLength":1,"maxLength":100},"metric":{"type":"string","minLength":1,"maxLength":100},"threshold":{"type":"number"},"windowMinutes":{"type":"integer","minimum":1,"maximum":1440,"default":5},"severity":{"type":"string","enum":["critical","high","medium","low"],"default":"medium"},"enabled":{"type":"boolean","default":true},"notifyChannels":{"type":"array","items":{"type":"string"},"default":["email"]},"agentId":{"type":"string","format":"uuid","description":"Optional — scope rule to a specific agent"},"description":{"type":"string","maxLength":1000}}},"UpdateAlertRuleInput":{"type":"object","description":"All fields from CreateAlertRuleInput, all optional","properties":{"name":{"type":"string"},"type":{"type":"string"},"metric":{"type":"string"},"threshold":{"type":"number"},"windowMinutes":{"type":"integer"},"severity":{"type":"string","enum":["critical","high","medium","low"]},"enabled":{"type":"boolean"},"notifyChannels":{"type":"array","items":{"type":"string"}},"agentId":{"type":"string","format":"uuid"},"description":{"type":"string"}}},"AlertHistoryEntry":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"ruleId":{"type":"string","format":"uuid"},"ruleName":{"type":"string"},"metric":{"type":"string"},"actualValue":{"type":"number"},"thresholdValue":{"type":"number"},"severity":{"type":"string","enum":["critical","high","medium","low"]},"agentId":{"type":"string","format":"uuid","nullable":true},"agentName":{"type":"string","nullable":true},"status":{"type":"string","enum":["triggered","acknowledged","resolved"]},"acknowledgedBy":{"type":"string","nullable":true},"acknowledgedAt":{"type":"string","format":"date-time","nullable":true},"resolvedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"Agent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"agentId":{"type":"string","description":"External agent identifier"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"type":{"type":"string","enum":["chatbot","workflow","autonomous","copilot"]},"platform":{"type":"string","enum":["openai","azure_openai","anthropic","langchain","crewai","custom"]},"frameworkVersion":{"type":"string","nullable":true},"modelProvider":{"type":"string","nullable":true},"ownerUserId":{"type":"string","format":"uuid","nullable":true},"teamId":{"type":"string","format":"uuid","nullable":true},"environment":{"type":"string","enum":["development","staging","production"]},"deploymentUrl":{"type":"string","nullable":true},"status":{"type":"string","enum":["active","paused","archived"]},"healthStatus":{"type":"string","enum":["healthy","degraded","failing","unknown"]},"lastSeenAt":{"type":"string","format":"date-time","nullable":true},"pausedAt":{"type":"string","format":"date-time","nullable":true},"pausedBy":{"type":"string","format":"uuid","nullable":true},"pauseReason":{"type":"string","nullable":true},"monthlyBudgetUsd":{"type":"number","nullable":true},"budgetAction":{"type":"string","enum":["alert","pause_agent"]},"currentMonthCostUsd":{"type":"number"},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object","additionalProperties":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"type":"string","format":"uuid","nullable":true}}},"RegisterAgentInput":{"type":"object","required":["agentId","name","type","platform","environment"],"properties":{"agentId":{"type":"string","minLength":1,"maxLength":255,"description":"External agent identifier"},"name":{"type":"string","minLength":1,"maxLength":255},"description":{"type":"string"},"type":{"type":"string","minLength":1,"maxLength":50},"platform":{"type":"string","enum":["openai","azure_openai","anthropic","langchain","crewai","custom"]},"frameworkVersion":{"type":"string","maxLength":50},"modelProvider":{"type":"string","maxLength":100},"environment":{"type":"string","enum":["development","staging","production"]},"deploymentUrl":{"type":"string","format":"uri"},"tags":{"type":"array","items":{"type":"string"},"default":[]},"metadata":{"type":"object","additionalProperties":true,"default":{}}}},"UpdateAgentInput":{"type":"object","description":"All fields from RegisterAgentInput, all optional","properties":{"name":{"type":"string"},"description":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object","additionalProperties":true},"ownerUserId":{"type":"string","format":"uuid"},"teamId":{"type":"string","format":"uuid"},"deploymentUrl":{"type":"string","format":"uri"}}},"GenerateApiKeyInput":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":255},"description":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"},"ipAllowlist":{"type":"array","items":{"type":"string","format":"ipv4"}}}},"AgentStatsPeriod":{"type":"object","properties":{"total":{"type":"integer"},"success":{"type":"integer"},"error":{"type":"integer"},"successRate":{"type":"number","format":"float"},"avgDurationMs":{"type":"number"},"p95DurationMs":{"type":"number"},"totalCostUsd":{"type":"number"}}},"AgentBudget":{"type":"object","properties":{"agentId":{"type":"string","format":"uuid"},"agentName":{"type":"string"},"monthlyBudgetUsd":{"type":"number","nullable":true},"currentMonthSpend":{"type":"number"},"percentUsed":{"type":"number"},"budgetAction":{"type":"string","enum":["alert","pause_agent"]},"projectedMonthSpend":{"type":"number"},"daysRemainingInPeriod":{"type":"integer"},"willExceedBudget":{"type":"boolean"},"warningThresholdPct":{"type":"number"}}}}},"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"paths":{"/webhooks":{"get":{"tags":["Webhooks"],"summary":"List webhooks","description":"Returns paginated webhooks for the organization. Requires ADMIN role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Maximum number of webhooks to return"},{"in":"query","name":"offset","schema":{"type":"integer","minimum":0,"default":0},"description":"Number of webhooks to skip"}],"responses":{"200":{"description":"Paginated list of webhooks","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}},"meta":{"type":"object","properties":{"total":{"type":"integer"}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — ADMIN role required"}}},"post":{"tags":["Webhooks"],"summary":"Create a webhook","description":"Registers a new webhook endpoint. A signing secret is generated and returned in the response — store it securely. Requires ADMIN role.\n","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebhookInput"}}}},"responses":{"201":{"description":"Webhook created (secret shown once)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"$ref":"#/components/schemas/Webhook"},{"type":"object","properties":{"secret":{"type":"string","description":"Signing secret — shown only once","example":"whsec_abc123..."}}}]}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — ADMIN role required"},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/{id}":{"get":{"tags":["Webhooks"],"summary":"Get webhook by ID","description":"Returns a single webhook. Requires ADMIN role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"Webhook UUID"}],"responses":{"200":{"description":"Webhook details","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Webhook"}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — ADMIN role required"},"404":{"description":"Webhook not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Webhooks"],"summary":"Update a webhook","description":"Partially updates a webhook. Requires ADMIN role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWebhookInput"}}}},"responses":{"200":{"description":"Webhook updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Webhook"}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — ADMIN role required"},"404":{"description":"Webhook not found"},"422":{"description":"Validation error"}}},"delete":{"tags":["Webhooks"],"summary":"Delete a webhook","description":"Permanently deletes a webhook. Requires ADMIN role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Webhook deleted"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — ADMIN role required"},"404":{"description":"Webhook not found"}}}},"/webhooks/{id}/test":{"post":{"tags":["Webhooks"],"summary":"Send a test ping","description":"Sends a test payload to the webhook URL and returns the response status. Requires ADMIN role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"Webhook UUID"}],"responses":{"200":{"description":"Test result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"success":{"type":"boolean"},"statusCode":{"type":"integer","description":"HTTP status code from the target URL"},"statusText":{"type":"string"},"error":{"type":"string","description":"Present on failure (e.g. timeout)"}}}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — ADMIN role required"},"404":{"description":"Webhook not found"}}}},"/webhooks/{id}/deliveries":{"get":{"tags":["Webhooks"],"summary":"Get webhook delivery logs","description":"Returns recent delivery attempts for a webhook. Requires ADMIN role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"Webhook UUID"},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Maximum delivery entries to return"}],"responses":{"200":{"description":"Delivery logs","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — ADMIN role required"},"404":{"description":"Webhook not found"}}}},"/webhooks/{id}/rotate-secret":{"post":{"tags":["Webhooks"],"summary":"Rotate webhook signing secret","description":"Generates a new signing secret for the webhook. The new secret is returned **only once**. Requires ADMIN role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"Webhook UUID"}],"responses":{"200":{"description":"New signing secret","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"secret":{"type":"string","description":"New signing secret — shown only once","example":"whsec_newSecret123..."}}}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — ADMIN role required"},"404":{"description":"Webhook not found"}}}},"/traces":{"get":{"tags":["Traces"],"summary":"List traces","description":"Returns paginated list of execution traces for the organization with optional filters.","parameters":[{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"in":"query","name":"offset","schema":{"type":"integer","minimum":0,"default":0}},{"in":"query","name":"agentId","schema":{"type":"string","format":"uuid"},"description":"Filter by agent UUID"},{"in":"query","name":"status","schema":{"type":"string","enum":["success","error","timeout","policy_blocked","limit_exceeded"]}},{"in":"query","name":"environment","schema":{"type":"string","enum":["development","staging","production"]}},{"in":"query","name":"sessionId","schema":{"type":"string"}},{"in":"query","name":"startTime","schema":{"type":"string","format":"date-time"},"description":"Filter traces after this time"},{"in":"query","name":"endTime","schema":{"type":"string","format":"date-time"},"description":"Filter traces before this time"},{"in":"query","name":"search","schema":{"type":"string"},"description":"Full-text search across trace fields"}],"responses":{"200":{"description":"Paginated list of traces","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Trace"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}},"401":{"description":"Unauthorized"},"429":{"description":"Rate limit exceeded"}}}},"/traces/ingest":{"post":{"tags":["Traces"],"summary":"Ingest traces (batch)","description":"SDK-facing endpoint for batch trace ingestion (up to 100 traces per request). Higher rate limit (1000 req/min) than control plane endpoints.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestTracesInput"}}}},"responses":{"202":{"description":"Traces accepted for processing","content":{"application/json":{"schema":{"type":"object","properties":{"accepted":{"type":"integer","description":"Number of traces accepted"},"failed":{"type":"integer","description":"Number of traces that failed"},"traceIds":{"type":"array","items":{"type":"string"},"description":"IDs of successfully ingested traces"},"errors":{"type":"array","items":{"type":"object","properties":{"traceId":{"type":"string"},"error":{"type":"string"}}},"description":"Details of failed traces (only present when failures occur)"}}}}}},"401":{"description":"Unauthorized"},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (1000/min)"}}}},"/traces/stats":{"get":{"tags":["Traces"],"summary":"Get trace statistics","description":"Returns aggregate trace statistics for the organization over a configurable time window.","parameters":[{"in":"query","name":"hours","schema":{"type":"integer","default":24},"description":"Number of hours to look back"}],"responses":{"200":{"description":"Trace statistics","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","description":"Aggregate stats (total traces, success rate, avg duration, etc.)"}}}}}},"401":{"description":"Unauthorized"}}}},"/traces/export":{"get":{"tags":["Traces"],"summary":"Export traces","description":"Export traces as CSV or JSON with optional filters.","parameters":[{"in":"query","name":"format","schema":{"type":"string","enum":["csv","json"],"default":"json"}},{"in":"query","name":"startDate","schema":{"type":"string","format":"date"}},{"in":"query","name":"endDate","schema":{"type":"string","format":"date"}},{"in":"query","name":"agentId","schema":{"type":"string","format":"uuid"}},{"in":"query","name":"status","schema":{"type":"string","enum":["success","error","timeout","policy_blocked","limit_exceeded"]}},{"in":"query","name":"environment","schema":{"type":"string","enum":["development","staging","production"]}}],"responses":{"200":{"description":"Exported trace data","content":{"application/json":{"schema":{"type":"object"}},"text/csv":{"schema":{"type":"string"}}}},"401":{"description":"Unauthorized"}}}},"/traces/{id}":{"get":{"tags":["Traces"],"summary":"Get trace by ID","description":"Returns a single trace with related traces.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"Trace UUID"}],"responses":{"200":{"description":"Trace details with related traces","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"$ref":"#/components/schemas/Trace"},{"type":"object","properties":{"relatedTraces":{"type":"array","items":{"$ref":"#/components/schemas/Trace"}}}}]}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Trace not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/traces/{id}/tree":{"get":{"tags":["Traces"],"summary":"Get trace tree","description":"Returns the recursive trace hierarchy (root + child spans) as a tree structure.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Trace tree","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"root":{"$ref":"#/components/schemas/Trace"},"children":{"type":"array","items":{"$ref":"#/components/schemas/Trace"}}}}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Trace not found"}}}},"/traces/{id}/children":{"get":{"tags":["Traces"],"summary":"Get child spans","description":"Returns child spans of a specific trace.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Child spans","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Trace"}}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Trace not found"}}}},"/traces/{id}/flag":{"patch":{"tags":["Traces"],"summary":"Flag trace for review","description":"Flags or unflags a trace for human review.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"flagged":{"type":"boolean","default":true},"reason":{"type":"string","description":"Reason for flagging"}}}}}},"responses":{"200":{"description":"Trace flag updated","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"}}}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Trace not found"}}}},"/traces/{id}/incidents":{"post":{"tags":["Traces"],"summary":"Create incident from trace","description":"Creates a new incident linked to this trace.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","description":"Optional title (auto-generated if omitted)"},"description":{"type":"string"},"severity":{"type":"string","enum":["critical","high","medium","low"]}}}}}},"responses":{"201":{"description":"Incident created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Incident"}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Trace not found"}}}},"/traces/similar/{id}":{"get":{"tags":["Traces"],"summary":"Find similar traces","description":"Returns traces similar to the given trace, scored by shared agent, model, status, environment, and span type.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"Reference trace UUID"},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":50,"default":10},"description":"Maximum number of similar traces to return"}],"responses":{"200":{"description":"Similar traces found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Trace"}},"meta":{"type":"object","properties":{"referenceTraceId":{"type":"string"},"total":{"type":"integer"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/teams":{"get":{"tags":["Teams"],"summary":"List teams","description":"Returns paginated teams for the organization. Supports text search on name and description.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"query","name":"search","schema":{"type":"string"},"description":"Search teams by name or description"},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Maximum number of teams to return"},{"in":"query","name":"offset","schema":{"type":"integer","minimum":0,"default":0},"description":"Number of teams to skip"}],"responses":{"200":{"description":"List of teams","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Team"}},"meta":{"type":"object","properties":{"total":{"type":"integer"}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Teams"],"summary":"Create a team","description":"Creates a new team in the organization. Requires ADMIN role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTeamInput"}}}},"responses":{"201":{"description":"Team created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Team"}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — ADMIN role required"},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/teams/{id}":{"get":{"tags":["Teams"],"summary":"Get team by ID","description":"Returns a single team with its members.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"Team UUID"}],"responses":{"200":{"description":"Team details with members","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"$ref":"#/components/schemas/Team"},{"type":"object","properties":{"members":{"type":"array","items":{"$ref":"#/components/schemas/TeamMember"}}}}]}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Team not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Teams"],"summary":"Update a team","description":"Updates team name and/or description. Requires ADMIN role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTeamInput"}}}},"responses":{"200":{"description":"Team updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Team"}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — ADMIN role required"},"404":{"description":"Team not found"},"422":{"description":"Validation error"}}},"delete":{"tags":["Teams"],"summary":"Delete a team","description":"Soft-deletes a team. Requires ADMIN role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Team deleted","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Team deleted successfully"}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — ADMIN role required"},"404":{"description":"Team not found"}}}},"/teams/{id}/members":{"get":{"tags":["Teams"],"summary":"Get team members","description":"Returns members of a specific team.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"Team UUID"}],"responses":{"200":{"description":"List of team members","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TeamMember"}},"meta":{"type":"object","properties":{"total":{"type":"integer"}}}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Team not found"}}},"post":{"tags":["Teams"],"summary":"Add a member to team","description":"Adds a user to the team. Requires ADMIN role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"Team UUID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["userId"],"properties":{"userId":{"type":"string","format":"uuid","description":"User UUID to add to the team"}}}}}},"responses":{"201":{"description":"Member added","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Member added successfully"}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — ADMIN role required"},"404":{"description":"Team or user not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error — userId is required"}}}},"/teams/{id}/members/{userId}":{"delete":{"tags":["Teams"],"summary":"Remove a member from team","description":"Removes a user from the team. Requires ADMIN role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"Team UUID"},{"in":"path","name":"userId","required":true,"schema":{"type":"string","format":"uuid"},"description":"User UUID to remove"}],"responses":{"200":{"description":"Member removed","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Member removed successfully"}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — ADMIN role required"},"404":{"description":"Team not found"}}}},"/saved-filters":{"get":{"tags":["Saved Filters"],"summary":"List saved filters","description":"Returns saved filters for the authenticated user. Optionally filter by resource type.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"query","name":"resource_type","schema":{"type":"string","enum":["agents","incidents","traces","policies","executions"]},"description":"Filter by resource type"}],"responses":{"200":{"description":"List of saved filters","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SavedFilter"}},"meta":{"type":"object","properties":{"total":{"type":"integer"}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Saved Filters"],"summary":"Create a saved filter","description":"Creates a new saved filter for the authenticated user.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSavedFilterInput"}}}},"responses":{"201":{"description":"Saved filter created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SavedFilter"}}}}}},"401":{"description":"Unauthorized"},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/saved-filters/{id}":{"get":{"tags":["Saved Filters"],"summary":"Get saved filter by ID","description":"Returns a single saved filter.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"Saved filter UUID"}],"responses":{"200":{"description":"Saved filter details","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SavedFilter"}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Saved filter not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"tags":["Saved Filters"],"summary":"Update a saved filter","description":"Updates an existing saved filter.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSavedFilterInput"}}}},"responses":{"200":{"description":"Saved filter updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SavedFilter"}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Saved filter not found"},"422":{"description":"Validation error"}}},"delete":{"tags":["Saved Filters"],"summary":"Delete a saved filter","description":"Permanently deletes a saved filter.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Saved filter deleted"},"401":{"description":"Unauthorized"},"404":{"description":"Saved filter not found"}}}},"/prompt-versions":{"get":{"tags":["Prompt Versions"],"summary":"List prompt versions","description":"Returns paginated prompt versions. Can filter by agent and approval status.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"query","name":"agentId","schema":{"type":"string","format":"uuid"},"description":"Filter by agent UUID"},{"in":"query","name":"status","schema":{"type":"string","enum":["pending","approved","rejected"]},"description":"Filter by approval status"},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Maximum results to return"},{"in":"query","name":"offset","schema":{"type":"integer","minimum":0,"default":0},"description":"Number of results to skip"}],"responses":{"200":{"description":"Paginated list of prompt versions","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PromptVersion"}},"meta":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Prompt Versions"],"summary":"Create a new prompt version","description":"Creates a new prompt version for an agent. Requires DEVELOPER role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePromptVersionInput"}}}},"responses":{"201":{"description":"Prompt version created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PromptVersion"}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — DEVELOPER role required"},"404":{"description":"Agent not found"},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/prompt-versions/pending":{"get":{"tags":["Prompt Versions"],"summary":"List pending approvals","description":"Returns prompt versions awaiting approval. Requires ADMIN role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"responses":{"200":{"description":"List of pending prompt versions","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PromptVersion"}}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — ADMIN role required"}}}},"/prompt-versions/{id}":{"get":{"tags":["Prompt Versions"],"summary":"Get prompt version by ID","description":"Returns a single prompt version with full details.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"Prompt version UUID"}],"responses":{"200":{"description":"Prompt version details","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PromptVersion"}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Prompt version not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/prompt-versions/{id}/approve":{"post":{"tags":["Prompt Versions"],"summary":"Approve or reject a prompt version","description":"Approves or rejects a pending prompt version. Requires ADMIN role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"Prompt version UUID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["action"],"properties":{"action":{"type":"string","enum":["approve","reject"]},"rejectionReason":{"type":"string","description":"Required when action is 'reject'"}}}}}},"responses":{"200":{"description":"Prompt version approved or rejected","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PromptVersion"}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — ADMIN role required"},"404":{"description":"Prompt version not found"},"422":{"description":"Validation error"}}}},"/prompt-versions/{id}/deploy":{"post":{"tags":["Prompt Versions"],"summary":"Deploy a prompt version","description":"Deploys an approved prompt version, making it the active version for the agent. Requires ADMIN role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"environment":{"type":"string","enum":["development","staging","production"]}}}}}},"responses":{"200":{"description":"Prompt version deployed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PromptVersion"}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — ADMIN role required"},"404":{"description":"Prompt version not found"}}}},"/prompt-versions/{id}/undeploy":{"post":{"tags":["Prompt Versions"],"summary":"Undeploy a prompt version","description":"Undeploys a currently active prompt version. Requires ADMIN role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Prompt version undeployed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PromptVersion"}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — ADMIN role required"},"404":{"description":"Prompt version not found"}}}},"/prompt-versions/{id}/rollback":{"post":{"tags":["Prompt Versions"],"summary":"Rollback to a previous prompt version","description":"Rolls back to this version, making it the active deployed version. Requires ADMIN role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string","minLength":1,"description":"Reason for rollback"}}}}}},"responses":{"200":{"description":"Prompt version rolled back","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PromptVersion"}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — ADMIN role required"},"404":{"description":"Prompt version not found"},"422":{"description":"Validation error — reason is required"}}}},"/policies":{"get":{"tags":["Policies"],"summary":"List all policies","description":"Returns all governance policies for the organization. Requires DEVELOPER role or higher.","responses":{"200":{"description":"List of policies","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Policy"}},"meta":{"type":"object","properties":{"total":{"type":"integer"}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — DEVELOPER role required"},"429":{"description":"Rate limit exceeded"}}},"post":{"tags":["Policies"],"summary":"Create a policy","description":"Creates a new governance policy. Requires ADMIN role.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePolicyInput"}}}},"responses":{"201":{"description":"Policy created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Policy"}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — ADMIN role required"},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/policies/enforce":{"post":{"tags":["Policies"],"summary":"Enforce policies against a pending agent action","description":"The synchronous enforcement gate. Call this BEFORE the agent acts — tracing alone never blocks anything.\n\nThe outcome is carried by the HTTP status, not only by the body: `200` allow (possibly with non-blocking warnings), `202` an approval is required and has been created, `403` blocked by a policy. Treat any non-200 as \"do not proceed\".\n\nUnknown fields are rejected with `400` rather than ignored. On an enforcement endpoint an unrecognised key must never read as \"no constraint\" — sending `toolName` instead of `tools` fails loudly instead of silently disabling a guardrail.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["agentId","input"],"properties":{"agentId":{"type":"string","minLength":1,"maxLength":255,"description":"External agent identifier."},"input":{"type":"string","minLength":1,"maxLength":10000,"description":"The prompt or action about to be executed."},"environment":{"type":"string","enum":["development","staging","production"],"default":"production"},"conversationHistory":{"type":"array","maxItems":50,"description":"Recent turns. When present, injection scanning runs over the combined recent user turns plus the current input, so an attack split across turns is caught rather than passing because no single turn trips a pattern.\n","items":{"type":"object","required":["role","content"],"properties":{"role":{"type":"string","enum":["user","assistant","system"]},"content":{"type":"string","maxLength":10000}}}},"tools":{"type":"array","maxItems":100,"items":{"type":"string"},"description":"Tools the agent intends to call."},"toolOutputs":{"type":"array","maxItems":100,"description":"Tool results to scan before feeding them back to the model.","items":{"type":"object","required":["name","output"],"properties":{"name":{"type":"string","minLength":1,"maxLength":255},"input":{},"output":{}}}},"toolDescriptors":{"type":"array","maxItems":100,"description":"MCP tool descriptors presented at enforcement time, diffed against the pinned tool_integrity baseline.\n","items":{"type":"object","required":["server","tool","descriptorHash"],"properties":{"server":{"type":"string","minLength":1,"maxLength":255},"tool":{"type":"string","minLength":1,"maxLength":255},"descriptorHash":{"type":"string","minLength":1,"maxLength":128},"description":{"type":"string","maxLength":10000}}}},"estimatedCost":{"type":"number","minimum":0},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form context, serialized size capped at 100KB."}}}}}},"responses":{"200":{"description":"Allowed. `warnings` carries warn/monitor-mode matches, which do not block.","content":{"application/json":{"schema":{"type":"object","properties":{"allowed":{"type":"boolean","enum":[true]},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/PolicyViolation"}}}}}}},"202":{"description":"An approval is required and an approval request has been created. The action must NOT proceed until the approval is granted; poll `pollUrl` for the decision.\n","content":{"application/json":{"schema":{"type":"object","properties":{"allowed":{"type":"boolean","enum":[false]},"requiresApproval":{"type":"boolean","enum":[true]},"approvalRequestId":{"type":"string","format":"uuid"},"pollUrl":{"type":"string","description":"Poll this path for the approval decision.","example":"/api/v1/approvals/3fa85f64-5717-4562-b3fc-2c963f66afa6"},"violations":{"type":"array","items":{"$ref":"#/components/schemas/PolicyViolation"}},"semanticCheck":{"type":"object"}}}}}},"400":{"description":"Invalid request — includes an unrecognised field being rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized"},"402":{"description":"Plan trace quota exceeded"},"403":{"description":"Blocked by a policy in block mode.","content":{"application/json":{"schema":{"type":"object","properties":{"allowed":{"type":"boolean","enum":[false]},"violations":{"type":"array","items":{"$ref":"#/components/schemas/PolicyViolation"}},"semanticCheck":{"type":"object"}}}}}},"413":{"description":"Request body too large"},"429":{"description":"Rate limit exceeded"}}}},"/policies/violations":{"get":{"tags":["Policies"],"summary":"Get policy violations","description":"Returns recent policy violations for the organization. Requires DEVELOPER role.","responses":{"200":{"description":"List of policy violations","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"policyId":{"type":"string","format":"uuid"},"policyName":{"type":"string"},"agentId":{"type":"string","format":"uuid"},"traceId":{"type":"string"},"violationType":{"type":"string"},"severity":{"type":"string"},"details":{"type":"object"},"createdAt":{"type":"string","format":"date-time"}}}}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — DEVELOPER role required"}}}},"/policies/{id}":{"get":{"tags":["Policies"],"summary":"Get policy by ID","description":"Returns a single policy by UUID. Requires DEVELOPER role.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"Policy UUID"}],"responses":{"200":{"description":"Policy details","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Policy"}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Policy not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Policies"],"summary":"Update a policy","description":"Update policy fields. Requires ADMIN role.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePolicyInput"}}}},"responses":{"200":{"description":"Policy updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Policy"}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — ADMIN role required"},"404":{"description":"Policy not found"},"422":{"description":"Validation error"}}},"delete":{"tags":["Policies"],"summary":"Delete a policy","description":"Permanently deletes a policy. Requires ADMIN role.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Policy deleted","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Policy deleted successfully"}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — ADMIN role required"},"404":{"description":"Policy not found"}}}},"/organizations/settings/security":{"get":{"tags":["Organizations"],"summary":"Get security settings","description":"Returns the organization's security settings including IP allowlist, MFA enforcement, and allowed environments. Requires ADMIN role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Security settings","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SecuritySettings"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — ADMIN role required"}}},"patch":{"tags":["Organizations"],"summary":"Update security settings","description":"Partially updates the organization's security settings. All fields are optional. Requires ADMIN role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSecuritySettingsInput"}}}},"responses":{"200":{"description":"Updated security settings","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SecuritySettings"}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — ADMIN role required"},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/organizations/settings/org":{"get":{"tags":["Organizations"],"summary":"Get organization settings","description":"Returns the organization's plan, compliance frameworks, and data residency settings. Requires ADMIN role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Organization settings","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OrgSettings"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — ADMIN role required"}}},"patch":{"tags":["Organizations"],"summary":"Update organization settings","description":"Partially updates organization settings (plan, compliance, data residency). Requires ADMIN role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateOrgSettingsInput"}}}},"responses":{"200":{"description":"Updated organization settings","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OrgSettings"}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — ADMIN role required"},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/orchestrations":{"get":{"tags":["Orchestrations"],"summary":"List orchestrations","description":"Returns paginated list of multi-agent orchestrations. Supports filtering by enabled status and text search. Requires VIEWER role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Maximum number of orchestrations to return"},{"in":"query","name":"offset","schema":{"type":"integer","minimum":0,"default":0},"description":"Number of orchestrations to skip"},{"in":"query","name":"enabled","schema":{"type":"string","enum":["true","false"]},"description":"Filter by enabled status"},{"in":"query","name":"search","schema":{"type":"string","maxLength":255},"description":"Search orchestrations by name"}],"responses":{"200":{"description":"Paginated list of orchestrations","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Orchestration"}},"meta":{"type":"object","properties":{"total":{"type":"integer"}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Orchestrations"],"summary":"Create an orchestration","description":"Creates a new multi-agent orchestration with a DAG graph. The graph is validated for cycles, missing agents, and structural integrity before creation. Requires ADMIN role.\n","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrchestrationInput"}}}},"responses":{"201":{"description":"Orchestration created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Orchestration"}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — ADMIN role required"},"422":{"description":"Validation error (including invalid graph structure)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/orchestrations/validate":{"post":{"tags":["Orchestrations"],"summary":"Validate orchestration graph","description":"Validates an orchestration graph structure without persisting it. Checks for cycles, missing agents, and structural issues. Requires DEVELOPER role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrchestrationInput"}}}},"responses":{"200":{"description":"Validation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"valid":{"type":"boolean"},"errors":{"type":"array","items":{"type":"string"}}}}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — DEVELOPER role required"},"422":{"description":"Validation error"}}}},"/orchestrations/{id}":{"get":{"tags":["Orchestrations"],"summary":"Get orchestration by ID","description":"Returns a single orchestration with full graph details. Requires VIEWER role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"Orchestration UUID"}],"responses":{"200":{"description":"Orchestration details","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Orchestration"}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Orchestration not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"tags":["Orchestrations"],"summary":"Update an orchestration","description":"Fully or partially updates an orchestration. If the graph is updated, it will be re-validated. Requires ADMIN role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateOrchestrationInput"}}}},"responses":{"200":{"description":"Orchestration updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Orchestration"}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — ADMIN role required"},"404":{"description":"Orchestration not found"},"422":{"description":"Validation error"}}},"delete":{"tags":["Orchestrations"],"summary":"Delete an orchestration","description":"Permanently deletes an orchestration. Requires ADMIN role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Orchestration deleted"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — ADMIN role required"},"404":{"description":"Orchestration not found"}}}},"/orchestrations/{id}/stats":{"get":{"tags":["Orchestrations"],"summary":"Get orchestration execution stats","description":"Returns execution statistics for a specific orchestration. Requires VIEWER role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"Orchestration UUID"}],"responses":{"200":{"description":"Orchestration execution statistics","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"orchestrationId":{"type":"string","format":"uuid"},"totalExecutions":{"type":"integer"},"successRate":{"type":"number"},"avgDurationMs":{"type":"number"},"totalCostUsd":{"type":"number"}}}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Orchestration not found"}}}},"/notification-channels":{"get":{"tags":["Notification Channels"],"summary":"List notification channels","description":"Returns all notification channels for the organization. Requires VIEWER role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"responses":{"200":{"description":"List of notification channels","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/NotificationChannel"}},"meta":{"type":"object","properties":{"total":{"type":"integer"}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Notification Channels"],"summary":"Create a notification channel","description":"Creates a new notification channel. Requires ADMIN role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","channel_type"],"properties":{"name":{"type":"string","maxLength":255},"channel_type":{"type":"string","enum":["email","slack","pagerduty","webhook"]},"configuration":{"type":"object","additionalProperties":true},"is_active":{"type":"boolean","default":true}}}}}},"responses":{"201":{"description":"Notification channel created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/NotificationChannel"}}}}}},"400":{"description":"Validation error"},"403":{"description":"Forbidden — ADMIN role required"}}}},"/notification-channels/{id}":{"get":{"tags":["Notification Channels"],"summary":"Get a notification channel","description":"Returns a single notification channel by ID. Requires VIEWER role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"Notification channel ID"}],"responses":{"200":{"description":"Notification channel details","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/NotificationChannel"}}}}}},"404":{"description":"Not found"}}},"put":{"tags":["Notification Channels"],"summary":"Update a notification channel","description":"Updates an existing notification channel. Requires ADMIN role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"Notification channel ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":255},"configuration":{"type":"object","additionalProperties":true},"is_active":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Notification channel updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/NotificationChannel"}}}}}},"400":{"description":"Validation error"},"403":{"description":"Forbidden — ADMIN role required"},"404":{"description":"Not found"}}},"delete":{"tags":["Notification Channels"],"summary":"Delete a notification channel","description":"Permanently deletes a notification channel. Requires ADMIN role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"Notification channel ID"}],"responses":{"204":{"description":"Notification channel deleted"},"403":{"description":"Forbidden — ADMIN role required"},"404":{"description":"Not found"}}}},"/incidents":{"get":{"tags":["Incidents"],"summary":"List incidents","description":"Returns paginated list of incidents for the organization.","parameters":[{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"in":"query","name":"offset","schema":{"type":"integer","minimum":0,"default":0}},{"in":"query","name":"search","schema":{"type":"string"},"description":"Search incidents by title or description"}],"responses":{"200":{"description":"Paginated list of incidents","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Incident"}},"meta":{"type":"object","properties":{"total":{"type":"integer"}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded"}}},"post":{"tags":["Incidents"],"summary":"Create an incident","description":"Creates a new incident. Requires DEVELOPER role or higher.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateIncidentInput"}}}},"responses":{"201":{"description":"Incident created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Incident"}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — DEVELOPER role required"},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/incidents/export":{"get":{"tags":["Incidents"],"summary":"Export incidents","description":"Export incidents as CSV or JSON with optional filters.","parameters":[{"in":"query","name":"format","schema":{"type":"string","enum":["csv","json"],"default":"json"}},{"in":"query","name":"status","schema":{"type":"string","enum":["open","investigating","resolved","closed","false_positive"]}},{"in":"query","name":"severity","schema":{"type":"string","enum":["critical","high","medium","low"]}},{"in":"query","name":"agentId","schema":{"type":"string","format":"uuid"}},{"in":"query","name":"startDate","schema":{"type":"string","format":"date"}},{"in":"query","name":"endDate","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Exported incident data","content":{"application/json":{"schema":{"type":"object"}},"text/csv":{"schema":{"type":"string"}}}},"401":{"description":"Unauthorized"}}}},"/incidents/{id}":{"get":{"tags":["Incidents"],"summary":"Get incident by ID","description":"Returns detailed incident information including agent and trace references.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"Incident UUID"}],"responses":{"200":{"description":"Incident details","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Incident"}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Incident not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Incidents"],"summary":"Update an incident","description":"Update incident fields (status, severity, assignment, etc.). Requires DEVELOPER role. Setting status to resolved/closed/false_positive records a resolution.\n","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateIncidentInput"}}}},"responses":{"200":{"description":"Incident updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"success":{"type":"boolean"}}}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — DEVELOPER role required"},"404":{"description":"Incident not found"}}}},"/incidents/{id}/timeline":{"get":{"tags":["Incidents"],"summary":"Get incident timeline","description":"Returns the timeline of events for an incident.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Incident timeline events","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"incidentId":{"type":"string","format":"uuid"},"event":{"type":"string"},"details":{"type":"object"},"userId":{"type":"string","format":"uuid","nullable":true},"createdAt":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"total":{"type":"integer"}}}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Incident not found"}}}},"/health":{"get":{"tags":["System"],"summary":"Health check","description":"Returns service health status including database and Redis connectivity. Used by load balancers and monitoring systems. No authentication required.\n","security":[],"responses":{"200":{"description":"Service is healthy or degraded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}},"503":{"description":"Service is unhealthy (both DB and Redis down)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/metrics":{"get":{"tags":["System"],"summary":"Prometheus metrics","description":"Returns metrics in Prometheus text exposition format. Intended for scraping by monitoring infrastructure. No authentication required.\n","security":[],"responses":{"200":{"description":"Prometheus metrics","content":{"text/plain":{"schema":{"type":"string","example":"# HELP http_request_duration_seconds HTTP request duration\n# TYPE http_request_duration_seconds histogram\nhttp_request_duration_seconds_bucket{le=\"0.1\"} 245\n"}}}}}}},"/audit-logs":{"get":{"tags":["Audit Logs"],"summary":"List audit logs","description":"Returns paginated audit log entries for the organization with rich filtering. Supports filtering by action, resource type, user, date range, and text search. Requires ADMIN role.\n","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"description":"Maximum number of entries to return"},{"in":"query","name":"offset","schema":{"type":"integer","minimum":0,"default":0},"description":"Number of entries to skip"},{"in":"query","name":"action","schema":{"type":"string"},"description":"Filter by action type (e.g. agent.created, policy.updated)"},{"in":"query","name":"resourceType","schema":{"type":"string"},"description":"Filter by resource type (e.g. agent, policy, team)"},{"in":"query","name":"resourceId","schema":{"type":"string"},"description":"Filter by specific resource ID"},{"in":"query","name":"userId","schema":{"type":"string"},"description":"Filter by user who performed the action"},{"in":"query","name":"result","schema":{"type":"string","enum":["success","failure"]},"description":"Filter by result"},{"in":"query","name":"startDate","schema":{"type":"string","format":"date-time"},"description":"Filter entries from this date"},{"in":"query","name":"endDate","schema":{"type":"string","format":"date-time"},"description":"Filter entries until this date"},{"in":"query","name":"search","schema":{"type":"string"},"description":"Full-text search across action, metadata, and user name"}],"responses":{"200":{"description":"Paginated audit log entries","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AuditLogEntry"}},"meta":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — ADMIN role required"}}}},"/audit-logs/export":{"get":{"tags":["Audit Logs"],"summary":"Export audit logs","description":"Exports audit logs as CSV or JSON. Supports date range filtering. Requires ADMIN role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"query","name":"format","schema":{"type":"string","enum":["csv","json"],"default":"json"},"description":"Export format"},{"in":"query","name":"startDate","schema":{"type":"string","format":"date-time"},"description":"Export entries from this date"},{"in":"query","name":"endDate","schema":{"type":"string","format":"date-time"},"description":"Export entries until this date"}],"responses":{"200":{"description":"Exported audit log data","content":{"application/json":{"schema":{"type":"object"}},"text/csv":{"schema":{"type":"string"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — ADMIN role required"}}}},"/audit-logs/{id}":{"get":{"tags":["Audit Logs"],"summary":"Get audit log entry by ID","description":"Returns a single audit log entry with full details. Requires ADMIN role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"Audit log entry UUID"}],"responses":{"200":{"description":"Audit log entry details","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AuditLogEntry"}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — ADMIN role required"},"404":{"description":"Audit log entry not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/audit-logs/{id}/verify":{"get":{"tags":["Audit Logs"],"summary":"Verify audit log checksum integrity","description":"Recomputes the SHA-256 checksum for an audit log entry and compares it to the stored value. Useful for tamper detection. Requires ADMIN role.\n","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"Audit log entry UUID"}],"responses":{"200":{"description":"Checksum verification result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"valid":{"type":"boolean","description":"Whether the stored checksum matches the computed one"},"storedChecksum":{"type":"string"},"computedChecksum":{"type":"string"}}}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — ADMIN role required"},"404":{"description":"Audit log entry not found"}}}},"/api-keys":{"get":{"tags":["API Keys"],"summary":"List API keys","description":"Returns all API keys for the organization. The key hash is never returned. Requires ADMIN role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"responses":{"200":{"description":"List of API keys","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"}},"meta":{"type":"object","properties":{"total":{"type":"integer"}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — ADMIN role required"}}},"post":{"tags":["API Keys"],"summary":"Create a new API key","description":"Generates a new API key for the organization. The plain key is returned in the response **only once** — store it securely. Requires ADMIN role.\n","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApiKeyInput"}}}},"responses":{"201":{"description":"API key created (plain key shown once)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"key":{"type":"string","description":"Plain API key — shown only once","example":"exe_prod_abc123..."},"keyPrefix":{"type":"string","example":"exe_prod_abc123"},"environment":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"expiresAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}}}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — ADMIN role required"},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api-keys/{id}/revoke":{"patch":{"tags":["API Keys"],"summary":"Revoke an API key","description":"Soft-deletes an API key by setting it inactive. Requires ADMIN role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"API key UUID"}],"responses":{"200":{"description":"API key revoked","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"revoked":{"type":"boolean","example":true}}}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — ADMIN role required"},"404":{"description":"API key not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api-keys/{id}/rotate":{"post":{"tags":["API Keys"],"summary":"Rotate an API key","description":"Revokes the current key and generates a new one with the same settings. The new plain key is returned **only once**. Requires ADMIN role.\n","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"API key UUID to rotate"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"expiresAt":{"type":"string","format":"date-time","description":"Optional override for the new key's expiry"}}}}}},"responses":{"201":{"description":"New API key generated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"key":{"type":"string","description":"New plain API key — shown only once"},"keyPrefix":{"type":"string"},"environment":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"expiresAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}}}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — ADMIN role required"},"404":{"description":"API key not found"}}}},"/api-keys/{id}":{"delete":{"tags":["API Keys"],"summary":"Delete an API key","description":"Permanently deletes an API key. Requires ADMIN role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"API key UUID"}],"responses":{"204":{"description":"API key deleted"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — ADMIN role required"},"404":{"description":"API key not found"}}}},"/anomaly/configs":{"get":{"tags":["Anomaly Detection"],"summary":"List anomaly detection configs","description":"Returns all anomaly detection configurations for the organization. Optionally filter by agent. Requires VIEWER role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"query","name":"agentId","schema":{"type":"string","format":"uuid"},"description":"Filter configs for a specific agent"}],"responses":{"200":{"description":"List of anomaly configs","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AnomalyConfig"}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"tags":["Anomaly Detection"],"summary":"Create or update anomaly config","description":"Upserts an anomaly detection configuration. Requires ADMIN role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpsertAnomalyConfigInput"}}}},"responses":{"201":{"description":"Config created or updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AnomalyConfig"}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — ADMIN role required"},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/anomaly/configs/{id}":{"get":{"tags":["Anomaly Detection"],"summary":"Get anomaly config by ID","description":"Returns a single anomaly detection configuration. Requires VIEWER role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"Anomaly config UUID"}],"responses":{"200":{"description":"Anomaly config details","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AnomalyConfig"}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Config not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Anomaly Detection"],"summary":"Delete anomaly config","description":"Deletes an anomaly detection configuration. Requires ADMIN role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Config deleted"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — ADMIN role required"},"404":{"description":"Config not found"}}}},"/anomaly/events":{"get":{"tags":["Anomaly Detection"],"summary":"List anomaly events","description":"Returns detected anomaly events for the organization. Supports filtering by agent and severity. Requires VIEWER role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"query","name":"agentId","schema":{"type":"string","format":"uuid"},"description":"Filter by agent"},{"in":"query","name":"severity","schema":{"type":"string","enum":["low","medium","high","critical"]},"description":"Filter by severity"},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Maximum results to return"},{"in":"query","name":"offset","schema":{"type":"integer","minimum":0,"default":0},"description":"Number of results to skip"}],"responses":{"200":{"description":"Paginated anomaly events","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"agentId":{"type":"string","format":"uuid"},"metric":{"type":"string"},"severity":{"type":"string"},"zScore":{"type":"number"},"acknowledged":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"total":{"type":"integer"}}}}}}}},"401":{"description":"Unauthorized"}}}},"/anomaly/events/{id}/acknowledge":{"patch":{"tags":["Anomaly Detection"],"summary":"Acknowledge an anomaly event","description":"Marks an anomaly event as acknowledged. Requires DEVELOPER role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"Anomaly event UUID"}],"responses":{"200":{"description":"Anomaly event acknowledged","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — DEVELOPER role required"},"404":{"description":"Event not found"}}}},"/anomaly/baselines":{"get":{"tags":["Anomaly Detection"],"summary":"List metric baselines","description":"Returns computed metric baselines. Optionally filter by agent or metric name. Requires VIEWER role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"query","name":"agentId","schema":{"type":"string","format":"uuid"},"description":"Filter by agent"},{"in":"query","name":"metricName","schema":{"type":"string"},"description":"Filter by metric name"}],"responses":{"200":{"description":"List of baselines","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"agentId":{"type":"string","format":"uuid"},"metricName":{"type":"string"},"mean":{"type":"number"},"stddev":{"type":"number"},"sampleCount":{"type":"integer"},"updatedAt":{"type":"string","format":"date-time"}}}}}}}}},"401":{"description":"Unauthorized"}}}},"/anomaly/baselines/rebuild":{"post":{"tags":["Anomaly Detection"],"summary":"Rebuild metric baselines","description":"Triggers a rebuild of metric baselines from historical data. Requires ADMIN role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RebuildBaselinesInput"}}}},"responses":{"200":{"description":"Baselines rebuild initiated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — ADMIN role required"},"422":{"description":"Validation error"}}}},"/anomaly/detect":{"post":{"tags":["Anomaly Detection"],"summary":"Run ML anomaly detection","description":"Triggers ML-based anomaly detection on recent trace data. Requires DEVELOPER role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunDetectionInput"}}}},"responses":{"200":{"description":"Detection results","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"anomaliesDetected":{"type":"integer"},"results":{"type":"array","items":{"type":"object"}}}}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — DEVELOPER role required"},"422":{"description":"Validation error"}}}},"/anomaly/rca":{"post":{"tags":["Anomaly Detection"],"summary":"Run root cause analysis","description":"Performs root cause analysis for a given incident. Requires DEVELOPER role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunRCAInput"}}}},"responses":{"200":{"description":"RCA results","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"incidentId":{"type":"string","format":"uuid"},"rootCauses":{"type":"array","items":{"type":"object"}},"confidence":{"type":"number"}}}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — DEVELOPER role required"},"422":{"description":"Validation error"}}}},"/anomaly/rca/{incidentId}":{"get":{"tags":["Anomaly Detection"],"summary":"Get RCA result for an incident","description":"Retrieves a previously computed root cause analysis result. Requires VIEWER role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"path","name":"incidentId","required":true,"schema":{"type":"string","format":"uuid"},"description":"Incident UUID"}],"responses":{"200":{"description":"RCA result (or null if none exists)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","nullable":true},"message":{"type":"string","description":"Present when no RCA exists yet"}}}}}},"401":{"description":"Unauthorized"}}}},"/anomaly/forecast":{"post":{"tags":["Anomaly Detection"],"summary":"Run metric forecast","description":"Generates a predictive forecast for a given metric. Requires DEVELOPER role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunForecastInput"}}}},"responses":{"200":{"description":"Forecast results","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"forecast":{"type":"array","items":{"type":"object"}},"breachProbability":{"type":"number"}}}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — DEVELOPER role required"},"422":{"description":"Validation error"}}}},"/anomaly/forecast/history":{"get":{"tags":["Anomaly Detection"],"summary":"Get forecast history","description":"Returns previously generated forecasts. Requires VIEWER role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"query","name":"agentId","schema":{"type":"string","format":"uuid"},"description":"Filter by agent"},{"in":"query","name":"metric","schema":{"type":"string","enum":["duration_ms","estimated_cost_usd","total_tokens"]},"description":"Filter by metric"},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100},"description":"Maximum results to return"}],"responses":{"200":{"description":"Forecast history","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object"}}}}}}},"401":{"description":"Unauthorized"}}}},"/analytics/dependencies":{"get":{"tags":["Analytics"],"summary":"Get agent dependency graph","description":"Returns a graph of inter-agent dependencies (nodes and links) for the organization.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Agent dependency graph","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"nodes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}}},"links":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string","format":"uuid"},"target":{"type":"string","format":"uuid"},"value":{"type":"integer","description":"Call count"},"method":{"type":"string"},"lastSeen":{"type":"string","format":"date-time"}}}}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/analytics/costs":{"get":{"tags":["Analytics"],"summary":"Get cost analytics","description":"Returns aggregated cost data broken down by agent and environment.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Cost analytics data","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"agent_name":{"type":"string"},"environment":{"type":"string"},"total_cost":{"type":"number"},"trace_count":{"type":"integer"}}}},"meta":{"type":"object","properties":{"total":{"type":"integer"}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/analytics/metrics":{"get":{"tags":["Analytics"],"summary":"Get execution metrics","description":"Returns aggregated execution metrics with time-series data. Can be scoped to a single agent.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"query","name":"agentId","schema":{"type":"string","format":"uuid"},"description":"Optional agent UUID to scope metrics"},{"in":"query","name":"period","schema":{"type":"string","enum":["24h","7d","30d"],"default":"7d"},"description":"Time period for metrics"},{"in":"query","name":"granularity","schema":{"type":"string","enum":["hour","day"],"default":"day"},"description":"Time-series bucket granularity"}],"responses":{"200":{"description":"Aggregated metrics with time series","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"agentId":{"type":"string","format":"uuid","nullable":true},"timeRange":{"type":"object","properties":{"period":{"type":"string"},"hours":{"type":"integer"}}},"summary":{"type":"object","properties":{"totalExecutions":{"type":"integer"},"successRate":{"type":"number"},"avgLatencyMs":{"type":"number"},"p50LatencyMs":{"type":"number"},"p95LatencyMs":{"type":"number"},"p99LatencyMs":{"type":"number"},"totalCostUsd":{"type":"number"},"avgCostPerCallUsd":{"type":"number"}}},"timeSeries":{"type":"array","items":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"},"executions":{"type":"integer"},"successRate":{"type":"number"},"avgLatencyMs":{"type":"number"},"costUsd":{"type":"number"}}}}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/analytics/overview":{"get":{"tags":["Analytics"],"summary":"Get dashboard overview","description":"Returns org-level overview statistics for the dashboard, including execution stats, trend comparisons, and agent health matrix.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"query","name":"period","schema":{"type":"string","enum":["24h","7d","30d"],"default":"24h"},"description":"Time period for stats"}],"responses":{"200":{"description":"Organization-level overview","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"period":{"type":"string"},"stats":{"type":"object","properties":{"totalExecutions":{"type":"integer"},"successRate":{"type":"number"},"avgLatencyMs":{"type":"number"},"p95LatencyMs":{"type":"number"},"totalCostUsd":{"type":"number"}}},"trends":{"type":"object","description":"Percentage changes vs. previous period"},"agentHealth":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"status":{"type":"string"},"executions":{"type":"integer"},"successRate":{"type":"number"},"avgLatencyMs":{"type":"number"},"totalCost":{"type":"number"}}}}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/alerts/rules":{"get":{"tags":["Alerts"],"summary":"List alert rules","description":"Returns all alert rules for the authenticated organization. Optionally filter by enabled status. Requires VIEWER role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"query","name":"enabled","schema":{"type":"string","enum":["true","false"]},"description":"Filter by enabled status"}],"responses":{"200":{"description":"List of alert rules","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AlertRule"}},"meta":{"type":"object","properties":{"total":{"type":"integer"}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Alerts"],"summary":"Create an alert rule","description":"Creates a new alert rule for the organization. Requires ADMIN role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAlertRuleInput"}}}},"responses":{"201":{"description":"Alert rule created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AlertRule"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — ADMIN role required"},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/alerts/rules/{id}":{"get":{"tags":["Alerts"],"summary":"Get alert rule by ID","description":"Returns a single alert rule. Requires VIEWER role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"Alert rule UUID"}],"responses":{"200":{"description":"Alert rule details","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AlertRule"}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Alert rule not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Alerts"],"summary":"Update an alert rule","description":"Partially updates an alert rule. Requires ADMIN role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAlertRuleInput"}}}},"responses":{"200":{"description":"Alert rule updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AlertRule"}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — ADMIN role required"},"404":{"description":"Alert rule not found"},"422":{"description":"Validation error"}}},"delete":{"tags":["Alerts"],"summary":"Delete an alert rule","description":"Permanently deletes an alert rule. Requires ADMIN role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Alert rule deleted"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — ADMIN role required"},"404":{"description":"Alert rule not found"}}}},"/alerts/rules/{id}/toggle":{"patch":{"tags":["Alerts"],"summary":"Toggle alert rule enabled/disabled","description":"Flips the enabled state of an alert rule. Requires DEVELOPER role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Alert rule toggled","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AlertRule"}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — DEVELOPER role required"},"404":{"description":"Alert rule not found"}}}},"/alerts/history":{"get":{"tags":["Alerts"],"summary":"List alert history","description":"Returns paginated alert history (fired alerts). Filterable by severity, status, and rule. Requires VIEWER role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"query","name":"page","schema":{"type":"integer","minimum":1,"default":1},"description":"Page number"},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Items per page"},{"in":"query","name":"severity","schema":{"type":"string","enum":["critical","high","medium","low"]},"description":"Filter by severity"},{"in":"query","name":"status","schema":{"type":"string","enum":["triggered","acknowledged","resolved"]},"description":"Filter by alert status"},{"in":"query","name":"ruleId","schema":{"type":"string","format":"uuid"},"description":"Filter by alert rule ID"}],"responses":{"200":{"description":"Paginated alert history","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AlertHistoryEntry"}},"meta":{"type":"object","properties":{"total":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"},"totalPages":{"type":"integer"}}}}}}}},"401":{"description":"Unauthorized"}}}},"/alerts/history/{id}/acknowledge":{"patch":{"tags":["Alerts"],"summary":"Acknowledge an alert","description":"Marks a triggered alert as acknowledged. Requires DEVELOPER role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"Alert history entry UUID"}],"responses":{"200":{"description":"Alert acknowledged","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AlertHistoryEntry"}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — DEVELOPER role required"},"404":{"description":"Alert not found or already acknowledged"}}}},"/alerts/history/{id}/resolve":{"patch":{"tags":["Alerts"],"summary":"Resolve an alert","description":"Marks an alert as resolved. Requires DEVELOPER role.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"Alert history entry UUID"}],"responses":{"200":{"description":"Alert resolved","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AlertHistoryEntry"}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — DEVELOPER role required"},"404":{"description":"Alert not found or already resolved"}}}},"/agents":{"get":{"tags":["Agents"],"summary":"List all agents","description":"Returns paginated list of agents for the authenticated organization. Supports filtering by status and text search.","parameters":[{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Maximum number of agents to return"},{"in":"query","name":"offset","schema":{"type":"integer","minimum":0,"default":0},"description":"Number of agents to skip"},{"in":"query","name":"status","schema":{"type":"string","enum":["active","paused","archived"]},"description":"Filter by agent status"},{"in":"query","name":"search","schema":{"type":"string"},"description":"Search agents by name or ID"}],"responses":{"200":{"description":"Paginated list of agents","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Agent"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded"}}},"post":{"tags":["Agents"],"summary":"Register a new agent","description":"Registers a new AI agent in the organization. Requires DEVELOPER role or higher.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterAgentInput"}}}},"responses":{"201":{"description":"Agent registered successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Agent"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — insufficient role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/agents/export":{"get":{"tags":["Agents"],"summary":"Export agents","description":"Export agents as CSV or JSON. Requires ADMIN role.","parameters":[{"in":"query","name":"format","schema":{"type":"string","enum":["csv","json"],"default":"json"}},{"in":"query","name":"status","schema":{"type":"string","enum":["active","paused","archived"]}},{"in":"query","name":"environment","schema":{"type":"string","enum":["development","staging","production"]}},{"in":"query","name":"type","schema":{"type":"string"}}],"responses":{"200":{"description":"Exported agent data","content":{"application/json":{"schema":{"type":"object"}},"text/csv":{"schema":{"type":"string"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — ADMIN role required"}}}},"/agents/audit-logs/all":{"get":{"tags":["Agents"],"summary":"Get organization audit logs","description":"Returns audit logs for the organization. Requires ADMIN role.","parameters":[{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Audit log entries","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"action":{"type":"string"},"resourceType":{"type":"string"},"resourceId":{"type":"string"},"userId":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}}}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — ADMIN role required"}}}},"/agents/{id}":{"get":{"tags":["Agents"],"summary":"Get agent by ID","description":"Returns a single agent by its UUID. Requires VIEW permission on the agent.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"Agent UUID"}],"responses":{"200":{"description":"Agent details","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Agent"}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Agent not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Agents"],"summary":"Update agent details","description":"Update agent name, description, tags, metadata, etc. Requires EDIT permission.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAgentInput"}}}},"responses":{"200":{"description":"Agent updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Agent"}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Agent not found"},"422":{"description":"Validation error"}}},"delete":{"tags":["Agents"],"summary":"Archive (soft-delete) an agent","description":"Archives an agent. Requires ADMIN role.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Agent archived","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Agent archived successfully"}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — ADMIN role required"},"404":{"description":"Agent not found"}}}},"/agents/{id}/stats":{"get":{"tags":["Agents"],"summary":"Get agent performance stats","description":"Returns performance statistics for 24h, 7d, and 30d periods. Requires VIEW permission.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Agent stats across three time periods","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"agentId":{"type":"string","format":"uuid"},"agentName":{"type":"string"},"period24h":{"$ref":"#/components/schemas/AgentStatsPeriod"},"period7d":{"$ref":"#/components/schemas/AgentStatsPeriod"},"period30d":{"$ref":"#/components/schemas/AgentStatsPeriod"}}}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Agent not found"}}}},"/agents/{id}/budget":{"get":{"tags":["Agents"],"summary":"Get agent budget info","description":"Returns budget configuration and current spend for an agent. Requires VIEW permission.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Agent budget details","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AgentBudget"}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Agent not found"}}},"patch":{"tags":["Agents"],"summary":"Update agent budget","description":"Update monthly budget and budget action. Requires EDIT permission.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"monthlyBudgetUsd":{"type":"number","example":500},"budgetAction":{"type":"string","enum":["alert","pause_agent"]}}}}}},"responses":{"200":{"description":"Budget updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AgentBudget"}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Agent not found"}}}},"/agents/{id}/pause":{"patch":{"tags":["Agents"],"summary":"Pause agent (kill switch)","description":"Pauses an agent immediately. Broadcasts to SDK control channel via Redis pub/sub. Includes blast radius (dependent agents). Requires PAUSE permission.\n","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string","minLength":1,"example":"Detected anomalous behavior"}}}}}},"responses":{"200":{"description":"Agent paused","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","example":"paused"},"pausedAt":{"type":"string","format":"date-time"},"pausedBy":{"type":"string","format":"uuid"},"pauseReason":{"type":"string"},"controlChannelBroadcasted":{"type":"boolean"},"blastRadius":{"type":"object","properties":{"dependentAgents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"status":{"type":"string"}}}},"count":{"type":"integer"}}}}}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Agent not found"},"422":{"description":"Validation error — reason is required"}}}},"/agents/{id}/resume":{"patch":{"tags":["Agents"],"summary":"Resume agent","description":"Resumes a paused agent. Broadcasts to SDK control channel. Requires ADMIN role.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","description":"Optional reason for resuming"}}}}}},"responses":{"200":{"description":"Agent resumed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","example":"active"},"resumedAt":{"type":"string","format":"date-time"},"resumedBy":{"type":"string","format":"uuid"}}}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — ADMIN role required"},"404":{"description":"Agent not found"}}}},"/agents/{id}/status":{"patch":{"tags":["Agents"],"summary":"Update agent status","description":"Toggle agent between active and paused status. Requires PAUSE permission.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["active","paused"]},"reason":{"type":"string","description":"Required when pausing"}}}}}},"responses":{"200":{"description":"Agent status updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Agent"}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Agent not found"},"422":{"description":"Validation error — invalid status value"}}}},"/agents/{id}/status-poll":{"get":{"tags":["Agents"],"summary":"Poll agent status (SDK fallback)","description":"Lightweight status check endpoint for SDK HTTP fallback when WebSocket/Redis is unavailable.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Current agent status","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","enum":["active","paused","archived"]},"pauseReason":{"type":"string","nullable":true}}}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Agent not found"}}}},"/agents/{id}/dependencies":{"get":{"tags":["Agents"],"summary":"Get agent dependencies","description":"Returns upstream and downstream agent dependencies. Requires VIEW permission.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Agent dependency graph","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"agentId":{"type":"string","format":"uuid"},"upstream":{"type":"array","items":{"type":"object"}},"downstream":{"type":"array","items":{"type":"object"}}}}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Agent not found"}}}},"/agents/{id}/keys":{"post":{"tags":["Agents"],"summary":"Generate API key for agent","description":"Creates a new API key bound to the agent. The plain key is returned only once. Requires ADMIN role.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateApiKeyInput"}}}},"responses":{"201":{"description":"API key generated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"key":{"type":"string","description":"Plain API key — shown only once","example":"exe_prod_abc123..."},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time","nullable":true}}},"message":{"type":"string","example":"Please save this key securely. It will not be shown again."}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — ADMIN role required"},"404":{"description":"Agent not found"},"422":{"description":"Validation error"}}}}},"tags":[]}