openapi: 3.1.0
info:
  title: Capsule Security AI Agent Management Platform
  description: >
    The Capsule Security platform provides comprehensive AI agent security
    management with advanced monitoring,

    risk assessment, and compliance capabilities. This API enables integration
    with multiple AI agent platforms

    and provides GraphQL endpoints for flexible data querying.
  version: 1.0.0
  contact:
    name: Capsule Security Support
    email: support@capsule.security
  license:
    name: Proprietary
    url: https://capsule.security/license
servers:
  - url: https://api.capsule.security/api/v1
    description: Production API server
  - url: https://staging.api.capsule.security/api/v1
    description: Staging API server
security:
  - cookieAuth: []
  - bearerAuth: []
paths:
  /auth/login:
    get:
      summary: Initiate authentication flow
      operationId: login
      tags:
        - Authentication
      parameters:
        - name: redirect_url
          in: query
          required: true
          schema:
            type: string
            format: uri
          description: URL to redirect after successful authentication
      responses:
        '302':
          description: Redirect to Auth0 or SSO provider
          headers:
            Location:
              schema:
                type: string
                format: uri
              description: Auth provider URL
  /auth/logout:
    get:
      summary: Logout current user
      operationId: logout
      tags:
        - Authentication
      responses:
        '302':
          description: Redirect after logout
          headers:
            Location:
              schema:
                type: string
                format: uri
  /auth/session:
    get:
      summary: Get current session information
      operationId: getSession
      tags:
        - Authentication
      responses:
        '200':
          description: Current user session
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionInfo'
        '401':
          description: Not authenticated
  /graphql:
    post:
      summary: GraphQL endpoint
      operationId: graphql
      tags:
        - GraphQL
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - query
              properties:
                query:
                  type: string
                  description: GraphQL query string
                variables:
                  type: object
                  description: Query variables
                operationName:
                  type: string
                  description: Operation name for multi-operation documents
      responses:
        '200':
          description: GraphQL response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                  errors:
                    type: array
                    items:
                      type: object
