# 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 typically have the following structure:
    
    ```json
    {
      "data": [
        ...
      ],
      "_pagination": {
        "links": {
          "self": "https://example.com/foo?limit=10",
          "next": "https://example.com/foo?page_token=abcdefg&limit=10"
        },
        "total": {
          "count": 100,
          "type": "EXACT"
        }
      }
    }
    ```
    
    `_pagination.links` enables navigation across pages. While the `self` link
    is always returned, `next` will not be present when no more items exist.
    
    To navigate backwards, clients should keep track of the previous `next`
    link(s) as they paginate through collections. The API does *not* provide
    `previous` links!
    
    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. `next` links will not include `sort_by` or `sort_direction`.
    
    `page_token`s are opaque strings. Clients should not try to interpret
    or generate them. Their format may also 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 or estimated counts
    (types `AT_LEAST` or `ESTIMATE` respectively). 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: Metrics
  description: Endpoints related to metrics
- name: Projects
  description: Endpoints related to projects
- name: Secrets
  description: Endpoints related to secrets
- name: Teams
  description: Endpoints related to teams
- name: Workflows
  description: Endpoints related to workflows

paths:
  /advisories:
    $ref: "./paths/advisories.yaml"
  /advisories/{advisoryId}:
    $ref: "./paths/advisories__advisoryid_.yaml"
  /advisories/seen/{advisoryId}:
    $ref: "./paths/advisories_seen__advisoryid_.yaml"
  /advisories/project/{uuid}:
    $ref: "./paths/advisories_project__uuid_.yaml"
  /advisories/project/{uuid}/advisory/{advisoryId}:
    $ref: "./paths/advisories_project__uuid__advisory__advisoryid_.yaml"
  /components:
    $ref: "./paths/components.yaml"
  /extension-points:
    $ref: "./paths/extension-points.yaml"
  /extension-points/{extensionPointName}/extensions:
    $ref: "./paths/extension-points__name__extensions.yaml"
  /extension-points/{extensionPointName}/extensions/{extensionName}/configs:
    $ref: "./paths/extension-points__name__extensions__name__configs.yaml"
  /extension-points/vuln.datasource/extensions/csaf/trigger-mirror:
    $ref: "./paths/extension-points__vuln-datasource__extensions__csaf__trigger-mirror.yaml"
  /extension-points/vuln.datasource/extensions/csaf/sources:
    $ref: "./paths/extension-points__vuln-datasource__extensions__csaf__sources.yaml"
  /extension-points/vuln.datasource/extensions/csaf/sources/{csafSourceId}:
    $ref: "./paths/extension-points__vuln-datasource__extensions__csaf__sources__csafSourceId_.yaml"
  /projects/{uuid}/clone:
    $ref: "./paths/projects__uuid__clone.yaml"
  /projects/{uuid}/components:
    $ref: "./paths/projects_uuid_components.yaml"
  /metrics/portfolio/current:
    $ref: "./paths/metrics_portfolio_current.yaml"
  /metrics/vulnerabilities:
    $ref: "./paths/metrics_vulnerabilities.yaml"
  /secrets:
    $ref: "./paths/secrets.yaml"
  /secrets/{name}:
    $ref: "./paths/secrets__name_.yaml"
  /teams:
    $ref: "./paths/teams.yaml"
  /teams/{name}:
    $ref: "./paths/teams__name_.yaml"
  /team-memberships:
    $ref: "./paths/team-memberships.yaml"
  /workflows/{token}:
    $ref: "./paths/workflows__token__.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