openapi: 3.2.0
info:
  title: Dependency Track Vex API
  version: 1.0.0
  contact:
    name: The Dependency-Track Authors
    url: https://github.com/DependencyTrack/dependency-track
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  description: 'Operations tagged vex across 2 of this provider''s published API definitions: dependency-track-openapi-v1.yaml, dependency-track-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: /api
tags:
- name: vex
paths:
  /v1/vex:
    post:
      description: 'Expects CycloneDX and a valid project UUID. If a UUID is not specified,

        then the projectName and projectVersion must be specified.


        The VEX will be validated against the CycloneDX schema. If schema validation fails,

        a response with problem details in RFC 9457 format will be returned. In this case,

        the response''s content type will be application/problem+json.


        Requires permission VULNERABILITY_ANALYSIS or VULNERABILITY_ANALYSIS_UPDATE'
      operationId: uploadVex_1
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                project:
                  type: string
                projectName:
                  type: string
                projectVersion:
                  type: string
                vex:
                  type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BomUploadResponse'
          description: Token to be used for checking VEX processing progress
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/InvalidBomProblemDetails'
          description: Invalid VEX
        '401':
          description: Unauthorized
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
          description: Access to the requested project is forbidden
        '404':
          description: The project could not be found
        '413':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
          description: The uploaded document is too large
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Upload a supported VEX document
      tags:
      - vex
    put:
      description: 'Expects CycloneDX and a valid project UUID. If a UUID is not specified,

        then the projectName and projectVersion must be specified.


        The VEX will be validated against the CycloneDX schema. If schema validation fails,

        a response with problem details in RFC 9457 format will be returned. In this case,

        the response''s content type will be application/problem+json.


        The maximum allowed length of the vex value is 20''000''000 characters.

        When uploading large VEX files, the POST endpoint is preferred,

        as it does not have this limit.


        Requires permission VULNERABILITY_ANALYSIS or VULNERABILITY_ANALYSIS_UPDATE'
      operationId: uploadVex
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VexSubmitRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BomUploadResponse'
          description: Token to be used for checking VEX processing progress
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/InvalidBomProblemDetails'
          description: Invalid VEX
        '401':
          description: Unauthorized
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
          description: Access to the requested project is forbidden
        '404':
          description: The project could not be found
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Upload a supported VEX document
      tags:
      - vex
    servers:
    - url: /api
  /v1/vex/cyclonedx/project/{uuid}:
    get:
      description: Requires permission VULNERABILITY_ANALYSIS or VULNERABILITY_ANALYSIS_READ
      operationId: exportProjectAsCycloneDx_1
      parameters:
      - description: The UUID of the project to export
        in: path
        name: uuid
        required: true
        schema:
          type: string
          format: uuid
      - description: Force the resulting VEX to be downloaded as a file (defaults to 'false')
        in: query
        name: download
        schema:
          type: boolean
      - description: 'The CycloneDX Spec variant exported (defaults to: ''1.5'')'
        in: query
        name: version
        schema:
          type: string
      responses:
        '200':
          content:
            application/octet-stream:
              schema:
                type: string
            application/vnd.cyclonedx+json:
              schema:
                type: string
          description: A VEX for a project in CycloneDX format
        '401':
          description: Unauthorized
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
          description: Access to the requested project is forbidden
        '404':
          description: The project could not be found
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Returns a VEX for a project in CycloneDX format
      tags:
      - vex
    servers:
    - url: /api
components:
  schemas:
    BomUploadResponse:
      type: object
      properties:
        projectUuid:
          type: string
          format: uuid
          description: UUID of the project the BOM was uploaded for
        token:
          type: string
          format: uuid
          description: Token used to check task progress
      required:
      - projectUuid
      - token
    ProblemDetails:
      type: object
      description: An RFC 9457 problem object
      properties:
        detail:
          type: string
          description: Human-readable explanation specific to this occurrence of the problem
          example: Example detail
        instance:
          type: string
          format: uri
          description: Reference URI that identifies the specific occurrence of the problem
          example: https://api.example.org/foo/bar/example-instance
        status:
          type: integer
          format: int32
          description: HTTP status code generated by the origin server for this occurrence of the problem
          example: 400
        title:
          type: string
          description: Short, human-readable summary of the problem type
          example: Example title
        type:
          type: string
          format: uri
          description: A URI reference that identifies the problem type
          example: https://api.example.org/foo/bar/example-problem
      required:
      - detail
      - status
      - title
    VexSubmitRequest:
      type: object
      properties:
        project:
          type: string
          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
        projectName:
          type: string
          minLength: 1
          pattern: ^[\p{IsWhite_Space}\p{L}\p{M}\p{S}\p{N}\p{P}]*$
        projectVersion:
          type: string
          minLength: 1
          pattern: ^[\p{IsWhite_Space}\p{L}\p{M}\p{S}\p{N}\p{P}]*$
        vex:
          type: string
          pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$
      required:
      - project
      - projectName
      - projectVersion
      - vex
    InvalidBomProblemDetails:
      type: object
      allOf:
      - $ref: '#/components/schemas/ProblemDetails'
      - type: object
        properties:
          errors:
            type: array
            description: Errors identified during schema validation
            items:
              type: string
              description: Errors identified during schema validation
      required:
      - detail
      - status
      - title
  securitySchemes:
    ApiKeyAuth:
      description: Authentication via API key.
      in: header
      name: X-Api-Key
      type: apiKey
    BearerAuth:
      bearerFormat: Opaque
      description: 'Authentication via opaque server-issued session token.

        Tokens are obtained from `POST /api/v1/user/login` or

        `POST /api/v1/user/oidc/login`.'
      scheme: bearer
      type: http
x-refined-from:
- dependency-track-openapi-v1.yaml
- dependency-track-openapi.yml