# 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*.

    ## Errors

    All error responses use the `application/problem+json` media type
    as defined in [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457.html).

    Example:

    ```json
    {
      "type": "about:blank",
      "status": 404,
      "title": "Resource Not Found",
      "detail": "No project with UUID 0976ef46-e4a0-4be4-8b0e-00e9d3625c1f exists"
    }
    ```

    ## HTTP Methods

    | Method   | Semantics                  |
    |----------|----------------------------|
    | `GET`    | Retrieve a resource        |
    | `POST`   | Create a new resource      |
    | `PUT`    | Update a resource          |
    | `PATCH`  | Partially update a resource|
    | `DELETE` | Delete a resource          |

    ## Response Conventions

    Create and update operations (`POST`, `PUT`, `PATCH`) do not return
    the full resource in the response. They return either no body,
    or only server-generated identifiers (e.g. a UUID).
    `POST` responses may include a `Location` header linking to the
    created resource.

    Delete operations return `204 No Content` with no body.

    ## Deprecations

    Operations may be removed or replaced over time. When a response
    carries the `X-API-Deprecated: true` header, the operation that
    produced it is deprecated and may be removed in a future release.
    Clients should check for this header on every response and surface
    it (e.g. via a log warning) so that operators are aware of upcoming
    breakages. The respective operation's description points out which
    alternative operation(s) to use.
  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: 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:
  /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}/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}/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