openapi: 3.0.0
info:
  title: AquilaX AI API Docs
  version: '2.0'
  description: |
    Welcome to the API documentation for AquilaX. Integrate AquilaX for advanced data processing and analytics in your applications. Key features include seamless data ingestion, powerful processing capabilities, analytics tools, real-time updates, and robust security measures. Get started with API keys, explore endpoints, understand formats, and implement error handling.Authorization is required for all end-points, excluding the one under Public Section. To authenticate, a Personal Access Token `PAT` must be included in the request header with the name `X-AX-KEY`. Happy coding!

servers:
  - url: https://aquilax.ai
    description: Cloud Instance

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-AX-KEY  # Define the header name for PAT

  schemas:
    Error:
      type: object
      description: Schema for error responses.
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string

    GenericJSON:
      type: object
      description: |
        JSON Object or Array containing the data in request. 
        Please do your own request to validate the JSON in output, 
        as it may contain different information


    HealthResponse:
      type: object
      description: Schema for health check response.
      properties:
        ID:
          type: string
          example: "95148e14be674e067be644de814de36c"
          description: "random generated request id"
        hostname:
          type: string
          example: "localhost"
          description: "Hostname of the server"
        status:
          type: string
          example: "ok"
          description: " `ok` only if the API Services is healthy"
        timestamp:
          type: integer
          example: 1741492261
          description: "unix timestamp of the request"
        version:
          type: integer
          example: 2
          description: "API Version"

    AppStats:
      type: object
      description: Schema for application statistics.
      properties:
        line_of_codes:
          type: integer
        orgs:
          type: integer
        scans:
          type: integer
        users:
          type: integer
        vulns:
          type: integer

    ScanRequest:
      type: object
      description: Schema for initiating a new scan.
      properties:
        url:
          type: string
          format: uri
          description: The URL of the public Git repository to scan.
        options:
          type: object
          description: Optional parameters for the scan.
          properties:
            depth:
              type: integer
              description: Scan depth level.
            include_submodules:
              type: boolean
              description: Include submodules in the scan.

    ScanResponse:
      type: object
      description: Schema for scan response.
      properties:
        scan_token:
          type: string
        status:
          type: string
        created_at:
          type: string
          format: date-time

    VerifyMe:
      type: object
      description: Schema representing user data.
      properties:
        email:
          type: string
          example: user@example.com
          description: "User Email"
        userData:
          type: string
          description: "Unique User ID"
          example: "xxxxx-82f9-4c65-b1cd-xxxxxxxxx"

    UserData:
      type: object
      description: Schema representing user data.
      properties:
        notification_count:
          type: integer
          example: 0
          description: "User Email"
        user_id:
          type: string
          description: "Unique User ID"
          example: "xxxxx-82f9-4c65-b1cd-xxxxxxxxx"

    Notification:
      type: object
      description: Schema for user notifications.
      properties:
        id:
          type: string
        message:
          type: string
        created_at:
          type: string
          format: date-time

    ActivityLog:
      type: object
      description: Schema for activity logs.
      properties:
        id:
          type: string
        action:
          type: string
        timestamp:
          type: string
          format: date-time

    AccessToken:
      type: object
      description: Schema for access token.
      properties:
        token:
          type: string
        expires_at:
          type: string
          format: date-time

security:
  - ApiKeyAuth: []

tags:
  - name: Health
    description: Endpoints for metrics and health check
  - name: Profile
    description: Endpoints for managing user profiles
  - name: Public Scan
    description: Endpoints for scanning a public git repo
  - name: Admin
    description: Endpoints for AquilaX Worker

