Dependency-Track Bom API

openapi: 3.2.0
info:
  title: Dependency Track Bom 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 bom 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: bom
paths:
  /v1/bom:
    post:
      description: 'Expects CycloneDX and a valid project UUID. If a UUID is not specified,

        then the projectName and projectVersion must be specified.

        Optionally, if autoCreate is specified and true and the project does not exist,

        the project will be created. In this scenario, the principal making the request will

        additionally need the PORTFOLIO_MANAGEMENT, PORTFOLIO_MANAGEMENT_CREATE,

        or PROJECT_CREATION_UPLOAD permission.


        The BOM artifact may be supplied uncompressed or compressed. If the BOM is uncompressed,

        the supported MediaType is ''application/xml'' or ''application/json''. If the BOM is compressed,

        the supported MediaType is ''application/gzip'' or ''application/zstd'' and must match the actual

        compression of the data.

        The BOM 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.


        When creating projects, parentUUID or parentName and

        parentVersion can place the new project under a parent,

        projectTags can apply tags, and isLatest can mark it as

        the latest version. The isActive parameter sets the project''s active

        state whenever it is provided, including when the target project already exists, so

        clients should send it only when they intend to change that state.


        Requires permission BOM_UPLOAD'
      operationId: UploadBom
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                autoCreate:
                  type: boolean
                  default: false
                bom:
                  type: string
                  format: binary
                isActive:
                  type: boolean
                isLatest:
                  type: boolean
                  default: false
                parentName:
                  type: string
                parentUUID:
                  type: string
                parentVersion:
                  type: string
                project:
                  type: string
                projectName:
                  type: string
                projectTags:
                  type: string
                projectVersion:
                  type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BomUploadResponse'
          description: Token to be used for checking BOM processing progress
        '400':
          description: The uploaded BOM is invalid
        '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 bill of material format document
      tags:
      - bom
    put:
      description: 'Expects CycloneDX and a valid project UUID. If a UUID is not specified,

        then the projectName and projectVersion must be specified.

        Optionally, if autoCreate is specified and true and the project does not exist,

        the project will be created. In this scenario, the principal making the request will

        additionally need the PORTFOLIO_MANAGEMENT, PORTFOLIO_MANAGEMENT_CREATE,

        or PROJECT_CREATION_UPLOAD permission.


        The BOM 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.


        When creating projects, parentUUID or parentName and

        parentVersion can place the new project under a parent,

        projectTags can apply tags, and isLatest can mark it as

        the latest version. The isActive parameter sets the project''s active

        state whenever it is provided, including when the target project already exists, so

        clients should send it only when they intend to change that state.


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

        When uploading large BOMs, the POST endpoint is preferred,

        as it does not have this limit.


        Requires permission BOM_UPLOAD'
      operationId: UploadBomBase64Encoded
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BomSubmitRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BomUploadResponse'
          description: Token to be used for checking BOM processing progress
        '400':
          description: The uploaded BOM is invalid
        '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 bill of material format document
      tags:
      - bom
    servers:
    - url: /api
  /v1/bom/cyclonedx/component/{uuid}:
    get:
      description: Requires permission VIEW_PORTFOLIO
      operationId: exportComponentAsCycloneDx
      parameters:
      - description: The UUID of the component to export
        in: path
        name: uuid
        required: true
        schema:
          type: string
          format: uuid
      - description: The format to output (defaults to JSON)
        in: query
        name: format
        schema:
          type: string
      - description: 'The CycloneDX Spec variant exported (defaults to: ''1.5'')'
        in: query
        name: version
        schema:
          type: string
      responses:
        '200':
          content:
            application/vnd.cyclonedx+json:
              schema:
                type: string
            application/vnd.cyclonedx+xml:
              schema:
                type: string
          description: Dependency metadata for a specific component 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 component could not be found
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Returns dependency metadata for a specific component in CycloneDX format
      tags:
      - bom
    servers:
    - url: /api
  /v1/bom/cyclonedx/project/{uuid}:
    get:
      description: 'Requires permission VIEW_PORTFOLIO


        The withVulnerabilities and vdr variants

        further require any of the following permissions:


        VIEW_VULNERABILITY


        VULNERABILITY_ANALYSIS


        VULNERABILITY_ANALYSIS_READ'
      operationId: exportProjectAsCycloneDx
      parameters:
      - description: The UUID of the project to export
        in: path
        name: uuid
        required: true
        schema:
          type: string
          format: uuid
      - description: The format to output (defaults to JSON)
        in: query
        name: format
        schema:
          type: string
      - description: Specifies the CycloneDX variant to export. Value options are 'inventory' and 'withVulnerabilities'. (defaults to 'inventory')
        in: query
        name: variant
        schema:
          type: string
      - description: Force the resulting BOM 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
            application/vnd.cyclonedx+xml:
              schema:
                type: string
          description: Dependency metadata 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 dependency metadata for a project in CycloneDX format
      tags:
      - bom
    servers:
    - url: /api
  /v1/bom/token/{uuid}:
    get:
      deprecated: true
      description: 'This endpoint is intended to be used in conjunction with uploading a supported BOM document.

        Upon upload, a token will be returned. The token can then be queried using this endpoint to

        determine if any tasks (such as vulnerability analysis) is being performed on the BOM:


        A value of true indicates processing is occurring.


        A value of false indicates that no processing is occurring for the specified token.


        However, a value of false also does not confirm the token is valid,

        only that no processing is associated with the specified token.


        Requires permission BOM_UPLOAD


        Deprecated. Use /v1/event/token/{uuid} instead.'
      operationId: isTokenBeingProcessed
      parameters:
      - description: The UUID of the token to query
        in: path
        name: uuid
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IsTokenBeingProcessedResponse'
          description: The processing status of the provided token
        '401':
          description: Unauthorized
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Determines if there are any tasks associated with the token that are being…
      tags:
      - bom
    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
    BomSubmitRequest:
      type: object
      properties:
        autoCreate:
          type: boolean
        bom:
          type: string
          format: bytes
          description: Base64 encoded BOM
          example: ewogICJib21Gb3JtYXQiOiAiQ3ljbG9uZURYIiwKICAic3BlY1ZlcnNpb24iOiAiMS40IiwKICAiY29tcG9uZW50cyI6IFsKICAgIHsKICAgICAgInR5cGUiOiAibGlicmFyeSIsCiAgICAgICJuYW1lIjogImFjbWUtbGliIiwKICAgICAgInZlcnNpb24iOiAiMS4wLjAiCiAgICB9CiAgXQp9
          pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$
        isActive:
          type: boolean
        isLatest:
          type: boolean
        parentName:
          type: string
          example: Example Application Parent
          pattern: ^[\p{IsWhite_Space}\p{L}\p{M}\p{S}\p{N}\p{P}]*$
        parentUUID:
          type: string
          example: 5341f53c-611b-4388-9d9c-731026dc5eec
          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
        parentVersion:
          type: string
          example: 1.0.0
          pattern: ^[\p{IsWhite_Space}\p{L}\p{M}\p{S}\p{N}\p{P}]*$
        project:
          type: string
          example: 38640b33-4ba9-4733-bdab-cbfc40c6f8aa
          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
        projectName:
          type: string
          example: Example Application
          minLength: 1
          pattern: ^[\p{IsWhite_Space}\p{L}\p{M}\p{S}\p{N}\p{P}]*$
        projectTags:
          type: array
          example: tag1, tag2
          items:
            $ref: '#/components/schemas/Tag'
        projectVersion:
          type: string
          example: 1.0.0
          minLength: 1
          pattern: ^[\p{IsWhite_Space}\p{L}\p{M}\p{S}\p{N}\p{P}]*$
      required:
      - bom
      - project
      - projectName
      - projectVersion
    Tag:
      type: object
      properties:
        name:
          type: string
          maxLength: 255
          minLength: 1
          pattern: ^[\p{IsWhite_Space}\p{L}\p{M}\p{S}\p{N}\p{P}]*$
      required:
      - name
    IsTokenBeingProcessedResponse:
      type: object
      properties:
        processing:
          type: boolean
        status:
          type:
          - string
          - 'null'
          description: The processing status associated with the token. Null when no processing is associated with the token.
          enum:
          - PENDING
          - RUNNING
          - COMPLETED
          - FAILED
      required:
      - processing
    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
  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