Checkmarx Scans API

openapi: 3.1.0
info:
  title: Checkmarx One Applications Scans API
  description: Unified REST API for the Checkmarx One cloud-native application security platform, providing consolidated access to SAST, SCA, KICS, and other security scanning capabilities through a single API with project management, scan orchestration, and results retrieval.
  version: '1.0'
  contact:
    name: Checkmarx Support
    url: https://support.checkmarx.com/
  termsOfService: https://checkmarx.com/terms-of-use/
servers:
- url: https://ast.checkmarx.net/api
  description: Checkmarx One (US)
- url: https://eu.ast.checkmarx.net/api
  description: Checkmarx One (EU)
security:
- bearerAuth: []
tags:
- name: Scans
  description: Trigger, monitor, and manage security scans
paths:
  /scans:
    get:
      operationId: listScans
      summary: Checkmarx List scans
      description: Retrieve scans with optional filtering by project, status, and scan type.
      tags:
      - Scans
      parameters:
      - name: offset
        in: query
        description: Pagination offset
        schema:
          type: integer
          default: 0
      - name: limit
        in: query
        description: Number of results to return
        schema:
          type: integer
          default: 20
      - name: project-id
        in: query
        description: Filter by project ID
        schema:
          type: string
          format: uuid
      - name: statuses
        in: query
        description: Filter by scan statuses (comma-separated)
        schema:
          type: string
      - name: sort
        in: query
        description: Sort field and direction
        schema:
          type: string
          example: -created_at
      responses:
        '200':
          description: List of scans
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScanListResponse'
        '401':
          description: Unauthorized
    post:
      operationId: createScan
      summary: Checkmarx Create a new scan
      description: Initiate a new security scan for a project. The scan can include SAST, SCA, KICS, and other scan types based on project configuration.
      tags:
      - Scans
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateScanRequest'
      responses:
        '201':
          description: Scan created and queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Scan'
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
  /scans/{scanId}:
    get:
      operationId: getScan
      summary: Checkmarx Get scan details
      description: Retrieve details and status of a specific scan.
      tags:
      - Scans
      parameters:
      - $ref: '#/components/parameters/scanId'
      responses:
        '200':
          description: Scan details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Scan'
        '401':
          description: Unauthorized
        '404':
          description: Scan not found
    delete:
      operationId: cancelScan
      summary: Checkmarx Cancel a scan
      description: Cancel a running or queued scan.
      tags:
      - Scans
      parameters:
      - $ref: '#/components/parameters/scanId'
      responses:
        '204':
          description: Scan canceled
        '401':
          description: Unauthorized
        '404':
          description: Scan not found
  /sast/scans:
    get:
      operationId: listScans
      summary: Checkmarx List all scans
      description: Retrieve a list of all SAST scans, with optional filtering by project, scan status, and date range.
      tags:
      - Scans
      parameters:
      - name: projectId
        in: query
        description: Filter scans by project ID
        schema:
          type: integer
      - name: scanStatus
        in: query
        description: Filter by scan status
        schema:
          type: string
          enum:
          - New
          - PreScan
          - Queued
          - Scanning
          - PostScan
          - Finished
          - Canceled
          - Failed
          - SourcePullingAndDeployment
          - None
      - name: last
        in: query
        description: Number of most recent scans to return
        schema:
          type: integer
      responses:
        '200':
          description: List of scans
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Scan_2'
        '401':
          description: Unauthorized
    post:
      operationId: createScan
      summary: Checkmarx Create a new scan
      description: Initiate a new SAST scan for a project. The scan will be queued and executed based on engine availability.
      tags:
      - Scans
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateScanRequest_2'
      responses:
        '201':
          description: Scan created and queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Scan_2'
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
  /sast/scans/{scanId}:
    get:
      operationId: getScan
      summary: Checkmarx Get scan details
      description: Retrieve details of a specific scan by ID.
      tags:
      - Scans
      parameters:
      - $ref: '#/components/parameters/scanId_2'
      responses:
        '200':
          description: Scan details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Scan_2'
        '401':
          description: Unauthorized
        '404':
          description: Scan not found
    patch:
      operationId: updateScanStatus
      summary: Checkmarx Update scan status
      description: Update the status of a scan, such as canceling a running scan.
      tags:
      - Scans
      parameters:
      - $ref: '#/components/parameters/scanId_2'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                  enum:
                  - Canceled
      responses:
        '200':
          description: Scan status updated
        '401':
          description: Unauthorized
        '404':
          description: Scan not found
  /risk-management/scans:
    get:
      operationId: listScans
      summary: Checkmarx List scans
      description: Retrieve a list of SCA scans with optional filtering by project ID.
      tags:
      - Scans
      parameters:
      - name: projectId
        in: query
        description: Filter by project ID
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: List of scans
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Scan_3'
        '401':
          description: Unauthorized
    post:
      operationId: createScan
      summary: Checkmarx Trigger a new scan
      description: Initiate a new SCA scan for a project by uploading a source archive or pointing to a repository.
      tags:
      - Scans
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateScanRequest_3'
      responses:
        '201':
          description: Scan created and queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Scan_3'
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
  /risk-management/scans/{scanId}:
    get:
      operationId: getScan
      summary: Checkmarx Get scan details
      description: Retrieve details and status of a specific SCA scan.
      tags:
      - Scans
      parameters:
      - $ref: '#/components/parameters/scanId'
      responses:
        '200':
          description: Scan details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Scan_3'
        '401':
          description: Unauthorized
        '404':
          description: Scan not found
