Trash API
6 endpoints. Request and response schemas are described on the schemas page; the other tags are listed in the API index.
Endpoints
GET /api/v1/repositories/{name}/trash
List a repository's trash
Soft-deleted items of one repository. Requires the repository-scoped delete permission; unknown or trashed repository: 404.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | yes | - |
kind | query | string | no | Only items of this kind. One of: repository, maven_artifact, ivy_artifact, sbt_artifact, apk_package, terraform_module, terraform_provider, npm_version, pypi_package, nuget_package, go_module, cargo_crate, rubygems_gem, conda_package, pacman, conan_package, helm_chart, raw_artifact, docker_manifest, docker_tag, rpm_package, deb_package. |
page | query | integer | no | Page number (default 1). Minimum: 1. |
limit | query | integer | no | Items per page (default 50, max 200). Minimum: 1. Maximum: 200. |
Responses
| Status | Description | Body |
|---|---|---|
200 | A page of trashed items, newest deletion first | application/json: TrashList |
400 | Invalid request | application/json: Error |
403 | Delete permission on the repository required | - |
404 | Repository not found | - |
DELETE /api/v1/repositories/{name}/trash
Empty a repository's trash
Permanently purges the trashed items of one repository now (blobs freed, quota released, audit artifact.purged and webhook events as for a single purge). Items only: neither the repository nor a trashed repository row is touched. Requires the repository-scoped manage permission (global administrators have it) or the maintainer or owner role in the repository's project. At most 1000 items are purged per request; remaining says how many are left, so repeat the call until it is 0.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | yes | - |
Responses
| Status | Description | Body |
|---|---|---|
200 | Items purged by this request and items still in the trash | application/json: TrashEmpty |
400 | Invalid request, including a NUL byte in the URL or the body | application/json: Error |
403 | Manage permission on the repository required | - |
404 | Repository not found | - |
POST /api/v1/repositories/{name}/trash/{kind}/{id}/restore
Restore an item of a repository
Like the admin restore, for callers with the repository-scoped delete permission. The item must belong to the repository; kind repository is admin only.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | yes | - |
kind | path | string | yes | One of the TrashItem kind values. One of: repository, maven_artifact, ivy_artifact, sbt_artifact, apk_package, terraform_module, terraform_provider, npm_version, pypi_package, nuget_package, go_module, cargo_crate, rubygems_gem, conda_package, pacman, conan_package, helm_chart, raw_artifact, docker_manifest, docker_tag, rpm_package, deb_package. |
id | path | string (uuid) | yes | Trash item id. |
Responses
| Status | Description | Body |
|---|---|---|
200 | The restored item | application/json: TrashItem |
400 | Invalid request | application/json: Error |
403 | Delete permission on the repository required (restoring a repository needs an admin) | - |
404 | Trash item not found (never deleted, already restored or purged, or not in this repository) | application/json: Error |
409 | trash_conflict: an item with the same name/version was published after the delete; delete or rename it first. repository_in_trash: the item's repository is in the trash; restore the repository first. manifest_in_trash: a docker tag's manifest is in the trash; restore the manifest first. | application/json: Error |
GET /api/v1/trash
List the trash (admin)
Every soft-deleted package and repository, newest first.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
kind | query | string | no | Only items of this kind. One of: repository, maven_artifact, ivy_artifact, sbt_artifact, apk_package, terraform_module, terraform_provider, npm_version, pypi_package, nuget_package, go_module, cargo_crate, rubygems_gem, conda_package, pacman, conan_package, helm_chart, raw_artifact, docker_manifest, docker_tag, rpm_package, deb_package. |
repository | query | string | no | Only items of the repository with this name (a repository that is itself in the trash is not matched by name; its items are hidden). |
page | query | integer | no | Page number (default 1). Minimum: 1. |
limit | query | integer | no | Items per page (default 50, max 200). Minimum: 1. Maximum: 200. |
Responses
| Status | Description | Body |
|---|---|---|
200 | A page of trashed items, newest deletion first | application/json: TrashList |
400 | Invalid request | application/json: Error |
403 | Admin access required | - |
DELETE /api/v1/trash/{kind}/{id}
Purge a trashed item now (admin)
Permanently removes the item before its retention window ends: frees its blobs (a repository's are swept as orphans afterwards), releases quota and emits artifact.purged / repository.purged. Cannot be undone.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
kind | path | string | yes | One of the TrashItem kind values. One of: repository, maven_artifact, ivy_artifact, sbt_artifact, apk_package, terraform_module, terraform_provider, npm_version, pypi_package, nuget_package, go_module, cargo_crate, rubygems_gem, conda_package, pacman, conan_package, helm_chart, raw_artifact, docker_manifest, docker_tag, rpm_package, deb_package. |
id | path | string (uuid) | yes | Trash item id. |
Responses
| Status | Description | Body |
|---|---|---|
204 | Purged | - |
400 | Invalid request | application/json: Error |
403 | Admin access required | - |
404 | Trash item not found | application/json: Error |
409 | The repository is still referenced (for example by a release bundle or promotion) | application/json: Error |
POST /api/v1/trash/{kind}/{id}/restore
Restore a trashed item or repository (admin)
Brings the item back, refreshes the repository's generated metadata and emits artifact.restored / repository.restored. Restoring into a name or version that was published meanwhile fails with 409 trash_conflict.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
kind | path | string | yes | One of the TrashItem kind values. One of: repository, maven_artifact, ivy_artifact, sbt_artifact, apk_package, terraform_module, terraform_provider, npm_version, pypi_package, nuget_package, go_module, cargo_crate, rubygems_gem, conda_package, pacman, conan_package, helm_chart, raw_artifact, docker_manifest, docker_tag, rpm_package, deb_package. |
id | path | string (uuid) | yes | Trash item id. |
Responses
| Status | Description | Body |
|---|---|---|
200 | The restored item | application/json: TrashItem |
400 | Invalid request | application/json: Error |
403 | Admin access required | - |
404 | Trash item not found (never deleted, already restored or purged, or not in this repository) | application/json: Error |
409 | trash_conflict: an item with the same name/version was published after the delete; delete or rename it first. repository_in_trash: the item's repository is in the trash; restore the repository first. manifest_in_trash: a docker tag's manifest is in the trash; restore the manifest first. | application/json: Error |