paths:
  /api/v2/health:
    get:
      summary: Health
      tags:
        - Health
      description: Check if the API is running
      security: []
      responses:
        '200':
          description: Service is healthy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'

  /api/v2/profile:
    get:
      summary: Profile
      description: Retrieve user data, organizations, notification_count, latest access logs and access tokens
      tags:
        - Profile
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: User data retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserData'

  /api/v2/admin/scans/pending:
    get:
      summary: Get pending scans
      tags:
        - Admin
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Pending scans retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ScanResponse'

  /api/v2/heartbeat/runners:
    get:
      summary: Runner heartbeat endpoint
      tags:
        - Health
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Heartbeat successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string

  /api/v2/ai/securitron:
    post:
      summary: Securitron Bot
      tags:
        - Public Scan
      security:
        - ApiKeyAuth: []
      parameters:
        - name: org
          in: query
          required: true
          description: Organization ID
          schema:
            type: string
        - name: group
          in: query
          required: true
          description: Group ID
          schema:
            type: string
      description: Securitron is built on a series of specialized Small Language Models (SLMs), designed to enhance user experience and streamline interactions within the AquilaX ecosystem. 🚀
      requestBody:
        required: true
        content:
          application/json:
            schema:
                type: object
                description: Data to submit on your request to Securitron
                properties:
                  prompt:
                    type: string
                    description: A user prompt
                    example: "Who am i?"
                    default: "Who am i?"
                  sessione_id:
                    type: string
                    description: A random ID defined from the client, to be used as a sessione_id
                    example: "123"
                    default: "123"
                  stream:
                    type: boolean
                    description: "`true` or `false`, to receive the data in streaming"
                    example: false
                    default: true
      responses:
        '200':
          description: Successful response with a structured text output
          content:
            text/markdown:
              schema:
                type: string
                description: |
                 Since the content type is always set to text/markdown, it should consistently be processed as such. 
                 This applies even if an API call fails with a status code other than 200—the response body will still contain a markdown-formatted message conveying the necessary information to the user. 
                 The only exception is when the content type is set to stream; in that case, the content should still be treated as markdown but delivered in a streaming format. 
                 ### Python code example to read the data in stream
                 ```
                  import requests

                  url = "https://aquilax.ai/api/v2/<your_own_org>/securitron"

                  payload = {
                      "prompt": "what is sql injection?",
                      "group_id": "<your_own_group>",
                      "sessione_id": "<random session id>",
                      "stream": True
                  }

                  headers = {
                      "X-AX-KEY": "",  # Add your API key here
                      "Content-Type": "application/json"
                  }

                  def stream_response(url, payload, headers):
                      """
                      Sends a POST request with streaming enabled and processes the response in real-time.
                      """
                      with requests.post(url, json=payload, headers=headers, stream=True) as response:
                          response.raise_for_status()  # Ensure request was successful

                          for line in response.iter_lines():
                              if line:
                                  decoded_line = line.decode('utf-8')
                                  print(f"Received: {decoded_line}")

                  # Call the function
                  stream_response(url, payload, headers)
                 ```
                example: |
                  Hey Name Surname!  
                  You authenticated via google using `your_email@aquilax.io`. 

  /api/v2/ai/review:
    post:
      summary: Vulnerability Review
      tags:
        - Public Scan
      security:
        - ApiKeyAuth: []
      parameters:
        - name: org
          in: query
          required: true
          description: Organization ID
          schema:
            type: string
      description: |
        Sends vulnerability details and source code to the AI service, which analyzes
        the data and returns a classification with a confidence score.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                code:
                  type: string
                  description: |
                    A code snippet representing the vulnerable logic or affected lines.
                  example: |
                    try {
                      const user = db.getUserById(req.query.id);
                      res.send(user);
                    } catch (err) {
                      res.status(500).send("Error");
                    }
                cwe_id:
                  type: string
                  description: CWE identifier, if applicable.
                  example: CWE-79
                cwe_name:
                  type: string
                  description: Optional name or title of the CWE.
                  example: Cross-Site Scripting
                line:
                  type: string
                  description: Line number(s) where the issue appears.
                  example: "105"
                file:
                  type: string
                  description: Name or path of the file containing the snippet.
                  example: userController.js
      responses:
        '200':
          description: Successful classification result from the AI model.
          content:
            application/json:
              schema:
                type: object
                properties:
                  class:
                    type: string
                    enum: [TRUE_POSITIVE, FALSE_POSITIVE, UNVERIFIED]
                    description: |
                      The AI-determined classification of the vulnerability.
                  confidence:
                    type: number
                    format: float
                    description: Confidence percentage (0–100) of the classification.
                example:
                  class: "TRUE_POSITIVE"
                  confidence: 95.12
        '400':
          description: Invalid request format
        '500':
          description: Internal server error or AI model not configured
        '502':
          description: Failed to reach external AI model

  /api/v2/ai/assistant:
    post:
      summary: Security Assistant
      tags:
        - Public Scan
      security:
        - ApiKeyAuth: []
      parameters:
        - name: org
          in: query
          required: true
          description: Organization ID
          schema:
            type: string
      description: |
        This API forwards the incoming question and vulnerability context to an external AI model assistant
        and streams back the AI's response in real-time (text/event-stream).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                code:
                  type: string
                  description: |
                    A code snippet representing the vulnerable logic or affected lines.
                  example: |
                    try {
                      const user = db.getUserById(req.query.id);
                      res.send(user);
                    } catch (err) {
                      res.status(500).send("Error");
                    }
                cwe_id:
                  type: string
                  description: CWE identifier, if applicable.
                  example: CWE-79
                cwe_name:
                  type: string
                  description: Optional name or title of the CWE.
                  example: Cross-Site Scripting
                line:
                  type: string
                  description: Line number(s) where the issue appears.
                  example: "105"
                file:
                  type: string
                  description: Name or path of the file containing the snippet.
                  example: userController.js
                prompt:
                  type: string
                  description: A question to the Security Assistant
                  example: How to fix this?
                status:
                  type: string
                  description: TRUE POSITIVE, FALSE POSITIVE or UNVERIFIED
                  example: UNVERIFIED
                Reason:
                  type: string
                  description: Reason of how this is identified as vulnerability from the scanner
                  example: SQL Injection in the code
                Remedation:
                  type: string
                  description: User parameters in the Query string
                  example: User parameters in the Query string
      responses:
        '200':
          description: Successful classification result from the AI model in streaming format.
          content:
            application/json:
              schema:
                type: string
        '400':
          description: Invalid request format
        '500':
          description: Internal server error or AI model not configured
        '502':
          description: Failed to reach external AI model

  /api/v2/ai/feedback/{request_id}/{status}:
    get:
      summary: Feedback
      description: |
        Proxies feedback for a specific AI model request for a given Chat message.
      operationId: submitAIFeedback
      tags:
        - AI Feedback
      parameters:
        - name: request_id
          in: path
          required: true
          description: Unique identifier of the AI request to provide feedback for
          schema:
            type: string
            format: uuid
            example: "77e81bbc-3e7f-47b9-87fa-681b5d2f54e6"
        - name: status
          in: path
          required: true
          description: Feedback status for the request
          schema:
            type: string
            enum:
              - "true"
              - "false"
            example: "false"
        - name: org
          in: query
          required: true
          description: Organization identifier
          schema:
            type: string
            example: "65dd3e835a669e3347654200"
        - name: group
          in: query
          required: true
          description: Group identifier
          schema:
            type: string
            example: "67e86d036e9921509f730483"
      responses:
        '200':
          description: Feedback submitted successfully
        '400':
          description: Bad request - Invalid parameters
          content:
            text/plain:
              schema:
                type: string
                example: "A valid organization_id is required in the URL path"
        '401':
          description: Unauthorized - Invalid authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found - Request ID not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            text/plain:
              schema:
                type: string
                example: "Failed to make request to downstream API"
        '502':
          description: Bad gateway - Downstream service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Service unavailable - Downstream service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '504':
          description: Gateway timeout - Downstream service timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/v2/organization/{organization_id}/groups:
    get:
      summary: List of Groups
      description: Returns an array of all groups associated with the given organization ID. 🚀
      tags:
        - Public Scan
      security:
        - ApiKeyAuth: []
      parameters:
        - name: organization_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Group Results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericJSON'
    
    post:
      summary: Create Group
      tags:
        - Public Scan
      security:
        - ApiKeyAuth: []
      parameters:
        - name: organization_id
          in: query
          required: true
          description: Organization ID
          schema:
            type: string
      description: |
        Sends vulnerability details and source code to the AI service, which analyzes
        the data and returns a classification with a confidence score.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Human readable Group Name
                  example: Main
                security_policy:
                  type: object
                  description: |
                    A JSON object representing the security policy configuration for the group.  
                    Includes scanner configurations, frequency of scans, thresholds, and ticketing behavior.

                  properties:
                    frequency:
                      type: string
                      description: Cron expression defining how often to run scans. Use `"none"` for disabled scheduling.
                      example: "none"
                    ignore:
                      type: array
                      items:
                        type: string
                      description: Paths or patterns to ignore during scanning.
                      example: ["test/*", "node_modules/*"]
                    jira_project_key:
                      type: string
                      example: ""
                    notify_on_failure:
                      type: boolean
                      example: true
                    raise_tickets:
                      type: boolean
                      example: false
                    scanners:
                      type: array
                      description: |
                        List of enabled scanners. Each scanner is an object with a key indicating its type 
                        (e.g., `sast`, `secret`, `compliance`) and an `enforced` boolean.
                      items:
                        type: object
                        additionalProperties: true
                        example:
                          sast: true
                          enforced: false
                    tags:
                      type: array
                      items:
                        type: string
                      example: ["all-scanners", "example", "special-project"]
                    testing:
                      type: boolean
                      example: false
                    threshold:
                      type: object
                      properties:
                        HIGH:
                          type: integer
                          example: 30
                        MEDIUM:
                          type: integer
                          example: 100
                        LOW:
                          type: integer
                          example: 99999
                        total:
                          type: integer
                          example: 100
                    ticket_body:
                      type: string
                      example: "Was found this {{vuln}} on this file {{file}}"
                    ticket_integration:
                      type: string
                      example: ""
                    ticket_title:
                      type: string
                      example: "AquilaX - {{vuln}}"
      responses:
        '200':
          description: Invalid request format
        '500':
          description: Internal server error or AI model not configured
        '502':
          description: Failed to reach external AI model


  /api/v2/organization/{organization_id}/integrations:
    get:
      summary: Integrations
      description: Returns an array of all integrations associated with the given organization ID. 🚀
      tags:
        - Public Scan
      security:
        - ApiKeyAuth: []
      parameters:
        - name: organization_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Group Results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericJSON'

  /api/v2/report:
    get:
      summary: Summary Report
      description: Returns an JSON documentation with the number of projects, scans, line of code and files, along with the vulnerabilites
      tags:
        - Public Scan
      security:
        - ApiKeyAuth: []
      parameters:
        - name: org
          in: query
          required: true
          schema:
            type: string
        - name: group
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Group Results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericJSON'

  /api/v2/report/scans:
    get:
      summary: Scans analytics
      description: Returns an JSON documentation with the number of scans, the time are created and their status (the API my limit the quantity of data for performance reasons)
      tags:
        - Public Scan
      security:
        - ApiKeyAuth: []
      parameters:
        - name: org
          in: query
          required: true
          schema:
            type: string
        - name: group
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Group Results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericJSON'

  /api/v2/projects:
    get:
      summary: List of Projects
      description: Returns an JSON Array of all projects for the given group ID
      tags:
        - Public Scan
      security:
        - ApiKeyAuth: []
      parameters:
        - name: org
          in: query
          required: true
          description: Organization ID
          schema:
            type: string
        - name: group
          in: query
          required: true
          description: Group ID
          schema:
            type: string
      responses:
        '200':
          description: Results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericJSON'

  /api/v2/project/{project_id}:
    get:
      summary: List of Scans
      description: Return and array of all scan for the given project ID
      tags:
        - Public Scan
      security:
        - ApiKeyAuth: []
      parameters:
        - name: org
          in: query
          required: true
          schema:
            type: string
        - name: group
          in: query
          required: true
          schema:
            type: string
        - name: project_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericJSON'
    delete:
      summary: Delete a Project
      description: Delete a project and its related scans. This is a hard delete
      tags:
        - Public Scan
      security:
        - ApiKeyAuth: []
      parameters:
        - name: org
          in: query
          required: true
          schema:
            type: string
        - name: group
          in: query
          required: true
          schema:
            type: string
        - name: project_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericJSON'

  /api/v2/organization/{organization_id}/group/{group_id}:
    delete:
      summary: Delete a Group
      description: Delete a group and its related projects and scans. This is a hard delete
      tags:
        - Public Scan
      security:
        - ApiKeyAuth: []
      parameters:
        - name: organization_id
          in: path
          required: true
          schema:
            type: string
        - name: group_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericJSON'

  /api/v2/scan:
    post:
      summary: Start a Scan
      tags:
        - Public Scan
      security:
        - ApiKeyAuth: []
      parameters:
        - name: org
          in: query
          required: true
          schema:
            type: string
            default: "your_own_org"
        - name: group
          in: query
          required: true
          schema:
            type: string
            default: ""
      description: Start a new source code scan based on a git code base 🚀
      requestBody:
        required: true
        content:
          application/json:
            schema:
                type: object
                description: Data to submit on your request to Securitron
                properties:
                  git_uri:
                    type: string
                    description: Git URL to scan
                    example: "https://github.com/AquilaX-AI/vulnapp-python"
                  branch:
                    type: string
                    description: Git Branch to Scan, if not set then `main` will be used
                    example: "main"
                    default: "main"
      responses:
        '200':
          description: Successful response with a structured text output
          content:
            text/markdown:
              schema:
                type: object
                properties:
                  scan_id:
                    type: string
                    description: Scan ID of the new Scan
                    example: "67e9f3205357d4a0178efde6"

  /api/v2/scan/{scan_id}:
    get:
      summary: Get Scan Results
      tags:
        - Public Scan
      security:
        - ApiKeyAuth: []
      parameters:
        - name: org
          in: query
          required: true
          schema:
            type: string
            default: "your_own_org"
        - name: group
          in: query
          required: true
          schema:
            type: string
            default: ""
        - name: scan_id
          in: path
          required: true
          schema:
            type: string
            default: ""
      description: Get results of a scan based on Scan ID
      responses:
        '200':
          description: Results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericJSON'

  /api/v2/vulns:
    get:
      summary: List of Vulnerabilites
      tags:
        - Public Scan
      security:
        - ApiKeyAuth: []
      parameters:
        - name: org
          in: query
          required: true
          schema:
            type: string
            default: "your_own_org"
        - name: group
          in: query
          required: true
          schema:
            type: string
            default: ""
      description: Return an array of all scans with the associated vulnerabilites
      responses:
        '200':
          description: Results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericJSON'

  /api/v2/scan/{scan_id}/finding/{finding_id}:
    put:
      summary: Update Vulnerability
      description: |
        Update specific fields (status, reason, remediation, severity, impact, likelihood, confidence) of a single finding inside a scan result.  
        Only the fields provided in the request body will be updated. Fields omitted will remain unchanged.
      tags:
        - Public Scan
      security:
        - ApiKeyAuth: []
      parameters:
        - name: org
          in: query
          required: true
          schema:
            type: string
          description: Organization ID
        - name: group
          in: query
          required: true
          schema:
            type: string
          description: Group ID
        - name: scan_id
          in: path
          required: true
          schema:
            type: string
          description: The ID of the scan document
        - name: finding_id
          in: path
          required: true
          schema:
            type: string
          description: The ID of the finding to update
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Fields to update in the finding
              properties:
                status:
                  type: string
                  description: Status of the finding (e.g., True Positive, False Positive, Unverified)
                reason:
                  type: string
                  description: Reason for classification
                remediation:
                  type: string
                  description: Suggested remediation
                severity:
                  type: string
                  description: Severity level
                impact:
                  type: string
                  description: Potential impact
                likelihood:
                  type: string
                  description: Likelihood of exploit
                confidence:
                  type: string
                  description: Confidence in detection
              example:
                status: "TRUE POSITIVE"
                reason: "Confirmed based on business logic"
                remediation: "Input sanitization applied"
                severity: "HIGH"
                impact: "Sensitive data exposure"
                likelihood: "MEDIUM"
                confidence: "MEDIUM"
      responses:
        '200':
          description: Finding updated successfully
        '400':
          description: Invalid request or missing required fields
        '404':
          description: Scan or finding not found
        '500':
          description: Internal server error