components:
  schemas:
    ScanResultsStatistics:
      type: object
      properties:
        highSeverity:
          type: integer
          description: Number of high severity vulnerabilities
        mediumSeverity:
          type: integer
          description: Number of medium severity vulnerabilities
        lowSeverity:
          type: integer
          description: Number of low severity vulnerabilities
        infoSeverity:
          type: integer
          description: Number of informational findings
        statisticsCalculationDate:
          type: string
          format: date-time
          description: When the statistics were calculated
    CreateScanRequest:
      type: object
      required:
      - project
      - type
      - handler
      properties:
        project:
          type: object
          required:
          - id
          properties:
            id:
              type: string
              format: uuid
              description: Project ID to scan
        type:
          type: string
          enum:
          - git
          - upload
          description: Source type
        handler:
          type: object
          properties:
            repoUrl:
              type: string
              description: Git repository URL (for git type)
            branch:
              type: string
              description: Branch to scan (for git type)
            uploadUrl:
              type: string
              description: Pre-signed upload URL (for upload type)
        config:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                - sast
                - sca
                - kics
                - apisec
              value:
                type: object
                additionalProperties: true
          description: Per-engine scan configuration
        tags:
          type: object
          additionalProperties:
            type: string
    CreateScanRequest_3:
      type: object
      required:
      - projectId
      properties:
        projectId:
          type: string
          format: uuid
          description: Project to scan
        sourceType:
          type: string
          enum:
          - Upload
          - RemoteRepository
          description: Source code input method
    ScanListResponse:
      type: object
      properties:
        totalCount:
          type: integer
          description: Total number of scans
        filteredTotalCount:
          type: integer
          description: Total count after filtering
        scans:
          type: array
          items:
            $ref: '#/components/schemas/Scan'
    Scan_2:
      type: object
      properties:
        id:
          type: integer
          description: Scan unique identifier
        project:
          type: object
          properties:
            id:
              type: integer
              description: Project ID
            name:
              type: string
              description: Project name
        status:
          type: object
          properties:
            id:
              type: integer
              description: Status ID
            name:
              type: string
              description: Status name
              enum:
              - New
              - PreScan
              - Queued
              - Scanning
              - PostScan
              - Finished
              - Canceled
              - Failed
              - SourcePullingAndDeployment
              - None
        scanType:
          type: string
          description: Type of scan
          enum:
          - Incremental
          - Full
        comment:
          type: string
          description: Scan comment
        dateAndTime:
          type: object
          properties:
            startedOn:
              type: string
              format: date-time
              description: Scan start time
            finishedOn:
              type: string
              format: date-time
              description: Scan finish time
            engineStartedOn:
              type: string
              format: date-time
              description: Engine processing start time
            engineFinishedOn:
              type: string
              format: date-time
              description: Engine processing finish time
        resultsStatistics:
          $ref: '#/components/schemas/ScanResultsStatistics'
    ScanStatusDetail:
      type: object
      properties:
        name:
          type: string
          description: Engine name
        status:
          type: string
          description: Engine-specific scan status
        details:
          type: string
          description: Status details message
    Scan_3:
      type: object
      properties:
        scanId:
          type: string
          format: uuid
          description: Scan unique identifier
        projectId:
          type: string
          format: uuid
          description: Associated project ID
        status:
          type: string
          enum:
          - Queued
          - Scanning
          - Done
          - Failed
          - Canceled
          description: Current scan status
        createdOn:
          type: string
          format: date-time
          description: Scan creation timestamp
        updatedOn:
          type: string
          format: date-time
          description: Last update timestamp
        origin:
          type: string
          description: Scan trigger origin
          enum:
          - API
          - CLI
          - Plugin
          - Upload
        riskReportId:
          type: string
          format: uuid
          description: Associated risk report ID
    CreateScanRequest_2:
      type: object
      required:
      - projectId
      properties:
        projectId:
          type: integer
          description: Project to scan
        isIncremental:
          type: boolean
          description: Whether to run an incremental scan
          default: false
        isPublic:
          type: boolean
          description: Whether the scan results are public
          default: true
        forceScan:
          type: boolean
          description: Force scan even if no code changes
          default: false
        comment:
          type: string
          description: Comment for the scan
    Scan:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Scan unique identifier
        status:
          type: string
          enum:
          - Queued
          - Running
          - Completed
          - Partial
          - Failed
          - Canceled
          description: Overall scan status
        statusDetails:
          type: array
          items:
            $ref: '#/components/schemas/ScanStatusDetail'
          description: Per-engine scan status
        projectId:
          type: string
          format: uuid
          description: Associated project ID
        projectName:
          type: string
          description: Associated project name
        branch:
          type: string
          description: Source branch scanned
        engines:
          type: array
          items:
            type: string
            enum:
            - sast
            - sca
            - kics
            - apisec
          description: Scan engines used
        sourceType:
          type: string
          description: Source origin type
        sourceOrigin:
          type: string
          description: Source origin detail
        initiator:
          type: string
          description: User or system that initiated the scan
        tags:
          type: object
          additionalProperties:
            type: string
        createdAt:
          type: string
          format: date-time
          description: Scan creation timestamp
        updatedAt:
          type: string
          format: date-time
          description: Last update timestamp
  parameters:
    scanId:
      name: scanId
      in: path
      required: true
      description: Scan unique identifier
      schema:
        type: string
        format: uuid
    scanId_2:
      name: scanId
      in: path
      required: true
      description: Scan unique identifier
      schema:
        type: integer
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth 2.0 bearer token obtained via client credentials from the Checkmarx One IAM service
externalDocs:
  description: Checkmarx One API Documentation
  url: https://checkmarx.com/resource/documents/en/34965-128036-checkmarx-one-api.html