sealgate-ai Insights API

openapi: 3.2.0
info:
  title: SealGate Insights API
  description: Open-source MCP security, aggregation, and monitoring. Self-hosted MCP proxy.
  version: 0.19.0
tags:
- name: Insights
paths:
  /api/v1/insights/latest:
    get:
      summary: Get Latest Insights
      description: Get the latest AI-generated security insights snapshot.
      operationId: get_latest_insights_api_v1_insights_latest_get
      security:
      - HTTPBearer: []
      parameters:
      - name: domain
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Org to view (Super-Owner only, read-only)
          title: Domain
        description: Org to view (Super-Owner only, read-only)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsightsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Insights
  /api/v1/insights/refresh:
    post:
      summary: Refresh Insights
      description: Manually trigger an insights refresh.
      operationId: refresh_insights_api_v1_insights_refresh_post
      security:
      - HTTPBearer: []
      parameters:
      - name: domain
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Org to view (Super-Owner only, read-only)
          title: Domain
        description: Org to view (Super-Owner only, read-only)
      - name: Idempotency-Key
        in: header
        required: false
        description: Optional client-generated key that makes this write operation safe to retry. Reusing the same key returns the original response instead of performing the operation a second time. Keys are scoped to the caller and expire after 24 hours.
        schema:
          type: string
          maxLength: 255
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsightsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Insights
  /api/v1/insights/session-security:
    get:
      summary: Get Session Security Insights
      description: Return sessions with trifecta flags created within the rolling window.
      operationId: get_session_security_insights_api_v1_insights_session_security_get
      security:
      - HTTPBearer: []
      parameters:
      - name: domain
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Org to view (Super-Owner only, read-only)
          title: Domain
        description: Org to view (Super-Owner only, read-only)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionSecurityResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Insights
components:
  schemas:
    SessionSecurityResponse:
      properties:
        sessions:
          items:
            $ref: '#/components/schemas/SessionSummary'
          type: array
          title: Sessions
        window_days:
          type: integer
          title: Window Days
        window_start:
          type: string
          title: Window Start
      type: object
      required:
      - sessions
      - window_days
      - window_start
      title: SessionSecurityResponse
    InsightsResponse:
      properties:
        insights:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Insights
          description: List of AI-generated insights
        generated_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Generated At
          description: When insights were generated (ISO 8601)
        next_run_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Run At
          description: Next scheduled generation (ISO 8601)
        refreshing:
          type: boolean
          title: Refreshing
          description: Whether a refresh is in progress
          default: false
        last_error:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Error
          description: Last error message if any
        interval_seconds:
          anyOf:
          - type: number
          - type: 'null'
          title: Interval Seconds
          description: Refresh interval in seconds
      type: object
      title: InsightsResponse
      description: Response for insights endpoints (dynamic structure from InsightService).
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    SessionSummary:
      properties:
        id:
          type: string
          title: Id
          description: Session identifier
        correlation_id:
          type: string
          title: Correlation Id
          description: Correlation ID linking related events
        session_token:
          anyOf:
          - type: string
          - type: 'null'
          title: Session Token
          description: SealGate session token the LLM client holds in context for token-based sessions (from builtin_obtain_session_token); null otherwise
        user_id:
          type: string
          title: User Id
          description: Authenticated user ID
        user_email:
          type: string
          title: User Email
          description: User email address
        agent_name:
          type: string
          title: Agent Name
          description: Name of the AI agent
        agent_type:
          type: string
          title: Agent Type
          description: Type/category of the agent
        created_at:
          type: string
          format: date-time
          title: Created At
          description: Session start timestamp
        last_activity_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Last Activity At
          description: Timestamp of the last tool call activity
        duration_ms:
          anyOf:
          - type: integer
          - type: 'null'
          title: Duration Ms
          description: Total session duration in milliseconds
        tool_call_count:
          type: integer
          title: Tool Call Count
          description: Number of tool calls in this session
        status:
          type: string
          title: Status
          description: Session status (active, completed, error)
        trifecta_flags:
          items:
            type: string
          type: array
          title: Trifecta Flags
          description: Trifecta security flags triggered
        trifecta_disposition:
          type: string
          title: Trifecta Disposition
          description: 'Worst outcome (denied > expired > approved) of any trifecta write gated for approval this session; ''pending'' is a transient in-flight state. One of: none, pending, approved, expired, denied'
          default: none
        trifecta_block_count:
          type: integer
          title: Trifecta Block Count
          description: Number of trifecta writes gated for approval this session
          default: 0
        block_severity:
          type: string
          title: Block Severity
          description: 'Severity of trifecta blocks for dashboard colouring: none, low, medium, high'
          default: none
        acl_level:
          type: string
          title: Acl Level
          description: Highest ACL level (PUBLIC, PRIVATE, SECRET)
          default: PUBLIC
        tool_names:
          items:
            type: string
          type: array
          title: Tool Names
          description: Distinct tool names invoked in this session
      type: object
      required:
      - id
      - correlation_id
      - user_id
      - user_email
      - agent_name
      - agent_type
      - created_at
      - tool_call_count
      - status
      - trifecta_flags
      title: SessionSummary
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
    ClientBearer:
      type: http
      description: Opaque ewc_ client installation credential
      scheme: bearer
    ServiceToken:
      type: http
      description: 'A SealGate service token: `sgt_acct_...` (account token) or `sgt_org_...` (org token). Mint an account token in the dashboard.'
      scheme: bearer
    MCPGatewayOAuth:
      type: oauth2
      description: OAuth 2.1 authorization-code flow (PKCE required) against the SealGate MCP gateway's authorization server. Request only the scopes an agent needs; unrequested scopes are not granted.
      flows:
        authorizationCode:
          authorizationUrl: /oauth/authorize
          tokenUrl: /oauth/token
          refreshUrl: /oauth/token
          scopes:
            mcp: Connect to the MCP gateway and call the tools exposed by your enabled servers. Every call is still evaluated by the policy engine.
            offline_access: Issue a refresh token so the client can renew access without a new browser sign-in.