Archive, unarchive or delete repositories with REST API in Bitbucket Data Center
Platform Notice: Data Center Only - This article only applies to Atlassian apps on the Data Center platform.
Note that this KB was created for the Data Center version of the product. Data Center KBs for non-Data-Center-specific features may also work for Server versions of the product, however they have not been tested. Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.
*Except Fisheye and Crucible
Summary
This article shares APIs that can be used to automate Bitbucket repository management. These API endpoints allow you to archive, unarchive, or delete redundant or unused repositories.
Archiving repositories declutter repository lists and ensure more accurate code search results by excluding archived repositories from searches. Once archived, repositories become read-only. Actions such as creating pull requests, and branches, adding comments, or changing repository details are blocked. However, you can still fork and clone archived repositories.
You can achieve archiving and deletion of the repo from UI details mentioned in the document: Archive a repository.
Environment
All Bitbucket-supported versions >= 8.0.
Which operation do you need?
Goal | HTTP verb | REST endpoint | Body |
|---|---|---|---|
Archive a repository (read-only, retains history) | PUT |
|
|
Unarchive a previously archived repository | PUT |
|
|
Permanently delete a repository | DELETE |
| - |
Permissions
Archive / Unarchive: Requires Repository Admin or higher permission.
Delete: Sufficient permissions specified by the repository delete policy to call the endpoint. Default: Repository Admin or higher.
Authenticate using an HTTP access token (PAT) with header: Authorization: Bearer <PAT>.Bitbucket DC versions (≥ 8.0) support PATs.
Solution
Archive or Unarchive a repository
The repository archive/unarchive task can be accomplished using the default repository endpoint, /rest/api/latest/projects/{projectkey}/repos/{repositorySlug}, with the option true or false for attribute 'archived':
Archive repository
curl --request PUT \
--url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/repos/{repositorySlug}' \
--header 'Accept: application/json;charset=UTF-8'
--data '{"archived": true}'Unarchive repository
curl --request PUT \
--url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/repos/{repositorySlug}' \
--header 'Accept: application/json;charset=UTF-8'
--data '{"archived": false}'Here's an example of what a request to this endpoint might look like:
curl -X PUT -u Admin https://<baseurl>/rest/api/1.0/projects/TES/repos/testrepo01 -H 'Content-Type: application/json' -d '{"archived": true}' | jq
{
"slug": "testrepo01",
"id": 263,
"name": "TestRepo01",
"hierarchyId": "1b8cc791e7fb599afd7b",
"scmId": "git",
"state": "AVAILABLE",
"statusMessage": "Available",
"forkable": true,
"project": {
"key": "TES",
"id": 42,
"name": "TestProject",
"public": false,
"type": "NORMAL",
"links": {
"self": [
{
"href": "https://<baseurl>/projects/TES"
}
]
}
},
"public": false,
"archived": true,
"links": {
"clone": [
{
"href": "ssh://git@<baseurl>/tes/testrepo01.git",
"name": "ssh"
},
{
"href": "https://<baseurl>/scm/tes/testrepo01.git",
"name": "http"
}
],
"self": [
{
"href": "https://<baseurl>/projects/TES/repos/testrepo01/browse"
}
]
}Delete a repository
To delete a repository, we also use the /rest/api/latest/projects/{projectkey}/repos/{repositorySlug} endpoint, but now calling the DELETE option.
Delete a repository
curl --request DELETE \
--url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/repos/{repositorySlug}'For example:
curl -X DELETE -u Admin https://<baseurl>/rest/api/1.0/projects/TES/repos/testrepo01 | jq
{
"context": null,
"message": "Repository scheduled for deletion.",
"exceptionName": null
}Common errors and Resolutions
HTTP Status | Likely cause | Resolution |
|---|---|---|
401 Unauthorized | Missing or invalid password or auth token | Confirm password is correct or PAT is valid and header format is |
403 Forbidden | User lacks the required permission per the Delete/Archive Repository Policy | Check Administration → Global Permissions → Policies; grant the required role |
404 Not Found | Wrong project key or repository slug | Verify slugs via UI URL: |
Verification
Archive a repository
Confirm the repository UI shows the "Archived" badge in Projects → Repository list.
Try to perform a git push and it should fail with "repository is archived" error
Unarchive a repository
Confirm the badge is removed and push succeed
Delete a repository
Confirm the repo URL returns 404 and is removed from the Project page
Check audit log: Administration (gear icon) → Audit log for the deletion event
Related articles
Was this helpful?