{ "openapi": "3.1.0", "info": { "title": "SealGate Management API", "version": "1.0.0", "summary": "REST API for managing the SealGate agentic-AI data-leak-prevention platform.", "description": "The SealGate Management API is the REST control plane for the SealGate agentic-AI security gateway and data firewall. It lets security, IT, and compliance teams manage MCP servers, sessions, access-control roles, deterministic policy rules, approvals, agents, API keys, and observability data programmatically.\n\n## Authentication\nAll endpoints require an HTTP Bearer credential: send `Authorization: Bearer `, where the token is a SealGate API key (obtained from the SealGate dashboard). This management API key is distinct from the MCP gateway credentials used by AI clients. Requests without a valid, active key receive `401`. A key whose role lacks the required permission receives `403`.\n\n## Versioning and deprecation policy\nThe API is versioned in the URL path: every operation lives under `/api/v1`. Breaking changes (removing a field, changing a type, removing an endpoint) are shipped only under a new path prefix such as `/api/v2`; additive changes (new endpoints, new optional fields) are made in place under `/api/v1`. When an endpoint or field is scheduled for removal it is first marked `deprecated: true` in this specification and announced in the changelog at https://docs.sealgate.ai; deprecated surfaces continue to function for a published sunset window before a new major version drops them.\n\n## Error model\nErrors use standard HTTP status codes with a JSON body. Application errors raised by the API return `{\"detail\": {\"error\": , \"code\": , \"details\": }}`. Request-validation failures return `422` with `{\"detail\": [{\"loc\": [...], \"msg\": \"...\", \"type\": \"...\"}]}`. Every non-2xx response documents a typed JSON schema.\n\n## Pagination\nList endpoints are page-based. Pass `page` (1-indexed) and `per_page` query parameters; responses return an envelope with `items`, `total`, `page`, `per_page`, and `total_pages`.", "termsOfService": "https://sealgate.ai/terms-of-service", "contact": { "name": "SealGate", "email": "hello@sealgate.ai", "url": "https://sealgate.ai" }, "license": { "name": "Proprietary", "url": "https://sealgate.ai/terms-of-service" }, "x-source-of-truth": { "description": "This published spec is a curated, human-reviewed mirror of the SealGate management API. The authoritative, always-current OpenAPI schema is generated live from the backend Pydantic models and served at generatedSpecUrl. Regenerate this mirror from the backend source when the API changes; do not hand-edit it to diverge from the generated schema.", "generatedSpecUrl": "https://dashboard.sealgate.ai/api/v1/openapi.json", "backendSource": "SealGate backend, src/api/v1/ (routes and Pydantic schemas)" } }, "externalDocs": { "description": "SealGate product documentation", "url": "https://docs.sealgate.ai" }, "servers": [ { "url": "https://dashboard.sealgate.ai", "description": "SealGate management API - release" }, { "url": "https://demo-dashboard.sealgate.ai", "description": "SealGate management API - demo" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Servers", "description": "Manage connected MCP servers and their configuration." }, { "name": "Sessions", "description": "Inspect agent sessions, tool-call history, and risk analysis." }, { "name": "Policies", "description": "CEL-based deterministic policy rules for agent tool calls." }, { "name": "Access Control", "description": "Roles, role assignments, and enablement scoping." }, { "name": "API Keys", "description": "Enable, disable, and re-role API keys." }, { "name": "Approvals", "description": "Review and resolve gated (lethal-trifecta and policy) approval requests." }, { "name": "Agents", "description": "Register and manage AI agents." }, { "name": "Observability", "description": "Trifecta event summaries and the audit log." }, { "name": "System", "description": "Service health." } ], "paths": { "/api/v1/health": { "get": { "tags": ["System"], "summary": "Service health check", "operationId": "getHealth", "security": [], "responses": { "200": { "description": "Service is healthy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } } } } }, "/api/v1/servers": { "get": { "tags": ["Servers"], "summary": "List MCP servers", "description": "List MCP servers visible to the caller, with pagination and optional name search.", "operationId": "listServers", "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "name": "per_page", "in": "query", "required": false, "description": "Items per page", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "q", "in": "query", "required": false, "description": "Search by server name or display name", "schema": { "type": "string", "maxLength": 200 } }, { "name": "my_mcps", "in": "query", "required": false, "description": "When true, hide globally-disabled stdio_tunnel servers with no override for the caller", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "A page of server summaries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerSummaryPage" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "post": { "tags": ["Servers"], "summary": "Create an MCP server", "description": "Register a new MCP server. Requires the admin role.", "operationId": "createServer", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateServerRequest" } } } }, "responses": { "201": { "description": "The created server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerDetail" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/api/v1/servers/{name}": { "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Server MCP prefix name", "schema": { "type": "string" } } ], "get": { "tags": ["Servers"], "summary": "Get an MCP server", "operationId": "getServer", "responses": { "200": { "description": "Server detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerDetail" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": ["Servers"], "summary": "Update an MCP server", "description": "Update an MCP server's configuration. Requires the admin role.", "operationId": "updateServer", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateServerRequest" } } } }, "responses": { "200": { "description": "The updated server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerDetail" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "delete": { "tags": ["Servers"], "summary": "Delete an MCP server", "description": "Delete an MCP server. Requires the admin role.", "operationId": "deleteServer", "responses": { "204": { "description": "Server deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/sessions": { "get": { "tags": ["Sessions"], "summary": "List agent sessions", "description": "List agent sessions the caller may see, with pagination, filtering, sorting, and full-text search.", "operationId": "listSessions", "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/PerPageParam" }, { "name": "user_id", "in": "query", "required": false, "description": "Filter by user ID", "schema": { "type": "string" } }, { "name": "agent_name", "in": "query", "required": false, "description": "Filter by agent name", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by session status", "schema": { "type": "string" } }, { "name": "sort_by", "in": "query", "required": false, "description": "Sort field", "schema": { "type": "string", "enum": ["created_at", "last_activity_at", "duration_ms", "tool_call_count"], "default": "created_at" } }, { "name": "sort_order", "in": "query", "required": false, "description": "Sort order", "schema": { "type": "string", "enum": ["asc", "desc"], "default": "desc" } }, { "name": "q", "in": "query", "required": false, "description": "Text search over session ID, agent name, user email, and tool names", "schema": { "type": "string", "maxLength": 200 } }, { "name": "risk", "in": "query", "required": false, "description": "Filter by risk level(s), comma-separated (Low, Medium, High)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of session summaries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionSummaryPage" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/api/v1/sessions/{session_id}": { "parameters": [ { "name": "session_id", "in": "path", "required": true, "description": "Session identifier", "schema": { "type": "string" } } ], "get": { "tags": ["Sessions"], "summary": "Get a session", "description": "Fetch a single session with its full tool-call history and risk analysis.", "operationId": "getSession", "responses": { "200": { "description": "Session detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionDetail" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/sessions/{session_id}/end": { "parameters": [ { "name": "session_id", "in": "path", "required": true, "description": "Session identifier", "schema": { "type": "string" } } ], "post": { "tags": ["Sessions"], "summary": "End a session", "description": "Mark an active session as ended.", "operationId": "endSession", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndSessionRequest" } } } }, "responses": { "200": { "description": "Session ended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/api/v1/policies": { "get": { "tags": ["Policies"], "summary": "List policy rules", "description": "List CEL-based policy rules. Requires the admin role.", "operationId": "listPolicies", "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/PerPageParam" } ], "responses": { "200": { "description": "A page of policy rules", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyRulePage" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "post": { "tags": ["Policies"], "summary": "Create a policy rule", "description": "Create a CEL-based policy rule. Requires the admin role.", "operationId": "createPolicy", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePolicyRequest" } } } }, "responses": { "201": { "description": "The created policy rule", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyRule" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/api/v1/policies/overview": { "get": { "tags": ["Policies"], "summary": "Policy overview statistics", "description": "Aggregate counts of policy rules by status, phase, and action type. Requires the admin role.", "operationId": "policyOverview", "responses": { "200": { "description": "Policy overview statistics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyOverviewStats" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/policies/{rule_id}": { "parameters": [ { "name": "rule_id", "in": "path", "required": true, "description": "Unique policy rule identifier", "schema": { "type": "string" } } ], "delete": { "tags": ["Policies"], "summary": "Delete a policy rule", "description": "Delete a policy rule by its rule_id. Requires the admin role.", "operationId": "deletePolicy", "responses": { "204": { "description": "Policy rule deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/access-control/roles": { "get": { "tags": ["Access Control"], "summary": "List roles and assignments", "description": "Return role definitions and user-to-role assignments for the caller's domain. Requires the admin role.", "operationId": "listRoles", "responses": { "200": { "description": "Role definitions and assignments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RolesListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/access-control/roles/definitions": { "post": { "tags": ["Access Control"], "summary": "Create a role definition", "description": "Create a new role in the caller's domain. Requires the admin role.", "operationId": "createRole", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRoleRequest" } } } }, "responses": { "201": { "description": "The created role definition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleDefinition" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/api/v1/access-control/summary": { "get": { "tags": ["Access Control"], "summary": "Access-control summary counts", "description": "Counts of roles and enablement overrides for the caller's domain. Requires the admin role.", "operationId": "accessControlSummary", "responses": { "200": { "description": "Access-control summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessControlSummary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/api-keys/{api_key_param}/status": { "parameters": [ { "name": "api_key_param", "in": "path", "required": true, "description": "The target API key to modify", "schema": { "type": "string" } } ], "patch": { "tags": ["API Keys"], "summary": "Enable or disable an API key", "description": "Set an API key's active status. Requires the admin role.", "operationId": "updateApiKeyStatus", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateApiKeyStatusRequest" } } } }, "responses": { "200": { "description": "Updated status (API key returned masked)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateApiKeyStatusResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/api/v1/api-keys/{api_key_param}/role": { "parameters": [ { "name": "api_key_param", "in": "path", "required": true, "description": "The target API key to modify", "schema": { "type": "string" } } ], "patch": { "tags": ["API Keys"], "summary": "Change an API key's role", "description": "Change an API key's role (admin, user, owner). Requires the admin role.", "operationId": "updateApiKeyRole", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateApiKeyRoleRequest" } } } }, "responses": { "200": { "description": "Updated role (API key returned masked)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateApiKeyRoleResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/api/v1/approvals": { "get": { "tags": ["Approvals"], "summary": "List approval requests", "description": "List gated approval requests. USER sees their own; ADMIN and OWNER see their domain.", "operationId": "listApprovals", "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "name": "per_page", "in": "query", "required": false, "description": "Results per page", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "status", "in": "query", "required": false, "description": "Filter by status: pending, approved, denied", "schema": { "type": "string", "enum": ["pending", "approved", "denied"] } } ], "responses": { "200": { "description": "A page of approval requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequestPage" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/api/v1/approvals/{approval_id}/approve": { "parameters": [ { "name": "approval_id", "in": "path", "required": true, "description": "Approval request ID", "schema": { "type": "integer" } } ], "post": { "tags": ["Approvals"], "summary": "Approve a gated action", "description": "Approve a blocked trifecta or policy action. Requires the admin role.", "operationId": "approveRequest", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApproveAction" } } } }, "responses": { "200": { "description": "The approved request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequest" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/api/v1/approvals/{approval_id}/deny": { "parameters": [ { "name": "approval_id", "in": "path", "required": true, "description": "Approval request ID", "schema": { "type": "integer" } } ], "post": { "tags": ["Approvals"], "summary": "Deny a gated action", "description": "Deny a blocked trifecta or policy action. Requires the admin role.", "operationId": "denyRequest", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DenyAction" } } } }, "responses": { "200": { "description": "The denied request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequest" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/api/v1/agents": { "get": { "tags": ["Agents"], "summary": "List agents", "description": "List registered agents. ADMIN sees domain agents; OWNER sees all. Requires the admin role.", "operationId": "listAgents", "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/PerPageParam" }, { "name": "q", "in": "query", "required": false, "description": "Search by agent name", "schema": { "type": "string", "maxLength": 200 } }, { "name": "agent_type", "in": "query", "required": false, "description": "Filter by agent type", "schema": { "type": "string" } }, { "name": "include_archived", "in": "query", "required": false, "description": "Include archived agents (owner only)", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "A page of agent summaries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSummaryPage" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "post": { "tags": ["Agents"], "summary": "Register an agent", "description": "Register a new agent. OWNER may target a specific domain. Requires the admin role.", "operationId": "createAgent", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentRequest" } } } }, "responses": { "201": { "description": "The registered agent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentDetail" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/api/v1/observability/trifecta": { "get": { "tags": ["Observability"], "summary": "Trifecta event summary", "description": "Summary counts of lethal-trifecta events within a rolling window. Requires the admin role.", "operationId": "getTrifectaSummary", "parameters": [ { "name": "time_period", "in": "query", "required": false, "description": "Rolling window: 24h, 7d, or 30d", "schema": { "type": "string", "enum": ["24h", "7d", "30d"], "default": "24h" } } ], "responses": { "200": { "description": "Trifecta summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrifectaSummary" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/observability/trifecta/events": { "get": { "tags": ["Observability"], "summary": "List trifecta events", "description": "List lethal-trifecta events with pagination and date filters. Requires the admin role.", "operationId": "listTrifectaEvents", "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "name": "per_page", "in": "query", "required": false, "description": "Results per page", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "created_after", "in": "query", "required": false, "description": "Filter events after this date-time", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_before", "in": "query", "required": false, "description": "Filter events before this date-time", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "A page of trifecta events", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrifectaEventPage" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/api/v1/observability/audit-log": { "get": { "tags": ["Observability"], "summary": "List audit log entries", "description": "List audit-log entries with pagination and filters. Requires the admin role.", "operationId": "listAuditLog", "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "name": "per_page", "in": "query", "required": false, "description": "Results per page", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "actor", "in": "query", "required": false, "description": "Filter by actor user ID", "schema": { "type": "string" } }, { "name": "action", "in": "query", "required": false, "description": "Filter by action type", "schema": { "type": "string" } }, { "name": "resource_type", "in": "query", "required": false, "description": "Filter by resource type", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of audit-log entries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditEntryPage" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "SealGate API key", "description": "SealGate API key sent as `Authorization: Bearer `." } }, "parameters": { "PageParam": { "name": "page", "in": "query", "required": false, "description": "Page number (1-indexed)", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, "PerPageParam": { "name": "per_page", "in": "query", "required": false, "description": "Items per page", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } }, "responses": { "BadRequest": { "description": "The request was invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Unauthorized": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Forbidden": { "description": "The caller's role is not permitted to perform this action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "NotFound": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Conflict": { "description": "The resource already exists or conflicts with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "ValidationError": { "description": "Request validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "schemas": { "ErrorDetail": { "type": "object", "description": "Application error body carried under `detail`.", "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "details": { "type": ["object", "null"], "description": "Additional error details", "additionalProperties": true } }, "required": ["error", "code"] }, "ErrorResponse": { "type": "object", "description": "Standard error envelope returned on 4xx and 5xx responses.", "properties": { "detail": { "$ref": "#/components/schemas/ErrorDetail" } }, "required": ["detail"] }, "ValidationError": { "type": "object", "description": "A single request-validation error.", "properties": { "loc": { "type": "array", "items": { "type": ["string", "integer"] }, "description": "Location of the invalid field" }, "msg": { "type": "string", "description": "Validation error message" }, "type": { "type": "string", "description": "Validation error type" } }, "required": ["loc", "msg", "type"] }, "HTTPValidationError": { "type": "object", "description": "Body returned for a 422 request-validation failure.", "properties": { "detail": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationError" } } } }, "HealthResponse": { "type": "object", "properties": { "status": { "type": "string", "description": "Service status", "examples": ["ok"] } }, "required": ["status"] }, "OkResponse": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "Whether the operation succeeded" } }, "required": ["ok"] }, "ServerRuntimeHealth": { "type": "object", "description": "Live runtime health of a mounted MCP server.", "properties": { "state": { "type": "string", "enum": ["ok", "starting", "degraded"], "description": "Runtime state" }, "error_kind": { "type": ["string", "null"], "enum": ["auth_required", "forbidden", "rate_limited", "upstream_error", "http_error", "timeout", "unreachable", "mount_failed", "no_tools", "unknown", null], "description": "Discriminating reason when state is degraded; null otherwise" }, "reason": { "type": ["string", "null"], "description": "Short user-facing label derived from error_kind" }, "detail": { "type": ["string", "null"], "description": "Longer error message tail" }, "last_check_at": { "type": ["string", "null"], "format": "date-time" }, "consecutive_failures": { "type": "integer", "default": 0 }, "next_check_at": { "type": ["string", "null"], "format": "date-time" } }, "required": ["state"] }, "ServerElement": { "type": "object", "properties": { "id": { "type": "integer", "description": "Element ID" }, "name": { "type": "string", "description": "Element name (permission_key)" }, "compacted_name": { "type": ["string", "null"], "description": "Client-facing tool name after prefixing and length compaction" }, "type": { "type": "string", "description": "Element type: tool, resource, or prompt" }, "permission_key": { "type": "string", "description": "Permission key for this element" }, "server_name": { "type": "string", "description": "Parent server name" } }, "required": ["id", "name", "type", "permission_key", "server_name"] }, "TemplateFieldSchema": { "type": "object", "properties": { "id": { "type": "integer" }, "field_type": { "type": "string", "description": "Field type: arg or env" }, "template_key": { "type": "string" }, "description": { "type": ["string", "null"] }, "example": { "type": ["string", "null"] }, "required": { "type": "boolean", "default": false }, "set_by_user": { "type": "boolean", "default": true }, "has_admin_value": { "type": "boolean", "default": false }, "has_user_value": { "type": "boolean", "default": false } }, "required": ["id", "field_type", "template_key"] }, "ServerSummary": { "type": "object", "description": "Summary view of a connected MCP server.", "properties": { "id": { "type": "integer", "description": "Server ID" }, "name": { "type": "string", "description": "Server MCP prefix name (alphanumeric)" }, "display_name": { "type": "string", "description": "Human-readable display name" }, "command": { "type": "string", "description": "Server command" }, "enabled": { "type": "boolean", "description": "Whether the server is enabled at the admin/global level" }, "tool_count": { "type": "integer", "description": "Number of registered tools/elements" }, "needs_config": { "type": "boolean", "description": "Whether the server has unconfigured required template fields" }, "domain": { "type": "string", "description": "Domain this server belongs to" }, "is_builtin": { "type": "boolean", "default": false, "description": "Whether this is the auto-provisioned builtin server" }, "user_enabled": { "type": ["boolean", "null"], "description": "User-level enablement override; null means no override" }, "parent_enabled": { "type": "boolean", "description": "Effective enabled state from the role/global hierarchy, ignoring any user override" }, "user_locked": { "type": "boolean", "default": false, "description": "Whether the caller's enablement override is admin-locked" }, "config_warnings": { "type": "array", "items": { "type": "string" }, "description": "Human-readable warnings about missing configuration" }, "icon_url": { "type": ["string", "null"], "description": "Remote icon URL" }, "runtime_health": { "oneOf": [ { "$ref": "#/components/schemas/ServerRuntimeHealth" }, { "type": "null" } ], "description": "Live mount and ping health, or null when no per-user MCP instance exists yet" }, "authenticated_user_emails": { "type": "array", "items": { "type": "string" }, "description": "Emails of users who have invoked tools on this server" }, "transport_type": { "type": "string", "default": "http", "description": "Transport: 'http' (remote URL) or 'stdio_tunnel' (proxied via daemon)" }, "device_id": { "type": ["string", "null"], "description": "Human-readable device label for a bound stdio_tunnel device" }, "device_owner_email": { "type": ["string", "null"], "description": "Email of the device owner for a stdio_tunnel server" } }, "required": ["id", "name", "display_name", "command", "enabled", "tool_count", "needs_config", "domain", "parent_enabled"] }, "ServerDetail": { "allOf": [ { "$ref": "#/components/schemas/ServerSummary" }, { "type": "object", "properties": { "elements": { "type": "array", "items": { "$ref": "#/components/schemas/ServerElement" }, "description": "Server elements (tools, resources, prompts)" }, "template_fields": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateFieldSchema" }, "description": "Template fields requiring configuration" }, "args": { "type": "array", "items": { "type": "string" }, "description": "Command-line arguments" }, "env": { "type": "object", "additionalProperties": { "type": ["string", "null"] }, "description": "Environment variables" }, "url": { "type": ["string", "null"], "description": "Remote server URL (direct mode)" }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Custom HTTP headers" }, "version": { "type": ["string", "null"], "description": "Server version" }, "from_marketplace_id": { "type": ["string", "null"], "description": "Marketplace ID this server was installed from" } } } ] }, "CreateServerRequest": { "type": "object", "description": "Body for creating an MCP server.", "properties": { "name": { "type": "string", "description": "Server MCP prefix name (alphanumeric only)" }, "display_name": { "type": ["string", "null"], "description": "Human-readable display name (defaults to name)" }, "command": { "type": "string", "default": "", "description": "Server command (required for local servers)" }, "args": { "type": "array", "items": { "type": "string" }, "description": "Command-line arguments" }, "env": { "type": "object", "additionalProperties": { "type": ["string", "null"] }, "description": "Environment variables" }, "url": { "type": ["string", "null"], "description": "Remote server URL (direct mode, no mcp-remote)" }, "headers": { "type": ["object", "null"], "additionalProperties": { "type": "string" }, "description": "Custom HTTP headers for remote servers" }, "enabled": { "type": "boolean", "default": true, "description": "Whether to enable the server" }, "version": { "type": ["string", "null"], "description": "Server version" }, "transport_type": { "type": "string", "default": "http", "description": "Transport: 'http' or 'stdio_tunnel'" }, "device_ref_id": { "type": ["integer", "null"], "description": "Target device id, required when transport_type is 'stdio_tunnel'" }, "working_dir": { "type": ["string", "null"], "description": "Optional working directory for stdio_tunnel subprocesses" }, "icon_url": { "type": ["string", "null"], "description": "Manual override icon URL" } }, "required": ["name"] }, "UpdateServerRequest": { "type": "object", "description": "Partial update for an MCP server; omitted fields are left unchanged.", "properties": { "name": { "type": ["string", "null"], "description": "New MCP prefix name (alphanumeric only)" }, "display_name": { "type": ["string", "null"], "description": "New human-readable display name" }, "command": { "type": ["string", "null"], "description": "New server command" }, "args": { "type": ["array", "null"], "items": { "type": "string" }, "description": "New command-line arguments" }, "env": { "type": ["object", "null"], "additionalProperties": { "type": ["string", "null"] }, "description": "New environment variables" }, "url": { "type": ["string", "null"], "description": "Remote server URL (direct mode)" }, "headers": { "type": ["object", "null"], "additionalProperties": { "type": "string" }, "description": "Custom HTTP headers for remote servers" }, "enabled": { "type": ["boolean", "null"], "description": "Enable or disable the server" }, "icon_url": { "type": ["string", "null"], "description": "Manual override icon URL" } } }, "ServerSummaryPage": { "type": "object", "description": "Paginated list of server summaries.", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ServerSummary" } }, "total": { "type": "integer", "description": "Total items across all pages" }, "page": { "type": "integer", "description": "Current page number (1-indexed)" }, "per_page": { "type": "integer", "description": "Items per page" }, "total_pages": { "type": "integer", "description": "Total number of pages" } }, "required": ["items", "total", "page", "per_page", "total_pages"] }, "ToolCall": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique tool call identifier" }, "tool_name": { "type": "string", "description": "Name of the MCP tool invoked" }, "parameters": { "type": "object", "additionalProperties": true, "description": "Parameters passed to the tool" }, "timestamp": { "type": "string", "format": "date-time", "description": "When the tool call was made" }, "duration_ms": { "type": ["integer", "null"], "description": "Execution time in milliseconds" }, "status": { "type": "string", "description": "Outcome status (e.g. success, blocked, error)" }, "result": { "description": "Tool call result payload" }, "read_private_data": { "type": "boolean", "default": false }, "read_untrusted_public_data": { "type": "boolean", "default": false }, "write_operation": { "type": "boolean", "default": false }, "acl": { "type": "string", "default": "PUBLIC", "description": "Tool ACL level (PUBLIC, PRIVATE, SECRET)" } }, "required": ["id", "tool_name", "parameters", "timestamp", "status"] }, "RiskInfo": { "type": "object", "description": "Plain-language risk explanation for a blocked action.", "properties": { "title": { "type": "string" }, "headline": { "type": "string" }, "summary": { "type": "string" }, "legs": { "type": ["object", "null"], "additionalProperties": { "type": "string" }, "description": "Trifecta legs (private/untrusted/external) with their sources" }, "server_name": { "type": "string" }, "acl_level": { "type": "string" }, "risk_level": { "type": ["string", "null"], "description": "Severity: low, medium, high, or critical" }, "policy_rule": { "type": ["string", "null"] }, "source": { "type": "string", "default": "template", "description": "How the summary was produced: template or llm" } } }, "RiskAnalysisEntry": { "type": "object", "properties": { "timestamp": { "type": ["string", "null"], "format": "date-time" }, "kind": { "type": "string", "default": "tool", "description": "Element kind: tool, resource, or prompt" }, "name": { "type": "string", "description": "Prefixed name of the blocked element" }, "reason": { "type": "string", "description": "Block reason, e.g. trifecta or trifecta_prevent" }, "risk": { "$ref": "#/components/schemas/RiskInfo" } }, "required": ["risk"] }, "SessionSummary": { "type": "object", "description": "Summary view of an agent session.", "properties": { "id": { "type": "string", "description": "Session identifier" }, "correlation_id": { "type": "string", "description": "Correlation ID linking related events" }, "session_token": { "type": ["string", "null"], "description": "Session token for token-based sessions; null otherwise" }, "user_id": { "type": "string", "description": "Authenticated user ID" }, "user_email": { "type": "string", "description": "User email address" }, "agent_name": { "type": "string", "description": "Name of the AI agent" }, "agent_type": { "type": "string", "description": "Type/category of the agent" }, "created_at": { "type": "string", "format": "date-time", "description": "Session start timestamp" }, "last_activity_at": { "type": ["string", "null"], "format": "date-time", "description": "Timestamp of the last tool call activity" }, "duration_ms": { "type": ["integer", "null"], "description": "Total session duration in milliseconds" }, "tool_call_count": { "type": "integer", "description": "Number of tool calls in this session" }, "status": { "type": "string", "description": "Session status (active, completed, error)" }, "trifecta_flags": { "type": "array", "items": { "type": "string" }, "description": "Trifecta security flags triggered" }, "trifecta_disposition": { "type": "string", "default": "none", "description": "Worst outcome of any trifecta write gated for approval: none, pending, approved, expired, denied" }, "trifecta_block_count": { "type": "integer", "default": 0, "description": "Number of trifecta writes gated for approval this session" }, "block_severity": { "type": "string", "default": "none", "description": "Severity of trifecta blocks: none, low, medium, high" }, "acl_level": { "type": "string", "default": "PUBLIC", "description": "Highest ACL level (PUBLIC, PRIVATE, SECRET)" }, "tool_names": { "type": "array", "items": { "type": "string" }, "description": "Distinct tool names invoked in this session" } }, "required": ["id", "correlation_id", "user_id", "user_email", "agent_name", "agent_type", "created_at", "tool_call_count", "status", "trifecta_flags"] }, "SessionDetail": { "allOf": [ { "$ref": "#/components/schemas/SessionSummary" }, { "type": "object", "properties": { "tool_calls": { "type": "array", "items": { "$ref": "#/components/schemas/ToolCall" }, "description": "Ordered list of tool calls in this session" }, "data_access_summary": { "type": "object", "additionalProperties": true, "description": "Summary of data access patterns during the session" }, "risk_analysis": { "type": "array", "items": { "$ref": "#/components/schemas/RiskAnalysisEntry" }, "description": "History of trifecta block analyses" } }, "required": ["tool_calls", "data_access_summary"] } ] }, "EndSessionRequest": { "type": "object", "properties": { "reason": { "type": "string", "default": "unknown", "description": "Reason the session ended" } } }, "SessionSummaryPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SessionSummary" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total_pages": { "type": "integer" } }, "required": ["items", "total", "page", "per_page", "total_pages"] }, "PrincipalScope": { "type": "object", "properties": { "is_global": { "type": "boolean", "default": true, "description": "Whether the rule applies to all users" }, "include_roles": { "type": "array", "items": { "type": "string" } }, "include_users": { "type": "array", "items": { "type": "string" } }, "exclude_roles": { "type": "array", "items": { "type": "string" } }, "exclude_users": { "type": "array", "items": { "type": "string" } } } }, "ResourceScope": { "type": "object", "properties": { "element_types": { "type": "array", "items": { "type": "string" }, "description": "Element types: tool, resource, prompt" }, "servers": { "type": "array", "items": { "type": "string" }, "description": "MCP server names" }, "name_patterns": { "type": "array", "items": { "type": "string" }, "description": "Regex patterns for element names" } } }, "PolicyAction": { "type": "object", "properties": { "action_type": { "type": "string", "description": "Action type: block, require_approval, allow_override, mark_private, mark_untrusted, mark_write, set_acl, add_tag" }, "acl_level": { "type": ["string", "null"], "description": "ACL level for set_acl action" }, "tag_key": { "type": ["string", "null"] }, "tag_value": { "type": ["string", "null"] }, "block_reason": { "type": ["string", "null"] }, "approval_reason": { "type": ["string", "null"], "description": "Plain-language reason shown to the human deciding" }, "approval_channels": { "type": "array", "items": { "type": "string" }, "description": "Channels to pin the approval prompt to" }, "approval_timeout_s": { "type": ["number", "null"], "description": "How long to hold the call awaiting a decision; null uses the server default" }, "approval_on_timeout": { "type": ["string", "null"], "enum": ["deny", "allow", null], "description": "What happens when nobody answers in time; null means deny (fail closed). 'allow' is deprecated and reported as 'deny'" } }, "required": ["action_type"] }, "PolicyRule": { "type": "object", "description": "A CEL-based policy rule.", "properties": { "id": { "type": "integer", "description": "Database row ID" }, "rule_id": { "type": "string", "description": "Unique rule identifier" }, "name": { "type": "string", "description": "Human-readable rule name" }, "description": { "type": ["string", "null"] }, "cel_expression": { "type": ["string", "null"], "description": "CEL filter expression" }, "phase": { "type": "string", "default": "pre", "description": "Evaluation phase: pre or post" }, "status": { "type": "string", "default": "enabled", "description": "Rule status: enabled, disabled, or tentative" }, "priority": { "type": "integer", "default": 0, "description": "Rule priority (higher evaluated first)" }, "domain": { "type": ["string", "null"], "description": "Domain scope (null = global)" }, "principal_scope": { "$ref": "#/components/schemas/PrincipalScope" }, "resource_scope": { "$ref": "#/components/schemas/ResourceScope" }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/PolicyAction" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": ["id", "rule_id", "name", "phase", "status", "priority", "principal_scope", "resource_scope", "actions", "created_at", "updated_at"] }, "CreatePolicyRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "Rule name" }, "rule_id": { "type": "string", "description": "Unique rule identifier" }, "description": { "type": ["string", "null"] }, "cel_expression": { "type": ["string", "null"], "description": "CEL filter expression" }, "phase": { "type": "string", "default": "pre", "description": "Evaluation phase: pre or post. A post-phase rule cannot carry a require_approval action" }, "status": { "type": "string", "default": "enabled", "description": "Rule status: enabled, disabled, or tentative" }, "priority": { "type": "integer", "default": 0 }, "principal_scope": { "oneOf": [ { "$ref": "#/components/schemas/PrincipalScope" }, { "type": "null" } ] }, "resource_scope": { "oneOf": [ { "$ref": "#/components/schemas/ResourceScope" }, { "type": "null" } ] }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/PolicyAction" } } }, "required": ["name", "rule_id"] }, "PolicyOverviewStats": { "type": "object", "properties": { "total_rules": { "type": "integer" }, "enabled_count": { "type": "integer", "default": 0 }, "disabled_count": { "type": "integer", "default": 0 }, "tentative_count": { "type": "integer", "default": 0 }, "pre_phase_count": { "type": "integer", "default": 0 }, "post_phase_count": { "type": "integer", "default": 0 }, "action_counts": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Count of each action type" } }, "required": ["total_rules"] }, "PolicyRulePage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PolicyRule" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total_pages": { "type": "integer" } }, "required": ["items", "total", "page", "per_page", "total_pages"] }, "RoleDefinition": { "type": "object", "properties": { "id": { "type": "integer" }, "role": { "type": "string", "description": "Role name" }, "domain": { "type": "string", "description": "Domain scope" }, "priority": { "type": "integer", "description": "Ordinal rank within the org (0 = highest priority)" }, "description": { "type": ["string", "null"] }, "created_at": { "type": "string", "format": "date-time" } }, "required": ["id", "role", "domain", "priority", "created_at"] }, "RoleAssignment": { "type": "object", "properties": { "id": { "type": "integer" }, "user_id": { "type": "string" }, "user_email": { "type": ["string", "null"] }, "role_id": { "type": "integer" }, "role_name": { "type": "string" }, "domain": { "type": "string" } }, "required": ["id", "user_id", "role_id", "role_name", "domain"] }, "RolesListResponse": { "type": "object", "properties": { "definitions": { "type": "array", "items": { "$ref": "#/components/schemas/RoleDefinition" } }, "assignments": { "type": "array", "items": { "$ref": "#/components/schemas/RoleAssignment" } } }, "required": ["definitions", "assignments"] }, "CreateRoleRequest": { "type": "object", "properties": { "role": { "type": "string", "description": "Role name (alphanumeric, hyphens, underscores)" }, "description": { "type": ["string", "null"], "description": "Human-readable description" } }, "required": ["role"] }, "AccessControlSummary": { "type": "object", "properties": { "role_count": { "type": "integer", "description": "Number of role definitions" }, "server_count": { "type": "integer", "description": "Number of server enablements" }, "element_enablements": { "type": "integer", "description": "Number of element enablement overrides" }, "server_enablements": { "type": "integer", "description": "Number of server enablement overrides" } }, "required": ["role_count", "server_count", "element_enablements", "server_enablements"] }, "UpdateApiKeyStatusRequest": { "type": "object", "properties": { "is_active": { "type": "boolean", "description": "New active status for the API key" } }, "required": ["is_active"] }, "UpdateApiKeyStatusResponse": { "type": "object", "properties": { "status": { "type": "string", "default": "success" }, "api_key": { "type": "string", "description": "Masked API key" }, "is_active": { "type": "boolean" } }, "required": ["status", "api_key", "is_active"] }, "UpdateApiKeyRoleRequest": { "type": "object", "properties": { "role": { "type": "string", "description": "New role for the API key (admin, user, owner)" } }, "required": ["role"] }, "UpdateApiKeyRoleResponse": { "type": "object", "properties": { "status": { "type": "string", "default": "success" }, "api_key": { "type": "string", "description": "Masked API key" }, "role": { "type": "string", "description": "New role" } }, "required": ["status", "api_key", "role"] }, "ApprovalRequest": { "type": "object", "description": "A gated approval request derived from a blocked session action.", "properties": { "id": { "type": "integer", "description": "Approval request ID" }, "session_id": { "type": "string", "description": "Session that triggered the approval request" }, "tool_name": { "type": "string", "description": "Name of the tool requesting approval" }, "tool_params": { "type": ["object", "null"], "additionalProperties": true, "description": "Parameters passed to the tool" }, "user_id": { "type": "string" }, "user_email": { "type": ["string", "null"] }, "agent_name": { "type": ["string", "null"] }, "trifecta_flags": { "type": "array", "items": { "type": "string" } }, "risk": { "oneOf": [ { "$ref": "#/components/schemas/RiskInfo" }, { "type": "null" } ] }, "reason": { "type": ["string", "null"], "description": "What held the call: 'trifecta'/'trifecta_prevent' or 'policy_approval'" }, "policy_rule": { "type": ["string", "null"] }, "status": { "type": "string", "description": "Approval status: pending, approved, denied" }, "created_at": { "type": "string", "format": "date-time" } }, "required": ["id", "session_id", "tool_name", "user_id", "trifecta_flags", "status", "created_at"] }, "ApproveAction": { "type": "object", "properties": { "note": { "type": ["string", "null"], "description": "Optional note explaining the approval" } } }, "DenyAction": { "type": "object", "properties": { "note": { "type": ["string", "null"], "description": "Optional note explaining the denial" } } }, "ApprovalRequestPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ApprovalRequest" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total_pages": { "type": "integer" } }, "required": ["items", "total", "page", "per_page", "total_pages"] }, "AgentSummary": { "type": "object", "properties": { "id": { "type": "integer", "description": "Agent primary key" }, "name": { "type": "string", "description": "Unique agent name" }, "agent_id": { "type": "string", "description": "Unique agent identifier in agent:HEX format" }, "agent_type": { "type": ["string", "null"], "description": "Agent type or category" }, "domain": { "type": "string", "description": "Email domain the agent belongs to" }, "archived": { "type": "boolean", "description": "Whether the agent is archived" }, "created_at": { "type": "string", "format": "date-time" } }, "required": ["id", "name", "agent_id", "domain", "archived", "created_at"] }, "AgentDetail": { "allOf": [ { "$ref": "#/components/schemas/AgentSummary" }, { "type": "object", "properties": { "user_id": { "type": "string", "description": "User ID of the agent creator" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the agent was last updated" } }, "required": ["user_id", "updated_at"] } ] }, "CreateAgentRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "Agent name (must be unique per domain)" }, "agent_type": { "type": ["string", "null"], "description": "Optional agent type/category" }, "domain": { "type": ["string", "null"], "description": "Target domain (owner only; must be in owner domain list)" } }, "required": ["name"] }, "AgentSummaryPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AgentSummary" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total_pages": { "type": "integer" } }, "required": ["items", "total", "page", "per_page", "total_pages"] }, "TrifectaSummary": { "type": "object", "properties": { "total_events": { "type": "integer", "description": "Total trifecta events in the time period" }, "blocked": { "type": "integer" }, "pending": { "type": "integer" }, "approved": { "type": "integer" }, "time_period": { "type": "string", "description": "Time period for the summary (e.g. '24h', '7d', '30d')" } }, "required": ["total_events", "blocked", "pending", "approved", "time_period"] }, "TrifectaEvent": { "type": "object", "properties": { "id": { "type": "integer" }, "session_id": { "type": "string" }, "tool_name": { "type": "string" }, "user_id": { "type": "string" }, "user_email": { "type": ["string", "null"] }, "trifecta_flags": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "description": "Event status: blocked, pending, or approved" }, "timestamp": { "type": "string", "format": "date-time" } }, "required": ["id", "session_id", "tool_name", "user_id", "status", "timestamp"] }, "AuditEntry": { "type": "object", "properties": { "id": { "type": "integer" }, "timestamp": { "type": "string", "format": "date-time" }, "user_id": { "type": "string" }, "user_email": { "type": ["string", "null"] }, "domain": { "type": "string" }, "action": { "type": "string", "description": "Action performed (e.g. approve_user, create_role, update_policy)" }, "resource_type": { "type": "string", "description": "Type of resource affected (e.g. user, role, policy, server)" }, "resource_id": { "type": "string" }, "old_value": { "type": ["object", "null"], "additionalProperties": true }, "new_value": { "type": ["object", "null"], "additionalProperties": true }, "request_status": { "type": "string", "description": "HTTP status of the request (e.g. success, error)" } }, "required": ["id", "timestamp", "user_id", "domain", "action", "resource_type", "resource_id", "request_status"] }, "TrifectaEventPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TrifectaEvent" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total_pages": { "type": "integer" } }, "required": ["items", "total", "page", "per_page", "total_pages"] }, "AuditEntryPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AuditEntry" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total_pages": { "type": "integer" } }, "required": ["items", "total", "page", "per_page", "total_pages"] } } } }