components:
  schemas:
    SessionInfo:
      type: object
      required:
        - userId
        - email
        - name
        - tenants
        - tenantIds
        - organization
      properties:
        userId:
          type: string
          description: Unique user identifier
        email:
          type: string
          format: email
          description: User email address
        name:
          type: string
          description: User full name
        tenants:
          type: object
          additionalProperties:
            type: object
            properties:
              roles:
                type: array
                items:
                  type: string
          description: Tenant access and roles mapping
        tenantIds:
          type: array
          items:
            type: string
          description: List of tenant IDs user has access to
        organization:
          type: object
          properties:
            id:
              type: string
            name:
              type: string
          description: User's organization details
    Agent:
      type: object
      properties:
        id:
          type: string
          description: Unique agent identifier
          readOnly: true
        externalId:
          type: string
          description: External platform agent ID
        platform:
          $ref: '#/components/schemas/Platform'
        name:
          type: string
          description: Agent name
        environment:
          $ref: '#/components/schemas/Environment'
        owner:
          $ref: '#/components/schemas/Owner'
        accessibility:
          $ref: '#/components/schemas/AgentAccessibility'
        description:
          type: string
          description: Agent description
        tools:
          type: array
          items:
            $ref: '#/components/schemas/Tool'
        nodes:
          type: array
          items:
            $ref: '#/components/schemas/Node'
        edges:
          type: array
          items:
            $ref: '#/components/schemas/Edge'
        highestPolicySeverity:
          $ref: '#/components/schemas/Issue'
        usage:
          $ref: '#/components/schemas/Usage'
        createdAt:
          type: string
          format: date-time
          readOnly: true
    Platform:
      type: object
      properties:
        id:
          type: string
        type:
          $ref: '#/components/schemas/PlatformType'
        name:
          type: string
        enabled:
          type: boolean
        configurationRequired:
          type: boolean
    Environment:
      type: object
      properties:
        id:
          type: string
        externalId:
          type: string
        name:
          type: string
          example: Production
    Owner:
      type: object
      properties:
        id:
          type: string
        externalId:
          type: string
        name:
          type: string
        email:
          type: string
          format: email
        jobTitle:
          type: string
    Tool:
      type: object
      properties:
        id:
          type: string
        externalId:
          type: string
        type:
          type: string
          description: Tool type identifier
        name:
          type: string
        enabled:
          type: boolean
        issues:
          type: array
          items:
            $ref: '#/components/schemas/Issue'
    Node:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        issues:
          type: array
          items:
            $ref: '#/components/schemas/Issue'
    Edge:
      type: object
      properties:
        id:
          type: string
        sourceId:
          type: string
        targetId:
          type: string
        direction:
          $ref: '#/components/schemas/EdgeDirection'
    Issue:
      type: object
      properties:
        id:
          type: string
        severity:
          $ref: '#/components/schemas/PolicySeverity'
        category:
          $ref: '#/components/schemas/IssueCategory'
        status:
          $ref: '#/components/schemas/IssueStatus'
        title:
          type: string
        description:
          type: string
        recommendation:
          type: string
        createdAt:
          type: string
          format: date-time
        resolvedAt:
          type: string
          format: date-time
    Usage:
      type: object
      properties:
        sessionCount:
          type: integer
          description: Number of agent sessions
        invocationCount:
          type: integer
          description: Total invocation count
        lastUsed:
          type: string
          format: date-time
    IntegrationConfig:
      type: object
      required:
        - platform
        - credentials
      properties:
        platform:
          $ref: '#/components/schemas/PlatformType'
        credentials:
          type: object
          description: Platform-specific credentials
        settings:
          type: object
          description: Integration settings
          properties:
            syncInterval:
              type: integer
              description: Sync interval in minutes
            autoDiscover:
              type: boolean
              description: Auto-discover agents
    Integration:
      type: object
      properties:
        id:
          type: string
        platform:
          $ref: '#/components/schemas/PlatformType'
        status:
          type: string
          enum:
            - connected
            - disconnected
            - error
        connectedAt:
          type: string
          format: date-time
        lastSync:
          type: string
          format: date-time
        agentCount:
          type: integer
    PolicySeverity:
      type: string
      enum:
        - LOW
        - MEDIUM
        - HIGH
        - CRITICAL
    IssueCategory:
      type: string
      enum:
        - SUPPLY_CHAIN
        - DATA
        - COMPLIANCE
        - INTEGRITY
        - ACCESS
        - MISC
    IssueStatus:
      type: string
      enum:
        - OPEN
        - RESOLVED
        - IGNORED
    AgentAccessibility:
      type: string
      enum:
        - PUBLIC
        - TENANT
        - LIMITED
    EdgeDirection:
      type: string
      enum:
        - ATOB
        - BTOA
        - BOTH
    PlatformType:
      type: string
      enum:
        - COPILOTSTUDIO
        - POWERAUTOMATE
        - AGENTFORCE
        - SERVICENOW
        - AGENTSPACE
        - AWSBEDROCK
        - AZUREAI
        - GCPVERTEXAI
        - ZAPIER
        - UIPATH
        - N8N
        - DATABRICKS
        - SAP
        - BOX
        - WORKATO
    Problem:
      type: object
      properties:
        type:
          type: string
          format: uri
          description: A URI reference that identifies the problem type.
          example: https://api.capsule.security/problems/invalid-request
        title:
          type: string
          description: A short, human-readable summary of the problem type.
          example: Invalid Request
        status:
          type: integer
          description: The HTTP status code.
          example: 400
        detail:
          type: string
          description: >-
            A human-readable explanation specific to this occurrence of the
            problem.
          example: The request payload is not valid according to the schema.
        instance:
          type: string
          format: uri
          description: >-
            A URI reference that identifies the specific occurrence of the
            problem.
          example: /problems/invalid-request/1234
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT Bearer token for API access
    cookieAuth:
      type: apiKey
      in: cookie
      name: session
      description: Session cookie authentication
