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

    ## Filtering

    Items in a collection can be filtered using query parameters.
    When multiple filter parameters are given, an item must match all of them.

    Filters that accept multiple values take them as repeated parameters,
    e.g. `?<field>=a&<field>=b`. How the values are combined depends on the field:

    - If the field holds a single value, an item matches when it has *any* of the given values.
    - If the field holds multiple values, the parameter name states how they are combined:
      `<field>_all` requires every given value, `<field>_any` at least one.

    Time range filters are named `<field>_since` and `<field>_before`.
    `_since` is inclusive and `_before` is exclusive, so adjacent ranges neither overlap nor leave gaps.

    Text filters state how they match with a suffix: `<field>_contains` matches a substring,
    `<field>_prefix` the start of the value. A filter without a suffix matches the exact value.
    Which filter types are available depends on the operation.

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

    ## Field expansion

    Some collection endpoints support an `expand` query parameter.
    Passing an expand value includes optional fields in each response item
    that are omitted by default, typically because they are expensive to compute
    and only needed in specific contexts.

    Valid `expand` values for an endpoint are listed in its operation description.
    Unknown values are silently ignored.

    ## 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"
    }
    ```

    A request that takes too long to complete is aborted and rejected
    with `504 Gateway Timeout`. Any operation can time out, so operations
    do not document it individually.

    ## Authentication

    Two credential types are accepted:

    - **API key** via the `X-Api-Key` request header. API keys are
      long-lived and intended for machine-to-machine integrations.
    - **Bearer token** via the `Authorization: Bearer <token>` request
      header. Bearer tokens are short-lived, user-bound, and opaque
      server-issued session tokens.

    Bearer tokens are obtained from one of the following endpoints:

    - `POST /api/v1/user/login`
    - `POST /api/v1/user/oidc/login`
    - `POST /api/v2/oauth/token`

    API v2 does not yet provide its own login endpoints; users log in
    through the v1 endpoints above and then call v2 with the token.

    Tokens are valid for 8 hours by default and **cannot be refreshed**.
    Clients must re-authenticate once a token expires.

    Requests with missing or invalid credentials are rejected with
    `401 Unauthorized`.

    ## Authorization

    Access is gated by named permissions. Operations document
    the permission(s) they require; operations without a documented
    permission requirement only require authentication.

    When the *Portfolio Access Control* feature is enabled
    (disabled by default), project-scoped operations additionally enforce
    per-project access via team membership. The `PORTFOLIO_ACCESS_CONTROL_BYPASS`
    permission grants access to all projects regardless of team mappings.
    When the feature is disabled, all authenticated callers holding the required
    permission can access all projects.

    Authenticated requests that lack the required permission, or that
    target a project the caller cannot access, are rejected with
    `403 Forbidden`.

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

    ## Internal operations

    Operations under the `/internal` path prefix expose system internals
    and are reserved for first-party use. They are **not** part of the
    stable v2 API contract and may change or be removed without notice.
    Third-party clients should not depend on them.
  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: Kev Data Sources
  description: Endpoints related to KEV data sources
- name: OAuth
  description: Endpoints related to OAuth 2.0 token issuance
- name: Projects
  description: Endpoints related to projects
- name: Secrets
  description: Endpoints related to secrets
- name: Service Accounts
  description: Endpoints related to service accounts
- name: System Capabilities
  description: Endpoints exposing the capabilities of the running server
- name: Task Queues
  description: Endpoints related to task queue management
- name: Vuln Data Sources
  description: Endpoints related to vulnerability data sources
- name: Vuln Policies
  description: Endpoints related to vulnerability policies
- name: Vulns
  description: Endpoints related to vulnerabilities
- name: Workflows
  description: Endpoints related to workflows
- name: Workload Identity Providers
  description: Endpoints related to workload identity providers

paths:
  /components:
    $ref: "./resources/components/components.yaml"
  /extension-points:
    $ref: "./resources/extensions/extension-points.yaml"
  /extension-points/{extension_point_name}/extensions:
    $ref: "./resources/extensions/extensions.yaml"
  /extension-points/{extension_point_name}/extensions/{extension_name}/config:
    $ref: "./resources/extensions/extension-config.yaml"
  /extension-points/{extension_point_name}/extensions/{extension_name}/config-schema:
    $ref: "./resources/extensions/extension-config-schema.yaml"
  /extension-points/{extension_point_name}/extensions/{extension_name}/test:
    $ref: "./resources/extensions/extension-test.yaml"
  /kev-data-sources/{name}/mirror-runs:
    $ref: "./resources/kev-data-sources/kev-data-source-mirror-runs.yaml"
  /kev-data-sources/{name}/mirror-runs/latest:
    $ref: "./resources/kev-data-sources/kev-data-source-mirror-run-latest.yaml"
  /oauth/token:
    $ref: "./resources/oauth/oauth-token.yaml"
  /projects:
    $ref: "./resources/projects/projects.yaml"
  /projects/{uuid}/clone:
    $ref: "./resources/projects/project-clone.yaml"
  /projects/{uuid}/components:
    $ref: "./resources/projects/project-components.yaml"
  /projects/{uuid}/dependency-graph:
    $ref: "./resources/projects/project-dependency-graph.yaml"
  /secrets:
    $ref: "./resources/secrets/secrets.yaml"
  /secrets/{name}:
    $ref: "./resources/secrets/secret.yaml"
  /service-accounts:
    $ref: "./resources/service-accounts/service-accounts.yaml"
  /service-accounts/{name}:
    $ref: "./resources/service-accounts/service-account.yaml"
  /service-accounts/{name}/api-keys:
    $ref: "./resources/service-accounts/service-account-api-keys.yaml"
  /service-accounts/{name}/api-keys/{public_id}:
    $ref: "./resources/service-accounts/service-account-api-key.yaml"
  /service-accounts/{name}/workload-identity-bindings:
    $ref: "./resources/service-accounts/service-account-workload-identity-bindings.yaml"
  /service-accounts/{name}/workload-identity-bindings/{binding_id}:
    $ref: "./resources/service-accounts/service-account-workload-identity-binding.yaml"
  /workload-identity-providers:
    $ref: "./resources/workload-identity-providers/workload-identity-providers.yaml"
  /workload-identity-providers/{name}:
    $ref: "./resources/workload-identity-providers/workload-identity-provider.yaml"
  /vuln-policies:
    $ref: "./resources/vuln-policies/vuln-policies.yaml"
  /vuln-policies/{uuid}:
    $ref: "./resources/vuln-policies/vuln-policy.yaml"
  /vuln-policy-bundles:
    $ref: "./resources/vuln-policies/vuln-policy-bundles.yaml"
  /vuln-policy-bundles/{uuid}:
    $ref: "./resources/vuln-policies/vuln-policy-bundle.yaml"
  /vuln-policy-bundles/{uuid}/sync-runs:
    $ref: "./resources/vuln-policies/vuln-policy-bundle-sync-runs.yaml"
  /vuln-policy-bundles/{uuid}/sync-runs/latest:
    $ref: "./resources/vuln-policies/vuln-policy-bundle-sync-run-latest.yaml"
  /vuln-data-sources/{name}/mirror-runs:
    $ref: "./resources/vuln-data-sources/vuln-data-source-mirror-runs.yaml"
  /vuln-data-sources/{name}/mirror-runs/latest:
    $ref: "./resources/vuln-data-sources/vuln-data-source-mirror-run-latest.yaml"
  /vulns/{source}/{vuln_id}/kev-assertions:
    $ref: "./resources/vulns/vuln-kev-assertions.yaml"
  /internal/system-capabilities:
    $ref: "./resources/internal/system-capabilities/system-capabilities.yaml"
  /internal/task-queues/{type}:
    $ref: "./resources/internal/task-queues/task-queues.yaml"
  /internal/task-queues/{type}/{name}:
    $ref: "./resources/internal/task-queues/task-queue.yaml"
  /internal/workflow-instances/{id}:
    $ref: "./resources/internal/workflows/workflow-instance.yaml"
  /internal/workflow-runs:
    $ref: "./resources/internal/workflows/workflow-runs.yaml"
  /internal/workflow-runs/{id}:
    $ref: "./resources/internal/workflows/workflow-run.yaml"
  /internal/workflow-runs/{id}/events:
    $ref: "./resources/internal/workflows/workflow-run-events.yaml"

components:
  securitySchemes:
    apiKeyAuth:
      name: X-Api-Key
      description: Authentication via API key.
      type: apiKey
      in: header
    bearerAuth:
      description: |-
        Authentication via opaque server-issued session token.
        Tokens are obtained from `POST /api/v1/user/login`,
        `POST /api/v1/user/oidc/login`, or `POST /api/v2/oauth/token`.
      type: http
      scheme: bearer
      bearerFormat: Opaque