REST API of OWASP Dependency-Track

Pagination

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

{
  "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.

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.

Example:

{
  "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

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.

REST API of OWASP Dependency-Track

Note: This API version is in maintenance mode and will be superseded by v2, available under /api/v2, which follows a spec-first approach. New operations will be added there.

This specification is generated and may not always accurately reflect the actual response content of every operation. When in doubt, treat observed runtime behavior as authoritative.

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

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.

Pagination

Collection endpoints support page-based pagination via the following query parameters:

The total number of items in the collection across all pages is returned in the X-Total-Count response header.

Bounded total counts

An exact X-Total-Count gets more expensive as a collection grows, and on large collections it can time out. Some endpoints therefore accept an optional totalCount query parameter that caps the cost of counting:

Any other value is rejected with 400. Each endpoint documents how it computes the bounded count, on its totalCount parameter.

Endpoints that accept totalCount also return an X-Total-Count-Type header saying how to read X-Total-Count. They return it on every collection response, including ones that did not opt in.

HTTP Methods

Note that the use of PUT for create and POST for update is the inverse of the convention followed by most other REST APIs, including API v2.

Response Conventions

Create (PUT) and update (POST) operations typically return the full resource representation in the response body, with status 201 Created and 200 OK respectively.

Delete (DELETE) operations typically return 204 No Content.

Timeouts

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

Requesting a bounded total count can avoid the timeout where the operation supports it, because counting is often the expensive part.

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.