openapi.yaml

# This file is part of Dependency-Track.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#   http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
# SPDX-License-Identifier: Apache-2.0
# Copyright (c) OWASP Foundation. All Rights Reserved.
openapi: 3.0.3
info:
  title: OWASP Dependency-Track
  description: |-
    # REST API of OWASP Dependency-Track
    
    ## Pagination

    This API implements token-based pagination.
    Collection responses have the following structure:

    ```json
    {
      "items": [...],
      "next_page_token": "abcdefg",
      "total": {
        "count": 100,
        "type": "EXACT"
      }
    }
    ```

    `next_page_token` is present when more items exist, and absent otherwise.
    To fetch the next page, pass it as the `page_token` query parameter.

    To navigate backwards, clients should keep track of previous page tokens
    as they paginate through collections. The API does *not* provide
    backward navigation!

    Collections that support sorting will only consider the `sort_by`
    and `sort_direction` query parameters for the request of the first
    page. For subsequent pages, sorting preferences are bound to the
    page token.

    Page tokens are opaque strings. Clients should not try to interpret
    or generate them. Their format may change without notice.

    The `total` object discloses how many items exist in the collection
    *across all pages*. Because counting is expensive, some collections
    that hold *a lot* of items may return partial counts (type `AT_LEAST`)
    instead of exact counts (type `EXACT`). Which type to expect is usually
    documented in the operation's description.
    
    ## Sorting
    
    Items in a collection can be sorted using the `sort_by` and `sort_direction`
    query parameters. Which fields are sortable is documented in the respective
    operation's description.
    
    Note that if no sortable fields are documented for an operation,
    sorting is not supported *at all*.
  version: 2.0.0
  contact:
    name: The Dependency-Track Authors
    email: dependencytrack@owasp.org
    url: https://github.com/DependencyTrack/dependency-track
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
security:
- apiKeyAuth: [ ]
- bearerAuth: [ ]
servers:
- url: /api/v2
tags:
- name: Advisories
  description: Endpoints related to advisories
- name: Components
  description: Endpoints related to components
- name: Extensions
  description: Endpoints related to extensions
- name: Projects
  description: Endpoints related to projects
- name: Secrets
  description: Endpoints related to secrets
- name: Task Queues
  description: Endpoints related to task queue management
- name: Vulnerability Policies
  description: Endpoints related to vulnerability policies
- name: Workflows
  description: Endpoints related to workflows

paths:
  /advisories:
    $ref: "./paths/advisories.yaml"
  /advisories/{id}:
    $ref: "./paths/advisories__id_.yaml"
  /advisories/{id}/mark-seen:
    $ref: "./paths/advisories__id__mark-seen.yaml"
  /components:
    $ref: "./paths/components.yaml"
  /csaf-aggregators:
    $ref: "./paths/csaf/aggregators.yaml"
  /csaf-aggregators/{id}:
    $ref: "./paths/csaf/aggregators__id_.yaml"
  /csaf-aggregators/{id}/provider-discovery:
    $ref: "./paths/csaf/aggregators__id__provider-discovery.yaml"
  /csaf-providers:
    $ref: "./paths/csaf/providers.yaml"
  /csaf-providers/{id}:
    $ref: "./paths/csaf/providers__id_.yaml"
  /extension-points:
    $ref: "./paths/extension-points.yaml"
  /extension-points/{extensionPointName}/extensions:
    $ref: "./paths/extension-points__name__extensions.yaml"
  /extension-points/{extensionPointName}/extensions/{extensionName}/config:
    $ref: "./paths/extension-points__name__extensions__name__config.yaml"
  /extension-points/{extensionPointName}/extensions/{extensionName}/config-schema:
    $ref: "./paths/extension-points__name__extensions__name__config-schema.yaml"
  /extension-points/{extensionPointName}/extensions/{extensionName}/test:
    $ref: "./paths/extension-points__name__extensions__name__test.yaml"
  /projects/{uuid}/advisories:
    $ref: "./paths/projects__uuid__advisories.yaml"
  /projects/{uuid}/advisories/{advisoryId}/findings:
    $ref: "./paths/projects__uuid__advisories__advisoryId__findings.yaml"
  /projects/{uuid}/clone:
    $ref: "./paths/projects__uuid__clone.yaml"
  /projects/{uuid}/components:
    $ref: "./paths/projects_uuid_components.yaml"
  /task-queues/{type}:
    $ref: "./paths/task-queues__type_.yaml"
  /task-queues/{type}/{name}:
    $ref: "./paths/task-queues__type___name_.yaml"
  /secrets:
    $ref: "./paths/secrets.yaml"
  /secrets/{name}:
    $ref: "./paths/secrets__name_.yaml"
  /vuln-policies:
    $ref: "./paths/vuln-policies.yaml"
  /vuln-policies/{uuid}:
    $ref: "./paths/vuln-policies__uuid_.yaml"
  /vuln-policy-bundles:
    $ref: "./paths/vuln-policy-bundles.yaml"
  /vuln-policy-bundles/{uuid}:
    $ref: "./paths/vuln-policy-bundles__uuid_.yaml"
  /vuln-policy-bundles/{uuid}/sync:
    $ref: "./paths/vuln-policy-bundles__uuid__sync.yaml"
  /workflow-instances/{id}:
    $ref: "./paths/workflow-instances__id_.yaml"
  /workflow-runs:
    $ref: "./paths/workflow-runs.yaml"
  /workflow-runs/{id}:
    $ref: "./paths/workflow-runs__id_.yaml"
  /workflow-runs/{id}/events:
    $ref: "./paths/workflow-runs__id__events.yaml"

components:
  securitySchemes:
    apiKeyAuth:
      name: X-Api-Key
      description: Authentication via API key
      type: apiKey
      in: header
    bearerAuth:
      description: Authentication via Bearer token
      type: http
      scheme: Bearer