openapi: 3.0.3
info:
  title: Lineaje Fix Plan Workflow API
  version: 1.0.0
  description: |
    Workflow documentation for authentication, project listing,
    and fix plan request APIs.

servers:
  - url: https://lineaje-identity-service.v2.prod.veedna.com
    description: Default server for authentication requests

tags:
  - name: Authentication
    description: Authentication endpoints
  - name: Projects
    description: Project listing endpoints
  - name: Fix Plan
    description: Fix plan request endpoints

paths:
  /lineajeidentity/api/v1/login:
    post:
      tags:
        - Authentication
      summary: Authenticate user
      description: Authenticates with username and password and returns a bearer token.
      operationId: authenticationLogin
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
            example:
              username: "<username>"
              password: "<password>"
      responses:
        '200':
          description: Authentication successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
              example:
                accessToken: "<token>"
                tokenType: "Bearer"
                expiresIn: 86400
                scope: "openid profile email"

  /scim/api/v2/projects/:
    get:
      tags:
        - Projects
      summary: List projects
      description: Returns all projects and their associated SBOM IDs.
      operationId: projectsList
      servers:
        - url: https://scim-service.v2.prod.veedna.com
          description: SCIM Service
      security:
        - bearerAuth: []
      parameters:
        - name: page
          in: query
          required: false
          description: Page index
          schema:
            type: integer
            example: 0
        - name: size
          in: query
          required: false
          description: Number of results to return
          schema:
            type: integer
            example: 2000
        - name: timestamp
          in: query
          required: false
          description: Timestamp parameter used by the API
          schema:
            type: integer
            example: 120
      responses:
        '200':
          description: Project list returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListProjectsResponse'
              example:
                results:
                  projects:
                    - projectId: 4780694
                      sbomId: "<sbom_id>"
                      jobStatus: "Ready for review"
                total_count: 17
        '401':
          description: Unauthorized

  /api/v1/explain:
    post:
      tags:
        - Fix Plan
      summary: Request fix plan
      description: |
        Requests a fix plan for a given SBOM. The client should poll this endpoint
        until meta_data.overall_status becomes "available".
      operationId: fixPlanRequest
      servers:
        - url: https://lineaje-gpt-service.v2.prod.veedna.com
          description: GPT Service
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FixPlanRequest'
            example:
              query: "Recommend a fix plan"
              sbom_id: "<sbom_id>"
      responses:
        '200':
          description: Fix plan response returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FixPlanResponse'
              example:
                meta_data:
                  plan_details:
                    - type: premium
                      vuln_fixed:
                        - CVE-2023-44487
                      efforts: high
                      is_compatible: true
                  overall_status: available
        '401':
          description: Unauthorized

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    LoginRequest:
      type: object
      required:
        - username
        - password
      properties:
        username:
          type: string
          description: Lineaje username
        password:
          type: string
          format: password
          description: Lineaje password

    LoginResponse:
      type: object
      required:
        - accessToken
        - tokenType
        - expiresIn
        - scope
      properties:
        accessToken:
          type: string
          description: Access token to be used in Authorization header
        tokenType:
          type: string
          example: Bearer
        expiresIn:
          type: integer
          description: Token expiration time in seconds
          example: 86400
        scope:
          type: string
          example: "openid profile email"

    Project:
      type: object
      properties:
        projectId:
          type: integer
          example: 4780694
        sbomId:
          type: string
          description: SBOM identifier for the project
        jobStatus:
          type: string
          example: "Ready for review"

    ListProjectsResponse:
      type: object
      properties:
        results:
          type: object
          properties:
            projects:
              type: array
              items:
                $ref: '#/components/schemas/Project'
        total_count:
          type: integer
          example: 17

    FixPlanRequest:
      type: object
      required:
        - query
        - sbom_id
      properties:
        query:
          type: string
          example: "Recommend a fix plan"
        sbom_id:
          type: string
          description: SBOM identifier captured from the projects API

    PlanDetail:
      type: object
      properties:
        type:
          type: string
          example: premium
        vuln_fixed:
          type: array
          items:
            type: string
          example:
            - CVE-2023-44487
        efforts:
          type: string
          example: high
        is_compatible:
          type: boolean
          example: true

    FixPlanMetaData:
      type: object
      properties:
        plan_details:
          type: array
          items:
            $ref: '#/components/schemas/PlanDetail'
        overall_status:
          type: string
          description: Poll until this becomes available
          example: available

    FixPlanResponse:
      type: object
      properties:
        meta_data:
          $ref: '#/components/schemas/FixPlanMetaData'