Gets the announcement banner, if one exists and is available to the user
Forge and OAuth2 apps cannot access this REST resource.
This request has no parameters.
The requested banner
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/admin/banner' \
--header 'Accept: application/json'1
2
3
4
5
{
"audience": "AUTHENTICATED",
"message": "<string>",
"enabled": true
}Sets the announcement banner with the provided JSON. Only users authenticated as Admins may call this resource
Forge and OAuth2 apps cannot access this REST resource.
string
Requiredboolean
string
The banner was set successfully
any
1
2
3
4
5
6
7
8
9
curl --request PUT \
--url 'http://{baseurl}/rest/api/latest/admin/banner' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"audience": "AUTHENTICATED",
"enabled": true,
"message": "<string>"
}'Deletes a banner, if one is present in the database.
Forge and OAuth2 apps cannot access this REST resource.
This request has no parameters.
The query executed successfully, whether a banner was deleted or not
any
1
2
3
curl --request DELETE \
--url 'http://{baseurl}/rest/api/latest/admin/banner' \
--header 'Accept: application/json'Gets information about the nodes that currently make up the stash cluster.
The authenticated user must have the SYS_ADMIN permission to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
This request has no parameters.
A response containing information about the cluster
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/admin/cluster' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
{
"localNode": {
"buildVersion": "7.0.0",
"name": "foo",
"id": "d4fde8b1-2504-4998-a0ba-14fbe98edd4d",
"address": {
"address": "node.example.com",
"port": 8230
},
"local": true
},
"running": true,
"nodes": [
{
"buildVersion": "7.0.0",
"name": "foo",
"id": "d4fde8b1-2504-4998-a0ba-14fbe98edd4d",
"address": {
"address": "node.example.com",
"port": 8230
},
"local": true
}
]
}Retrieves the configured global default branch, which is used when creating new repositories if an explicit default branch is not specified. The user must be authenticated to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
This request has no parameters.
The configured global default branch.
any
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/admin/default-branch' \
--header 'Accept: application/json'Configures the global default branch, which is used when creating new repositories if an explicit default branch is not specified.
The authenticated user must have ADMIN permission to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
The default branch has been set.
any
1
2
3
4
5
6
7
curl --request PUT \
--url 'http://{baseurl}/rest/api/latest/admin/default-branch' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"id": "<string>"
}'Clears the global default branch, which is used when creating new repositories if an explicit default branch is not specified, if one has been configured.
The authenticated user must have ADMIN permission to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
This request has no parameters.
The default branch has been cleared.
any
1
2
3
curl --request DELETE \
--url 'http://{baseurl}/rest/api/latest/admin/default-branch' \
--header 'Accept: application/json'Obtain the control plane PEM.
The authenticated user must have SYS_ADMIN permission.
Forge and OAuth2 apps cannot access this REST resource.
This request has no parameters.
The control plane PEM.
any
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/admin/git/mesh/config/control-plane.pem' \
--header 'Accept: text/plain'Generates a connectivity report between the Bitbucket node(s) and the Mesh node(s).
The authenticated user must have SYS_ADMIN permission.
Forge and OAuth2 apps cannot access this REST resource.
This request has no parameters.
The connectivity report between the Bitbucket node(s) and Mesh node(s).
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/admin/git/mesh/diagnostics/connectivity' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
{
"reports": [
{
"summaries": [
{
"summary": {
"reachable": true,
"roundTripTime": 100,
"errorMessage": "Unable to connect to the node."
},
"node": {
"name": "My Node",
"id": "1",
"type": "BITBUCKET"
}
}
],
"node": {
"name": "My Node",
"id": "1",
"type": "BITBUCKET"
}
}
]
}Get all the registered Mesh nodes.
The authenticated user must have SYS_ADMIN permission.
Forge and OAuth2 apps cannot access this REST resource.
This request has no parameters.
The list of registered Mesh nodes.
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/admin/git/mesh/nodes' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
{
"rpcUrl": "http://127.0.0.1:7999",
"lastSeenDate": 1630041546433,
"rpcId": "1",
"name": "My node",
"id": "1",
"offline": false
}Register a new Mesh node.
The authenticated user must have SYS_ADMIN permission.
Forge and OAuth2 apps cannot access this REST resource.
The request specifying the new Mesh node.
string
number
string
string
string
boolean
The newly registered Mesh node.
1
2
3
4
5
6
7
8
9
10
11
12
curl --request POST \
--url 'http://{baseurl}/rest/api/latest/admin/git/mesh/nodes' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"rpcUrl": "http://127.0.0.1:7999",
"lastSeenDate": 1630041546433,
"rpcId": "1",
"name": "My node",
"id": "1",
"offline": false
}'1
2
3
4
5
6
7
8
{
"rpcUrl": "http://127.0.0.1:7999",
"lastSeenDate": 1630041546433,
"rpcId": "1",
"name": "My node",
"id": "1",
"offline": false
}Get the registered Mesh node that matches the supplied ID.
The authenticated user must have SYS_ADMIN permission.
Forge and OAuth2 apps cannot access this REST resource.
string
RequiredThe Mesh node that matches the ID.
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/admin/git/mesh/nodes/{id}' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
{
"rpcUrl": "http://127.0.0.1:7999",
"lastSeenDate": 1630041546433,
"rpcId": "1",
"name": "My node",
"id": "1",
"offline": false
}Update a Mesh node.
The authenticated user must have SYS_ADMIN permission.
Forge and OAuth2 apps cannot access this REST resource.
string
RequiredThe request specifying the updated Mesh node.
string
number
string
string
string
boolean
The updated Mesh node.
1
2
3
4
5
6
7
8
9
10
11
12
curl --request PUT \
--url 'http://{baseurl}/rest/api/latest/admin/git/mesh/nodes/{id}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"rpcUrl": "http://127.0.0.1:7999",
"lastSeenDate": 1630041546433,
"rpcId": "1",
"name": "My node",
"id": "1",
"offline": false
}'1
2
3
4
5
6
7
8
{
"rpcUrl": "http://127.0.0.1:7999",
"lastSeenDate": 1630041546433,
"rpcId": "1",
"name": "My node",
"id": "1",
"offline": false
}Get the support zips for all the Mesh nodes.
The authenticated user must have SYS_ADMIN permission.
Forge and OAuth2 apps cannot access this REST resource.
This request has no parameters.
The support zips for all the Mesh nodes.
any
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/admin/git/mesh/support-zips' \
--header 'Accept: application/octet-stream'Get the support zip for the Mesh node that matches the specified ID.
The authenticated user must have SYS_ADMIN permission.
Forge and OAuth2 apps cannot access this REST resource.
string
RequiredThe support zip for the Mesh node that matches the ID.
any
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/admin/git/mesh/support-zips/{id}' \
--header 'Accept: application/octet-stream'Retrieve a page of groups.
The authenticated user must have LICENSED_USER permission or higher to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
number
number
A page of groups.
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/admin/groups' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
10
11
12
13
{
"values": [
{
"deletable": true,
"name": "group-a"
}
],
"size": 1,
"isLastPage": true,
"nextPageStart": 2154,
"start": 2154,
"limit": 25
}Create a new group.
The authenticated user must have ADMIN permission or higher to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
RequiredThe newly created group.
1
2
3
curl --request POST \
--url 'http://{baseurl}/rest/api/latest/admin/groups?name={name}' \
--header 'Accept: application/json'1
2
3
4
{
"deletable": true,
"name": "group-a"
}Deletes the specified group, removing them from the system. This also removes any permissions that may have been granted to the group.
A user may not delete the last group that is granting them administrative permissions, or a group with greater permissions than themselves.
The authenticated user must have the ADMIN permission to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
RequiredThe deleted group.
1
2
3
curl --request DELETE \
--url 'http://{baseurl}/rest/api/latest/admin/groups?name={name}' \
--header 'Accept: application/json'1
2
3
4
{
"deletable": true,
"name": "group-a"
}Deprecated since 2.10. Use /rest/users/add-groups instead.
Add a user to a group.
In the request entity, the context attribute is the group and the itemName is the user.
The authenticated user must have the ADMIN permission to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
string
The user was added to the group.
any
1
2
3
4
5
6
7
8
curl --request POST \
--url 'http://{baseurl}/rest/api/latest/admin/groups/add-user' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"context": "group_a",
"itemName": "user_a"
}'Add multiple users to a group.
The authenticated user must have the ADMIN permission to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
array<string>
RequiredAll the users were added to the group
any
1
2
3
4
5
6
7
8
9
10
11
curl --request POST \
--url 'http://{baseurl}/rest/api/latest/admin/groups/add-users' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"group": "group",
"users": [
"user1",
"user2"
]
}'Retrieves a list of users that are members of a specified group.
The authenticated user must have the LICENSED_USER permission to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
string
Requirednumber
number
A page of users.
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/admin/groups/more-members?context={context}' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
"values": [
{
"directoryName": "Bitbucket Internal Directory",
"lastAuthenticationTimestamp": 1368145580548,
"deletable": true,
"mutableDetails": true,
"mutableGroups": true,
"slug": "jcitizen",
"emailAddress": "jane@example.com",
"displayName": "Jane Citizen",
"name": "jcitizen",
"id": 101,
"type": "NORMAL",
"active": true
}
],
"size": 1,
"isLastPage": true,
"nextPageStart": 2154,
"start": 2154,
"limit": 25
}Retrieves a list of users that are not members of a specified group.
The authenticated user must have the LICENSED_USER permission to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
string
Requirednumber
number
A page of users.
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/admin/groups/more-non-members?context={context}' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
"values": [
{
"directoryName": "Bitbucket Internal Directory",
"lastAuthenticationTimestamp": 1368145580548,
"deletable": true,
"mutableDetails": true,
"mutableGroups": true,
"slug": "jcitizen",
"emailAddress": "jane@example.com",
"displayName": "Jane Citizen",
"name": "jcitizen",
"id": 101,
"type": "NORMAL",
"active": true
}
],
"size": 1,
"isLastPage": true,
"nextPageStart": 2154,
"start": 2154,
"limit": 25
}Deprecated since 2.10. Use /rest/users/remove-groups instead.
Remove a user from a group.
The authenticated user must have the ADMIN permission to call this resource.
In the request entity, the context attribute is the group and the itemName is the user.
Forge and OAuth2 apps cannot access this REST resource.
string
string
The user was removed from the group.
any
1
2
3
4
5
6
7
8
curl --request POST \
--url 'http://{baseurl}/rest/api/latest/admin/groups/remove-user' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"context": "group_a",
"itemName": "user_a"
}'Retrieves details about the current license, as well as the current status of the system with regards to the installed license. The status includes the current number of users applied toward the license limit, as well as any status messages about the license (warnings about expiry or user counts exceeding license limits).
The authenticated user must have ADMIN permission. Unauthenticated users, and non-administrators, are not permitted to access license details.
Forge and OAuth2 apps cannot access this REST resource.
This request has no parameters.
The currently-installed license.
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/admin/license' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
"serverId": "<server ID embedded in license>",
"creationDate": 1331038800000,
"daysBeforeExpiry": 2154,
"expiryDate": 1372493732817,
"gracePeriodEndDate": 1372493732817,
"maintenanceExpiryDate": 1372493732817,
"maximumNumberOfUsers": 12,
"numberOfDaysBeforeExpiry": 2154,
"numberOfDaysBeforeGracePeriodExpiry": 2154,
"numberOfDaysBeforeMaintenanceExpiry": 2154,
"purchaseDate": 1331038800000,
"supportEntitlementNumber": "<support entitlement number embedded in license>",
"unlimitedNumberOfUsers": true,
"license": "<encoded license text>",
"status": {
"serverId": "<actual server ID>",
"currentNumberOfUsers": 2
}
}Decodes the provided encoded license and sets it as the active license. If no license was provided, a 400 is returned. If the license cannot be decoded, or cannot be applied, a 409 is returned. Some possible reasons a license may not be applied include:
Otherwise, if the license is updated successfully, details for the new license are returned with a 200 response.
Warning: It is possible to downgrade the license during update, applying a license with a lower number of permitted users. If the number of currently-licensed users exceeds the limits of the new license, pushing will be disabled until the licensed user count is brought into compliance with the new license.
The authenticated user must have SYS_ADMIN permission. ADMIN users may view the current license details, but they may not update the license.
Forge and OAuth2 apps cannot access this REST resource.
a JSON payload containing the encoded license to apply
string
The newly-installed license.
1
2
3
4
5
6
7
curl --request POST \
--url 'http://{baseurl}/rest/api/latest/admin/license' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"license": "<encoded license text>"
}'1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
"serverId": "<server ID embedded in license>",
"creationDate": 1331038800000,
"daysBeforeExpiry": 2154,
"expiryDate": 1372493732817,
"gracePeriodEndDate": 1372493732817,
"maintenanceExpiryDate": 1372493732817,
"maximumNumberOfUsers": 12,
"numberOfDaysBeforeExpiry": 2154,
"numberOfDaysBeforeGracePeriodExpiry": 2154,
"numberOfDaysBeforeMaintenanceExpiry": 2154,
"purchaseDate": 1331038800000,
"supportEntitlementNumber": "<support entitlement number embedded in license>",
"unlimitedNumberOfUsers": true,
"license": "<encoded license text>",
"status": {
"serverId": "<actual server ID>",
"currentNumberOfUsers": 2
}
}Retrieves the current mail configuration.
The authenticated user must have the SYS_ADMIN permission to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
This request has no parameters.
The mail configuration
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/admin/mail-server' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
10
{
"senderAddress": "stash-no-reply@company.com",
"hostname": "smtp.example.com",
"requireStartTls": true,
"useStartTls": true,
"port": 465,
"protocol": "SMTP",
"password": "password",
"username": "user"
}Updates the mail configuration.
The authenticated user must have the SYS_ADMIN permission to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
string
integer
string
boolean
string
boolean
string
The updated mail configuration.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
curl --request PUT \
--url 'http://{baseurl}/rest/api/latest/admin/mail-server' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"hostname": "smtp.example.com",
"password": "password",
"port": 465,
"protocol": "SMTP",
"requireStartTls": true,
"senderAddress": "stash-no-reply@company.com",
"useStartTls": true,
"username": "user"
}'1
2
3
4
5
6
7
8
9
10
{
"senderAddress": "stash-no-reply@company.com",
"hostname": "smtp.example.com",
"requireStartTls": true,
"useStartTls": true,
"port": 465,
"protocol": "SMTP",
"password": "password",
"username": "user"
}Deletes the current mail configuration.
The authenticated user must have the SYS_ADMIN permission to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
This request has no parameters.
The mail configuration was successfully deleted.
any
1
2
3
curl --request DELETE \
--url 'http://{baseurl}/rest/api/latest/admin/mail-server' \
--header 'Accept: application/json'Retrieves the server email address
Forge and OAuth2 apps cannot access this REST resource.
This request has no parameters.
The server email address
any
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/admin/mail-server/sender-address' \
--header 'Accept: application/json'Updates the server email address
The authenticated user must have the ADMIN permission to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
The from address used in notification emails
any
1
2
3
4
5
curl --request PUT \
--url 'http://{baseurl}/rest/api/latest/admin/mail-server/sender-address' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '"<string>"'Clears the server email address.
The authenticated user must have the ADMIN permission to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
This request has no parameters.
he server email address was successfully cleared.
any
1
2
3
curl --request DELETE \
--url 'http://{baseurl}/rest/api/latest/admin/mail-server/sender-address' \
--header 'Accept: application/json'Retrieve a page of groups that have been granted at least one global permission.
The authenticated user must have ADMIN permission or higher to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
number
number
A page of groups and their highest global permissions.
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/admin/permissions/groups' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
"values": [
{
"permission": "ADMIN",
"group": {
"name": "group_a"
}
}
],
"size": 1,
"isLastPage": true,
"nextPageStart": 2154,
"start": 2154,
"limit": 25
}Promote or demote a user's global permission level. Available global permissions are:
See the Bitbucket Server documentation for a detailed explanation of what each permission entails.
The authenticated user must have:
to call this resource. In addition, a user may not demote a group's permission level if their own permission level would be reduced as a result.
Forge and OAuth2 apps cannot access this REST resource.
array<string>
Requiredstring
RequiredThe specified permission was granted to the specified user.
any
1
2
3
curl --request PUT \
--url 'http://{baseurl}/rest/api/latest/admin/permissions/groups?name={name}&permission={permission}' \
--header 'Accept: application/json'Revoke all global permissions for a group.
The authenticated user must have:
to call this resource. In addition, a user may not revoke a group's permissions if their own permission level would be reduced as a result.
Forge and OAuth2 apps cannot access this REST resource.
string
RequiredAll global permissions were revoked from the group.
any
1
2
3
curl --request DELETE \
--url 'http://{baseurl}/rest/api/latest/admin/permissions/groups?name={name}' \
--header 'Accept: application/json'Retrieve a page of groups that have no granted global permissions.
The authenticated user must have ADMIN permission or higher to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
number
number
A page of groups that have not been granted any global permissions.
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/admin/permissions/groups/none' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
10
11
12
13
{
"values": [
{
"deletable": true,
"name": "group-a"
}
],
"size": 1,
"isLastPage": true,
"nextPageStart": 2154,
"start": 2154,
"limit": 25
}Retrieve a page of users that have been granted at least one global permission.
The authenticated user must have ADMIN permission or higher to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
number
number
A page of users and their highest global permissions.
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/admin/permissions/users' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
"values": [
{
"permission": "ADMIN",
"group": {
"name": "group_a"
}
}
],
"size": 1,
"isLastPage": true,
"nextPageStart": 2154,
"start": 2154,
"limit": 25
}Promote or demote the global permission level of a user. Available global permissions are:
See the Bitbucket Server documentation for a detailed explanation of what each permission entails.
The authenticated user must have:
to call this resource. In addition, a user may not demote their own permission level.
Forge and OAuth2 apps cannot access this REST resource.
array<string>
Requiredstring
RequiredThe requested permission was granted.
any
1
2
3
curl --request PUT \
--url 'http://{baseurl}/rest/api/latest/admin/permissions/users?name={name}&permission={permission}' \
--header 'Accept: application/json'Revoke all global permissions for a user.
The authenticated user must have:
to call this resource. In addition, a user may not demote their own permission level.
Forge and OAuth2 apps cannot access this REST resource.
string
RequiredAll global permissions were revoked from the user.
any
1
2
3
curl --request DELETE \
--url 'http://{baseurl}/rest/api/latest/admin/permissions/users?name={name}' \
--header 'Accept: application/json'Retrieve a page of users that have no granted global permissions.
The authenticated user must have ADMIN permission or higher to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
number
number
A page of users that have not been granted any global permissions.
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/admin/permissions/users/none' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
"values": [
{
"slug": "jcitizen",
"emailAddress": "jane@example.com",
"displayName": "Jane Citizen",
"name": "jcitizen",
"id": 101,
"type": "NORMAL",
"active": true
}
],
"size": 1,
"isLastPage": true,
"nextPageStart": 2154,
"start": 2154,
"limit": 25
}Retrieve the merge strategies available for this instance. The user must be authenticated to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
RequiredThe merge configuration of this instance.
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/admin/pull-requests/{scmId}' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
"strategies": [
{
"flag": "--no-ff",
"name": "Merge commit",
"id": "no-ff",
"enabled": true,
"description": "Always create a merge commit"
}
],
"commitSummaries": 2154,
"defaultStrategy": {
"flag": "--no-ff",
"name": "Merge commit",
"id": "no-ff",
"enabled": true,
"description": "Always create a merge commit"
},
"type": "repository"
}Update the pull request merge strategies for the context repository.
The authenticated user must have ADMIN permission to call this resource.
Only the strategies provided will be enabled, only one may be set to default
An explicitly set pull request merge strategy configuration can be deleted by POSTing a document with an empty "mergeConfig" attribute. i.e:```{ "mergeConfig": { } }
1 2Upon completion of this request, the effective configuration will be the default configuration.
Forge and OAuth2 apps cannot access this REST resource.
string
Requiredthe settings
object
The repository pull request merge strategies for the context repository.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
curl --request POST \
--url 'http://{baseurl}/rest/api/latest/admin/pull-requests/{scmId}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"mergeConfig": {
"strategies": [
{
"id": "no-ff",
"links": {}
}
],
"commitSummaries": 2154,
"defaultStrategy": {
"id": "no-ff",
"links": {}
}
}
}'1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
"strategies": [
{
"flag": "--no-ff",
"name": "Merge commit",
"id": "no-ff",
"enabled": true,
"description": "Always create a merge commit"
}
],
"commitSummaries": 2154,
"defaultStrategy": {
"flag": "--no-ff",
"name": "Merge commit",
"id": "no-ff",
"enabled": true,
"description": "Always create a merge commit"
},
"type": "repository"
}Retrieves the recent rate limit history for the instance.
The authenticated user must have the ADMIN permission to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
number
number
A response containing a page of aggregated counters for users who have been recently rate limited.
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/admin/rate-limit/history' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
"values": [
{
"lastRejectTime": 1630041546433,
"rejectCount": 5,
"user": {
"slug": "jcitizen",
"emailAddress": "jane@example.com",
"displayName": "Jane Citizen",
"name": "jcitizen",
"id": 101,
"type": "NORMAL",
"active": true
}
}
],
"size": 1,
"isLastPage": true,
"nextPageStart": 2154,
"start": 2154,
"limit": 25
}Retrieves the rate limit settings for the instance. The user must be authenticated to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
This request has no parameters.
A response containing the rate limit plugin settings for the instance.
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/admin/rate-limit/settings' \
--header 'Accept: application/json'1
2
3
4
5
6
7
{
"defaultSettings": {
"capacity": 60,
"fillRate": 5
},
"enabled": true
}Sets the rate limit settings for the instance.
The authenticated user must have ADMIN permission to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
Sets the rate limit settings for the instance.
The authenticated user must have ADMIN permission to call this resource.
object
boolean
A response containing the updated rate limit plugin settings for the instance.
1
2
3
4
5
6
7
8
9
10
11
curl --request PUT \
--url 'http://{baseurl}/rest/api/latest/admin/rate-limit/settings' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"defaultSettings": {
"capacity": 60,
"fillRate": 5
},
"enabled": true
}'1
2
3
4
5
6
7
{
"defaultSettings": {
"capacity": 60,
"fillRate": 5
},
"enabled": true
}Retrieves the user-specific rate limit settings for the given user.
The authenticated user must have ADMIN permission to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
number
number
A response containing all the user-specific rate limit settings filtered by the optional filter.
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/admin/rate-limit/settings/users' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
{
"values": [
{
"whitelisted": true,
"user": {
"slug": "jcitizen",
"emailAddress": "jane@example.com",
"displayName": "Jane Citizen",
"name": "jcitizen",
"id": 101,
"type": "NORMAL",
"active": true
},
"settings": {
"capacity": 60,
"fillRate": 5
}
}
],
"size": 1,
"isLastPage": true,
"nextPageStart": 2154,
"start": 2154,
"limit": 25
}Sets the given rate limit settings for the given users.
The authenticated user must have ADMIN permission to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
object
array<string>
boolean
A response containing the updated user settings.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
curl --request POST \
--url 'http://{baseurl}/rest/api/latest/admin/rate-limit/settings/users' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"settings": {
"capacity": 60,
"fillRate": 5
},
"usernames": [
"<string>"
],
"whitelisted": true
}'1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
"whitelisted": true,
"user": {
"slug": "jcitizen",
"emailAddress": "jane@example.com",
"displayName": "Jane Citizen",
"name": "jcitizen",
"id": 101,
"type": "NORMAL",
"active": true
},
"settings": {
"capacity": 60,
"fillRate": 5
}
}Retrieves the user-specific rate limit settings for the given user.
To call this resource, the user must be authenticated and either have ADMIN permission or be the same user as the one whose settings are requested. A user with ADMIN permission cannot get the settings of a user with SYS_ADMIN permission.
Forge and OAuth2 apps cannot access this REST resource.
string
RequiredA response containing the user-specific rate limit settings for the given user.
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/admin/rate-limit/settings/users/{userSlug}' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
"whitelisted": true,
"user": {
"slug": "jcitizen",
"emailAddress": "jane@example.com",
"displayName": "Jane Citizen",
"name": "jcitizen",
"id": 101,
"type": "NORMAL",
"active": true
},
"settings": {
"capacity": 60,
"fillRate": 5
}
}Sets the given rate limit settings for the given user.
The authenticated user must have ADMIN permission to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
Requiredobject
boolean
A response containing the updated user settings
1
2
3
4
5
6
7
8
9
10
11
curl --request PUT \
--url 'http://{baseurl}/rest/api/latest/admin/rate-limit/settings/users/{userSlug}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"settings": {
"capacity": 60,
"fillRate": 5
},
"whitelisted": true
}'1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
"whitelisted": true,
"user": {
"slug": "jcitizen",
"emailAddress": "jane@example.com",
"displayName": "Jane Citizen",
"name": "jcitizen",
"id": 101,
"type": "NORMAL",
"active": true
},
"settings": {
"capacity": 60,
"fillRate": 5
}
}Deletes the user-specific rate limit settings for the given user.
The authenticated user must have ADMIN permission to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
RequiredAn empty response indicating that the user settings have been deleted.
any
1
2
3
curl --request DELETE \
--url 'http://{baseurl}/rest/api/latest/admin/rate-limit/settings/users/{userSlug}' \
--header 'Accept: application/json'Retrieve a page of users.
The authenticated user must have the LICENSED_USER permission to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
number
number
A page of users.
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/admin/users' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
"values": [
{
"directoryName": "Bitbucket Internal Directory",
"lastAuthenticationTimestamp": 1368145580548,
"deletable": true,
"mutableDetails": true,
"mutableGroups": true,
"slug": "jcitizen",
"emailAddress": "jane@example.com",
"displayName": "Jane Citizen",
"name": "jcitizen",
"id": 101,
"type": "NORMAL",
"active": true
}
],
"size": 1,
"isLastPage": true,
"nextPageStart": 2154,
"start": 2154,
"limit": 25
}Update a user's details.
The authenticated user must have the ADMIN permission to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
string
string
The updated user.
1
2
3
4
5
6
7
8
9
curl --request PUT \
--url 'http://{baseurl}/rest/api/latest/admin/users' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"displayName": "Jane Citizen",
"email": "jane@example.com",
"name": "jcitizen"
}'1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
"directoryName": "Bitbucket Internal Directory",
"lastAuthenticationTimestamp": 1368145580548,
"deletable": true,
"mutableDetails": true,
"mutableGroups": true,
"slug": "jcitizen",
"emailAddress": "jane@example.com",
"displayName": "Jane Citizen",
"name": "jcitizen",
"id": 101,
"type": "NORMAL",
"active": true
}Creates a new user from the assembled query parameters.
The default group can be used to control initial permissions for new users, such as granting users the ability to login or providing read access to certain projects or repositories. If the user is not added to the default group, they may not be able to login after their account is created until explicit permissions are configured.
The authenticated user must have the ADMIN permission to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
Requiredstring
boolean
string
Requiredstring
Requiredboolean
The user was successfully created.
any
1
2
3
curl --request POST \
--url 'http://{baseurl}/rest/api/latest/admin/users?emailAddress={emailAddress}&displayName={displayName}&name={name}' \
--header 'Accept: application/json'Deletes the specified user, removing them from the system. This also removes any permissions that may have been granted to the user.
A user may not delete themselves, and a user with ADMIN permissions may not delete a user with SYS_ADMINpermissions.
The authenticated user must have the ADMIN permission to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
RequiredThe deleted user.
1
2
3
curl --request DELETE \
--url 'http://{baseurl}/rest/api/latest/admin/users?name={name}' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
"directoryName": "Bitbucket Internal Directory",
"lastAuthenticationTimestamp": 1368145580548,
"deletable": true,
"mutableDetails": true,
"mutableGroups": true,
"slug": "jcitizen",
"emailAddress": "jane@example.com",
"displayName": "Jane Citizen",
"name": "jcitizen",
"id": 101,
"type": "NORMAL",
"active": true
}Deprecated since 2.10. Use /rest/users/add-groups instead.
Add a user to a group. This is very similar to groups/add-user, but with the context and itemName attributes of the supplied request entity reversed. On the face of it this may appear redundant, but it facilitates a specific UI component in Stash.
In the request entity, the context attribute is the user and the itemName is the group.
The authenticated user must have the ADMIN permission to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
string
The user was added to the group
any
1
2
3
4
5
6
7
8
curl --request POST \
--url 'http://{baseurl}/rest/api/latest/admin/users/add-group' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"context": "group_a",
"itemName": "user_a"
}'Add a user to one or more groups.
The authenticated user must have the ADMIN permission to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
array<string>
Requiredstring
The user was added to all the groups
any
1
2
3
4
5
6
7
8
9
10
11
curl --request POST \
--url 'http://{baseurl}/rest/api/latest/admin/users/add-groups' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"groups": [
"group_a",
"group_b"
],
"user": "user"
}'Clears any CAPTCHA challenge that may constrain the user with the supplied username when they authenticate. Additionally any counter or metric that contributed towards the user being issued the CAPTCHA challenge (for instance too many consecutive failed logins) will also be reset.
The authenticated user must have the ADMIN permission to call this resource, and may not clear the CAPTCHA of a user with greater permissions than themselves.
Forge and OAuth2 apps cannot access this REST resource.
string
RequiredThe CAPTCHA was successfully cleared.
any
1
2
3
curl --request DELETE \
--url 'http://{baseurl}/rest/api/latest/admin/users/captcha?name={name}' \
--header 'Accept: application/json'Update a user's password.
The authenticated user must have the ADMIN permission to call this resource, and may not update the password of a user with greater permissions than themselves.
Forge and OAuth2 apps cannot access this REST resource.
string
string
string
The user's password was successfully updated.
any
1
2
3
4
5
6
7
8
9
curl --request PUT \
--url 'http://{baseurl}/rest/api/latest/admin/users/credentials' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"name": "jcitizen",
"password": "my-secret-password",
"passwordConfirm": "my-secret-password"
}'Validate if a user can be erased.
A username is only valid for erasure if it exists as the username of a deleted user. This endpoint will return an appropriate error response if the supplied username is invalid for erasure.
This endpoint does not perform the actual user erasure, and will not modify the application in any way.
The authenticated user must have the ADMIN permission to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
Requiredthe user is erasable
any
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/admin/users/erasure?name={name}' \
--header 'Accept: application/json'Erases personally identifying user data for a deleted user.
References in the application to the original username will be either removed or updated to a new non-identifying username. Refer to the support guide for details about what data is and isn't erased.
User erasure can only be performed on a deleted user. If the user has not been deleted first then this endpoint will return a bad request and no erasure will be performed.
Erasing user data is irreversible and may lead to a degraded user experience. This method should not be used as part of a standard user deletion and cleanup process.
Plugins can participate in user erasure by defining a <user-erasure-handler> module. If one or more plugin modules fail, an error summary of the failing modules is returned.
The authenticated user must have the ADMIN permission to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
RequiredThe identifier of the erased user.
1
2
3
curl --request POST \
--url 'http://{baseurl}/rest/api/latest/admin/users/erasure?name={name}' \
--header 'Accept: application/json'1
2
3
{
"newIdentifier": "user-123ab"
}Retrieves a list of users that are not members of a specified group.
The authenticated user must have the LICENSED_USER permission to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
string
Requirednumber
number
A page of users.
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/admin/users/more-members?context={context}' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
"values": [
{
"directoryName": "Bitbucket Internal Directory",
"lastAuthenticationTimestamp": 1368145580548,
"deletable": true,
"mutableDetails": true,
"mutableGroups": true,
"slug": "jcitizen",
"emailAddress": "jane@example.com",
"displayName": "Jane Citizen",
"name": "jcitizen",
"id": 101,
"type": "NORMAL",
"active": true
}
],
"size": 1,
"isLastPage": true,
"nextPageStart": 2154,
"start": 2154,
"limit": 25
}Retrieves a list of groups the specified user is not a member of.
The authenticated user must have the LICENSED_USER permission to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
string
Requirednumber
number
A page of groups.
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/admin/users/more-non-members?context={context}' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
10
11
12
13
{
"values": [
{
"deletable": true,
"name": "group-a"
}
],
"size": 1,
"isLastPage": true,
"nextPageStart": 2154,
"start": 2154,
"limit": 25
}Remove a user from a group. This is very similar to groups/remove-user, but with the context and itemName attributes of the supplied request entity reversed. On the face of it this may appear redundant, but it facilitates a specific UI component in Stash.
In the request entity, the context attribute is the user and the itemName is the group.
The authenticated user must have the ADMIN permission to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
string
The user was removed from the group.
any
1
2
3
4
5
6
7
8
curl --request POST \
--url 'http://{baseurl}/rest/api/latest/admin/users/remove-group' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"context": "group_a",
"itemName": "user_a"
}'Rename a user.
The authenticated user must have the ADMIN permission to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
string
The renamed user.
1
2
3
4
5
6
7
8
curl --request POST \
--url 'http://{baseurl}/rest/api/latest/admin/users/rename' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"name": "jcitizen",
"newName": "jcitizen-new"
}'1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
"directoryName": "Bitbucket Internal Directory",
"lastAuthenticationTimestamp": 1368145580548,
"deletable": true,
"mutableDetails": true,
"mutableGroups": true,
"slug": "jcitizen",
"emailAddress": "jane@example.com",
"displayName": "Jane Citizen",
"name": "jcitizen",
"id": 101,
"type": "NORMAL",
"active": true
}Retrieve version information and other application properties. No authentication is required to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
This request has no parameters.
The application properties
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/application-properties' \
--header 'Accept: application/json'1
2
3
4
5
6
{
"buildDate": "1358897885952000",
"displayName": "Example.com Bitbucket",
"version": "2.1.0",
"buildNumber": "20220123103656677"
}Returns the build capabilities of this instance
Forge and OAuth2 apps cannot access this REST resource.
This request has no parameters.
capabilities
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/build/capabilities' \
--header 'Accept: application/json'1
2
3
4
5
{
"buildStatus": [
"richBuildStatus"
]
}Retrieves a page of suggestions for pull requests that the currently authenticated user may wish to raise. Such suggestions are based on ref changes occurring and so contain the ref change that prompted the suggestion plus the time the change event occurred. Changes will be returned in descending order based on the time the change that prompted the suggestion occurred. Note that although the response is a page object, the interface does not support paging, however a limit can be applied to the size of the returned page.
Forge and OAuth2 apps cannot access this REST resource.
string
string
A page of pull requests that match the search criteria.
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/dashboard/pull-request-suggestions' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
{
"values": [
{
"changeTme": 1359075920,
"refChange": {
"fromHash": "6053a1eaa1c009dd11092d09a72f3c41af1b59ad",
"toHash": "d6edcbf924697ab811a867421dab60d954ccad99",
"refId": "refs/heads/master",
"type": "ADD",
"ref": {
"displayId": "master",
"id": "refs/heads/master",
"type": "BRANCH"
}
},
"fromRef": {
"displayId": "master",
"id": "refs/heads/master",
"type": "BRANCH"
},
"toRef": {
"displayId": "master",
"id": "refs/heads/master",
"type": "BRANCH"
},
"repository": {
"relatedLinks": {},
"scmId": "git",
"hierarchyId": "e3c939f9ef4a7fae272e",
"statusMessage": "Available",
"partition": 2154,
"origin": {
"relatedLinks": {},
"scmId": "git",
"hierarchyId": "e3c939f9ef4a7fae272e",
"statusMessage": "Available",
"partition": 2154,
"archived": true,
"forkable": true,
"defaultBranch": "main",
"slug": "my-repo",
"name": "My repo",
"public": true,
"id": 2154,
"state": "AVAILABLE",
"description": "My repo description",
"scope": "REPOSITORY"
},
"archived": true,
"forkable": true,
"defaultBranch": "main",
"slug": "my-repo",
"name": "My repo",
"public": true,
"id": 2154,
"state": "AVAILABLE",
"description": "My repo description",
"scope": "REPOSITORY"
}
}
],
"size": 1,
"isLastPage": true,
"nextPageStart": 2154,
"start": 2154,
"limit": 25
}Retrieve a page of pull requests where the current authenticated user is involved as either a reviewer, author or a participant. The request may be filtered by pull request state, role or participant status.
Forge and OAuth2 apps cannot access this REST resource.
string
string
string
string
string
number
number
A page of pull requests that match the search criteria.
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/dashboard/pull-requests' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
{
"values": [
{
"updatedDate": 14490759200,
"createdDate": 13590759200,
"closedDate": 19990759200,
"fromRef": {
"latestCommit": "babecafebabecafebabecafebabecafebabecafe",
"displayId": "feature-ABC-1233",
"id": "refs/heads/feature-ABC-123",
"type": "BRANCH",
"repository": {
"relatedLinks": {},
"scmId": "git",
"hierarchyId": "e3c939f9ef4a7fae272e",
"statusMessage": "Available",
"partition": 2154,
"origin": {
"relatedLinks": {},
"scmId": "git",
"hierarchyId": "e3c939f9ef4a7fae272e",
"statusMessage": "Available",
"partition": 2154,
"archived": true,
"forkable": true,
"defaultBranch": "main",
"slug": "my-repo",
"name": "My repo",
"public": true,
"id": 2154,
"state": "AVAILABLE",
"description": "My repo description",
"scope": "REPOSITORY"
},
"archived": true,
"forkable": true,
"defaultBranch": "main",
"slug": "my-repo",
"name": "My repo",
"public": true,
"id": 2154,
"state": "AVAILABLE",
"description": "My repo description",
"scope": "REPOSITORY"
}
},
"participants": [
{
"lastReviewedCommit": "7549846524f8aed2bd1c0249993ae1bf9d3c9998",
"approved": true,
"user": {
"slug": "jcitizen",
"emailAddress": "jane@example.com",
"displayName": "Jane Citizen",
"name": "jcitizen",
"id": 101,
"type": "NORMAL",
"active": true
},
"status": "UNAPPROVED",
"role": "AUTHOR"
}
],
"reviewers": [
{
"lastReviewedCommit": "7549846524f8aed2bd1c0249993ae1bf9d3c9998",
"approved": true,
"user": {
"slug": "jcitizen",
"emailAddress": "jane@example.com",
"displayName": "Jane Citizen",
"name": "jcitizen",
"id": 101,
"type": "NORMAL",
"active": true
},
"status": "UNAPPROVED",
"role": "AUTHOR"
}
],
"toRef": {
"latestCommit": "babecafebabecafebabecafebabecafebabecafe",
"displayId": "feature-ABC-1233",
"id": "refs/heads/feature-ABC-123",
"type": "BRANCH",
"repository": {
"relatedLinks": {},
"scmId": "git",
"hierarchyId": "e3c939f9ef4a7fae272e",
"statusMessage": "Available",
"partition": 2154,
"origin": {
"relatedLinks": {},
"scmId": "git",
"hierarchyId": "e3c939f9ef4a7fae272e",
"statusMessage": "Available",
"partition": 2154,
"archived": true,
"forkable": true,
"defaultBranch": "main",
"slug": "my-repo",
"name": "My repo",
"public": true,
"id": 2154,
"state": "AVAILABLE",
"description": "My repo description",
"scope": "REPOSITORY"
},
"archived": true,
"forkable": true,
"defaultBranch": "main",
"slug": "my-repo",
"name": "My repo",
"public": true,
"id": 2154,
"state": "AVAILABLE",
"description": "My repo description",
"scope": "REPOSITORY"
}
},
"version": 2154,
"closed": true,
"open": true,
"id": 1,
"state": "DECLINED",
"locked": true,
"description": "It is a kludge, but put the tuple from the database in the cache.",
"title": "Talking Nerdy"
}
],
"size": 1,
"isLastPage": true,
"nextPageStart": 2154,
"start": 2154,
"limit": 25
}Returns the Deployment capabilities of this instance
Forge and OAuth2 apps cannot access this REST resource.
This request has no parameters.
capabilities
any
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/deployment/capabilities' \
--header 'Accept: application/json'Retrieve a page of group names.
The authenticated user must have LICENSED_USER permission or higher to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
number
number
A page of group names.
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/groups' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
10
{
"values": [
"<string>"
],
"size": 1,
"isLastPage": true,
"nextPageStart": 2154,
"start": 2154,
"limit": 25
}Create a new hook script.
This endpoint requires SYS_ADMIN permission.
Forge and OAuth2 apps cannot access this REST resource.
The multipart form data containing the hook script
string
string
string
string
The newly created hook script.
1
2
3
curl --request POST \
--url 'http://{baseurl}/rest/api/latest/hook-scripts' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
10
{
"updatedDate": "<string>",
"createdDate": "<string>",
"version": 2154,
"name": "<string>",
"id": 2154,
"type": "POST",
"description": "<string>",
"pluginKey": "<string>"
}Retrieves a hook script by ID.
Forge and OAuth2 apps cannot access this REST resource.
string
RequiredThe hook script.
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/hook-scripts/{scriptId}' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
10
{
"updatedDate": "<string>",
"createdDate": "<string>",
"version": 2154,
"name": "<string>",
"id": 2154,
"type": "POST",
"description": "<string>",
"pluginKey": "<string>"
}Updates a hook script.
This endpoint requires SYS_ADMIN permission.
Forge and OAuth2 apps cannot access this REST resource.
string
RequiredThe multipart form data containing the hook script
string
string
string
The updated hook script.
1
2
3
curl --request PUT \
--url 'http://{baseurl}/rest/api/latest/hook-scripts/{scriptId}' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
10
{
"updatedDate": "<string>",
"createdDate": "<string>",
"version": 2154,
"name": "<string>",
"id": 2154,
"type": "POST",
"description": "<string>",
"pluginKey": "<string>"
}Deletes a registered hook script.
This endpoint requires SYS_ADMIN permission.
Forge and OAuth2 apps cannot access this REST resource.
string
RequiredThe hook script was deleted.
any
1
2
3
curl --request DELETE \
--url 'http://{baseurl}/rest/api/latest/hook-scripts/{scriptId}' \
--header 'Accept: application/json'Retrieves the hook script content.
This endpoint requires SYS_ADMIN permission.
Forge and OAuth2 apps cannot access this REST resource.
string
RequiredThe hook script content.
any
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/hook-scripts/{scriptId}/content' \
--header 'Accept: application/json'Retrieve the avatar for the project matching the supplied moduleKey.
Forge and OAuth2 apps cannot access this REST resource.
string
Requiredstring
The avatar of the project matching the supplied moduleKey.
any
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/hooks/{hookKey}/avatar' \
--header 'Accept: application/json'Forge and OAuth2 apps cannot access this REST resource.
string
integer
integer
default response
any
1
2
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/inbox/pull-requests'Forge and OAuth2 apps cannot access this REST resource.
This request has no parameters.
default response
any
1
2
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/inbox/pull-requests/count'Returns a paged response of all the labels in the system. The user needs to be authenticated to use this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
number
number
Page of returned labels.
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/labels' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
10
11
12
{
"values": [
{
"name": "labelName"
}
],
"size": 1,
"isLastPage": true,
"nextPageStart": 2154,
"start": 2154,
"limit": 25
}Returns a label. The user needs to be authenticated to use this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
RequiredThe label.
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/labels/{labelName}' \
--header 'Accept: application/json'1
2
3
{
"name": "labelName"
}Returns a page of labelables for a given label. Only labelables that the authenticated user has view access to will be returned.
Forge and OAuth2 apps cannot access this REST resource.
string
Requiredstring
number
number
The page of labelables.
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/labels/{labelName}/labeled' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
{
"values": [
{
"labelableType": "REPOSITORY",
"relatedLinks": {},
"scmId": "git",
"hierarchyId": "e3c939f9ef4a7fae272e",
"statusMessage": "Available",
"partition": 2154,
"origin": {
"relatedLinks": {},
"scmId": "git",
"hierarchyId": "e3c939f9ef4a7fae272e",
"statusMessage": "Available",
"partition": 2154,
"archived": true,
"forkable": true,
"defaultBranch": "main",
"slug": "my-repo",
"name": "My repo",
"public": true,
"id": 2154,
"state": "AVAILABLE",
"description": "My repo description",
"scope": "REPOSITORY"
},
"archived": true,
"forkable": true,
"defaultBranch": "main",
"slug": "my-repo",
"name": "My repo",
"public": true,
"id": 2154,
"state": "AVAILABLE",
"description": "My repo description",
"scope": "REPOSITORY"
}
],
"size": 1,
"isLastPage": true,
"nextPageStart": 2154,
"start": 2154,
"limit": 25
}Retrieve the current log level for a given logger.
The authenticated user must have ADMIN permission or higher to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
RequiredThe log level of the logger.
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/logs/logger/{loggerName}' \
--header 'Accept: application/json'1
2
3
{
"logLevel": "DEBUG"
}Set the current log level for a given logger.
The authenticated user must have ADMIN permission or higher to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
Requiredstring
RequiredThe log level was successfully changed.
any
1
2
3
curl --request PUT \
--url 'http://{baseurl}/rest/api/latest/logs/logger/{loggerName}/{levelName}' \
--header 'Accept: application/json'Retrieve the current log level for the root logger.
The authenticated user must have ADMIN permission or higher to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
This request has no parameters.
The log level of the logger.
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/logs/rootLogger' \
--header 'Accept: application/json'1
2
3
{
"logLevel": "DEBUG"
}Set the current log level for the root logger.
The authenticated user must have ADMIN permission or higher to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
RequiredThe log level was successfully changed.
any
1
2
3
curl --request PUT \
--url 'http://{baseurl}/rest/api/latest/logs/rootLogger/{levelName}' \
--header 'Accept: application/json'Preview generated HTML for the given markdown content. Only authenticated users may call this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
string
string
string
string
The rendered markdown.
1
2
3
curl --request POST \
--url 'http://{baseurl}/rest/api/latest/markup/preview' \
--header 'Accept: application/json'1
2
3
{
"html": "<h1>Hello World!</h1>"
}Starts a background job that exports the selected repositories.
Only 2 concurrent exports are supported per cluster node. If a request ends up on a node that is already running that many export jobs, the request will be rejected and an error returned.
The response includes a description of the job that has been started, and its ID can be used to query these details again, including the current progress, warnings and errors that occurred while processing the job, and to interrupt and cancel the execution of this job.
The request to start an export is similar to the one for previewing an export. Additionally, it accepts an optional parameter, exportLocation, which can be used to specify a relative path within data/migration/export in the shared home directory. No locations outside of that directory will be accepted for exports.
There are essentially three ways to select repositories for export. Regardless of which you use, a few general rules apply:
Now, a single repository can be selected like this:
1 2 3 4 5 6 7 8{ "projectKey": "PRJ", "slug": "my-repo" }
Second, all repositories in a specific project can be selected like this:
1 2 3 4 5 6 7 8{ "projectKey": "PRJ", "slug": *" }
And third, all projects and repositories in the system would be selected like this:
1 2 3 4 5 6 7 8{ "projectKey": "*", "slug": *" }
The authenticated user must have ADMIN permission or higher to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
The request
string
object
RequiredDetails about the export job.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
curl --request POST \
--url 'http://{baseurl}/rest/api/latest/migration/exports' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"exportLocation": "example/sub/directory",
"repositoriesRequest": {
"includes": [
{
"projectKey": "PRJ",
"slug": "my-repo"
}
]
}
}'1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
"endDate": 1497657603000,
"startDate": 1497657601000,
"nodeId": "1bec7499-077a-4b58-b27c-996a9c2187a4",
"initiator": {
"slug": "jcitizen",
"emailAddress": "jane@example.com",
"displayName": "Jane Citizen",
"name": "jcitizen",
"id": 101,
"type": "NORMAL",
"active": true
},
"updatedDate": 1497657603000,
"progress": {
"percentage": 42,
"message": "Working on it..."
},
"id": 1,
"state": "INITIALISING",
"type": "com.atlassian.bitbucket.migration.export"
}Enumerates the projects and repositories that would be exported for a given export request.
All affected repositories will be enumerated explicitly, and while projects are listed as individual items in responses from this endpoint, their presence does not imply that all their repositories are included.
While this endpoint can be used to verify that all selectors in the request apply as intended, it should be noted that a subsequent, actual export might contain a different set of repositories, as they might have been added or deleted in the meantime.
Note that the overall response from this endpoint can become very large when a lot of repositories end up in the selection. This is why the server is streaming the response while it is being generated (as opposed to creating it in memory and then sending it all at once) and it can be consumed in a streaming way, too.
Also, due to the potential size of the response, projects and repositories are listed with fewer details than in other REST responses.
For a more detailed description of selectors, see the endpoint documentation for starting an export.
The authenticated user must have ADMIN permission or higher to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
the export request
string
object
RequiredThe effectively selected projects and repositories.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
curl --request POST \
--url 'http://{baseurl}/rest/api/latest/migration/exports/preview' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"exportLocation": "example/sub/directory",
"repositoriesRequest": {
"includes": [
{
"projectKey": "PRJ",
"slug": "my-repo"
}
]
}
}'1
2
3
4
5
{
"scopes": [
{}
]
}Gets the details, including the current status and progress, of the export job identified by the given ID.
The authenticated user must have ADMIN permission or higher to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
RequiredThe job, including status and progress information.
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/migration/exports/{jobId}' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
"endDate": 1497657603000,
"startDate": 1497657601000,
"nodeId": "1bec7499-077a-4b58-b27c-996a9c2187a4",
"initiator": {
"slug": "jcitizen",
"emailAddress": "jane@example.com",
"displayName": "Jane Citizen",
"name": "jcitizen",
"id": 101,
"type": "NORMAL",
"active": true
},
"updatedDate": 1497657603000,
"progress": {
"percentage": 42,
"message": "Working on it..."
},
"id": 1,
"state": "INITIALISING",
"type": "com.atlassian.bitbucket.migration.export"
}Requests the cancellation of an export job.
The request to cancel a job will be processed successfully if the job is actually still running. If it has already finished (successfully or with errors) or if it has already been canceled before, then an error will be returned.
There might be a small delay between accepting the request and actually cancelling the job. In most cases, the delay will be close to instantaneously. In the unlikely case of communication issues across a cluster, it can however take a few seconds to cancel a job.
A client should always actively query the job status to confirm that a job has been successfully canceled.
The authenticated user must have ADMIN permission or higher to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
RequiredThe job has successfully been marked for cancellation
any
1
2
3
curl --request POST \
--url 'http://{baseurl}/rest/api/latest/migration/exports/{jobId}/cancel' \
--header 'Accept: application/json'Gets the messages generated by the job.
Without any filter, all messages will be returned, but the response can optionally be filtered for the following severities. The severity parameter can be repeated to include multiple severities in one response.
The authenticated user must have ADMIN permission or higher to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
Requiredstring
string
number
number
The messages generated by this job.
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/migration/exports/{jobId}/messages' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
"values": [
{
"createdDate": "<string>",
"subject": "job",
"severity": "INFO",
"id": "617",
"text": "Something of interest happened"
}
],
"size": 1,
"isLastPage": true,
"nextPageStart": 2154,
"start": 2154,
"limit": 25
}Starts a background job that imports the specified archive.
Only 1 import at a time is supported per cluster. If another request is made while an import is already running, the request will be rejected and an error returned.
The path in the request must point to a valid archive file. The file must be located within the data/migration/import directory in the shared home directory.
The authenticated user must have ADMIN permission or higher to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
The request
string
Details about the export job.
1
2
3
4
5
6
7
curl --request POST \
--url 'http://{baseurl}/rest/api/latest/migration/imports' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"archivePath": "Bitbucket_export_1.tar"
}'1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
"endDate": 1497657603000,
"startDate": 1497657601000,
"nodeId": "1bec7499-077a-4b58-b27c-996a9c2187a4",
"initiator": {
"slug": "jcitizen",
"emailAddress": "jane@example.com",
"displayName": "Jane Citizen",
"name": "jcitizen",
"id": 101,
"type": "NORMAL",
"active": true
},
"updatedDate": 1497657603000,
"progress": {
"percentage": 42,
"message": "Working on it..."
},
"id": 1,
"state": "INITIALISING",
"type": "com.atlassian.bitbucket.migration.export"
}Gets the details, including the current status and progress, of the import job identified by the given ID.
The authenticated user must have ADMIN permission or higher to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
RequiredThe job, including status and progress information.
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/migration/imports/{jobId}' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
"endDate": 1497657603000,
"startDate": 1497657601000,
"nodeId": "1bec7499-077a-4b58-b27c-996a9c2187a4",
"initiator": {
"slug": "jcitizen",
"emailAddress": "jane@example.com",
"displayName": "Jane Citizen",
"name": "jcitizen",
"id": 101,
"type": "NORMAL",
"active": true
},
"updatedDate": 1497657603000,
"progress": {
"percentage": 42,
"message": "Working on it..."
},
"id": 1,
"state": "INITIALISING",
"type": "com.atlassian.bitbucket.migration.export"
}Requests the cancellation of an import job.
The request to cancel a job will be processed successfully if the job is actually still running. If it has already finished (successfully or with errors) or if it has already been canceled before, then an error will be returned.
Note that import jobs are not canceled as instantaneously as export jobs. Rather, once the request has been accepted, there are a number of checkpoints at which the job will actually apply it and stop. This is to keep the system in a reasonably consistent state:
A client should always actively query the job status to confirm that a job has been successfully canceled.
The authenticated user must have ADMIN permission or higher to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
RequiredThe job has successfully been marked for cancellation.
any
1
2
3
curl --request POST \
--url 'http://{baseurl}/rest/api/latest/migration/imports/{jobId}/cancel' \
--header 'Accept: application/json'Gets the messages generated by the job.
Without any filter, all messages will be returned, but the response can optionally be filtered for the following severities. The severity parameter can be repeated to include multiple severities in one response.
The authenticated user must have ADMIN permission or higher to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
Requiredstring
string
number
number
The messages generated by this job.
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/migration/imports/{jobId}/messages' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
"values": [
{
"createdDate": "<string>",
"subject": "job",
"severity": "INFO",
"id": "617",
"text": "Something of interest happened"
}
],
"size": 1,
"isLastPage": true,
"nextPageStart": 2154,
"start": 2154,
"limit": 25
}Starts a background job that migrates selected projects/repositories to Mesh.
Only 1 job is supported per cluster.
The response includes a description of the job that has been started, and its ID can be used to query these details again, including the current progress, and to interrupt and cancel the execution of this job.
The request to start a migration is similar to the one for previewing a migration.
There are essentially three ways to select repositories for migration. Regardless of which you use, a few general rules apply:
1- You can supply a list of repository IDs and project IDs. The selection will be additive. All repositories in the system are migrated if both lists are empty. - Repositories that are selected more than once due to overlapping IDs will be de-duplicated and effectively migrated only once. - For every selected repository, its full fork hierarchy will be considered selected, even if parts of that hierarchy would otherwise not be matched by the provided IDs. For example, when you explicitly select a single repository only, but that repository is a fork, then its origin will be migrated too.
Now, a single repository can be selected like this:
1 2 3 4{ "repositoryIds": [1] }
Multiple repositories can be selected like this:
1 2 3 4{ "repositoryIds": [1, 2] }
Second, all repositories in a specific project can be selected like this:
1 2 3 4{ "projectIds": [1] }
And third, all projects and repositories in the system would be selected like this:
1 2 3 4 5{ "projectIds": [], "repositoryIds": [] }
The authenticated user must have SYS_ADMIN permission to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
boolean
object
array<integer>
array<integer>
The started job
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
curl --request POST \
--url 'http://{baseurl}/rest/api/latest/migration/mesh' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"all": true,
"maxBytesPerSecond": {
"asLong": 2154,
"present": true
},
"projectIds": [
2154
],
"repositoryIds": [
2154
]
}'1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
"endDate": 1497657603000,
"startDate": 1497657601000,
"nodeId": "1bec7499-077a-4b58-b27c-996a9c2187a4",
"initiator": {
"slug": "jcitizen",
"emailAddress": "jane@example.com",
"displayName": "Jane Citizen",
"name": "jcitizen",
"id": 101,
"type": "NORMAL",
"active": true
},
"updatedDate": 1497657603000,
"progress": {
"percentage": 42,
"message": "Working on it..."
},
"id": 1,
"state": "INITIALISING",
"type": "com.atlassian.bitbucket.migration.export"
}Enumerates the projects and repositories that would be migrated for a given request.
All affected repositories will be enumerated explicitly, and while projects are listed as individual items in responses from this endpoint, their presence does not imply that all their repositories are included.
While this endpoint can be used to verify that all selectors in the request apply as intended, it should be noted that a subsequent, actual export might contain a different set of repositories, as they might have been added or deleted in the meantime.
Note that the overall response from this endpoint can become very large when a lot of repositories end up in the selection. This is why the server is streaming the response while it is being generated (as opposed to creating it in memory and then sending it all at once) and it can be consumed in a streaming way, too.
Also, due to the potential size of the response, projects and repositories are listed with fewer details than in other REST responses.
The authenticated user must have SYS_ADMIN permission to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
The export request
boolean
object
array<integer>
array<integer>
Enumeration of projects and repositories that would be migrated for a given request.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
curl --request POST \
--url 'http://{baseurl}/rest/api/latest/migration/mesh/preview' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"all": true,
"maxBytesPerSecond": {
"asLong": 2154,
"present": true
},
"projectIds": [
2154
],
"repositoryIds": [
2154
]
}'1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
{
"repositories": [
{
"relatedLinks": {},
"scmId": "git",
"hierarchyId": "e3c939f9ef4a7fae272e",
"statusMessage": "Available",
"partition": 2154,
"origin": {
"relatedLinks": {},
"scmId": "git",
"hierarchyId": "e3c939f9ef4a7fae272e",
"statusMessage": "Available",
"partition": 2154,
"archived": true,
"forkable": true,
"defaultBranch": "main",
"slug": "my-repo",
"name": "My repo",
"public": true,
"id": 2154,
"state": "AVAILABLE",
"description": "My repo description",
"scope": "REPOSITORY"
},
"archived": true,
"forkable": true,
"defaultBranch": "main",
"slug": "my-repo",
"name": "My repo",
"public": true,
"id": 2154,
"state": "AVAILABLE",
"description": "My repo description",
"scope": "REPOSITORY"
}
]
}Searches for repositories in the system matching the specified criteria and enriches their MeshMigrationQueueState migration state if a migration is currently in progress.
The currently active migration can optionally be specified by passing a migrationId, if known. If this isn't passed, an attempt is made to locate the active migration and its ID is used.
If a migration is currently active, only repositories that are a part of the migration are filtered and returned. Otherwise, all repositories in the systems are filtered and returned.
Filtering by state is ignored when no migration is currently in progress. In such a case, results are not enriched with their MeshMigrationQueueState migration state.
The authenticated user must have SYS_ADMIN permission to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
string
string
string
string
number
number
A page of repositories matching the specified criteria.
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/migration/mesh/repos' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
{
"values": [
{
"migrationState": "QUEUED",
"repository": {
"relatedLinks": {},
"scmId": "git",
"hierarchyId": "e3c939f9ef4a7fae272e",
"statusMessage": "Available",
"partition": 2154,
"origin": {
"relatedLinks": {},
"scmId": "git",
"hierarchyId": "e3c939f9ef4a7fae272e",
"statusMessage": "Available",
"partition": 2154,
"archived": true,
"forkable": true,
"defaultBranch": "main",
"slug": "my-repo",
"name": "My repo",
"public": true,
"id": 2154,
"state": "AVAILABLE",
"description": "My repo description",
"scope": "REPOSITORY"
},
"archived": true,
"forkable": true,
"defaultBranch": "main",
"slug": "my-repo",
"name": "My repo",
"public": true,
"id": 2154,
"state": "AVAILABLE",
"description": "My repo description",
"scope": "REPOSITORY"
}
}
],
"size": 1,
"isLastPage": true,
"nextPageStart": 2154,
"start": 2154,
"limit": 25
}Retrieve a page of Mesh migration job summaries. Jobs are ordered by when they were started, newest first.
The authenticated user must have SYS_ADMIN permission to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
number
number
The summary of the migration job.
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/migration/mesh/summaries' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
"values": [
{
"jobId": 2154,
"endTime": 1331038800000,
"maxBandwidth": 2154,
"progress": 53,
"queue": {},
"state": "RUNNING",
"startTime": 1331038800000
}
],
"size": 1,
"isLastPage": true,
"nextPageStart": 2154,
"start": 2154,
"limit": 25
}Gets the summary, including the queue status and progress, of the currently active Mesh migration job.
The authenticated user must have SYS_ADMIN permission to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
This request has no parameters.
The summary of the currently active migration job.
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/migration/mesh/summary' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
{
"jobId": 2154,
"endTime": 1331038800000,
"maxBandwidth": 2154,
"progress": 53,
"queue": {},
"state": "RUNNING",
"startTime": 1331038800000
}Gets the details, including the current status and progress, of the job identified by the given ID.
The authenticated user must have SYS_ADMIN permission to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
RequiredThe details of the migration job.
any
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/migration/mesh/{jobId}' \
--header 'Accept: application/json'Requests the cancellation of a migration job.
The request to cancel a job will be processed successfully if the job is actually still running. If it has already finished (successfully or with errors) or if it has already been canceled before, then an error will be returned.
There might be a small delay between accepting the request and actually cancelling the job. In most cases, the delay will be close to instantaneously. In the unlikely case of communication issues across a cluster, it can however take a few seconds to cancel a job.
A client should always actively query the job status to confirm that a job has been successfully canceled.
The authenticated user must have SYS_ADMIN permission to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
RequiredThe migration job was successfully marked for cancellation.
any
1
2
3
curl --request POST \
--url 'http://{baseurl}/rest/api/latest/migration/mesh/{jobId}/cancel' \
--header 'Accept: application/json'Gets the messages generated by the job.
Without any filter, all messages will be returned, but the response can optionally be filtered for the following severities. The severity parameter can be repeated to include multiple severities in one response.
1 2 3- INFO - WARN - ERROR
The authenticated user must have SYS_ADMIN permission to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
Requiredstring
string
number
number
The details of the migration job.
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/migration/mesh/{jobId}/messages' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
"values": [
{
"createdDate": "<string>",
"subject": "job",
"severity": "INFO",
"id": "617",
"text": "Something of interest happened"
}
],
"size": 1,
"isLastPage": true,
"nextPageStart": 2154,
"start": 2154,
"limit": 25
}Gets the summary, including the queue status and progress, of a Mesh migration job.
The authenticated user must have SYS_ADMIN permission to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
RequiredThe summary of the migration job.
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/migration/mesh/{jobId}/summary' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
{
"jobId": 2154,
"endTime": 1331038800000,
"maxBandwidth": 2154,
"progress": 53,
"queue": {},
"state": "RUNNING",
"startTime": 1331038800000
}Retrieve a page of recently accessed repositories for the currently authenticated user.
Repositories are ordered from most recently to least recently accessed.
Only authenticated users may call this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
number
number
A page of recently accessed repositories.
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/profile/recent/repos' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
{
"values": [
{
"relatedLinks": {},
"scmId": "git",
"hierarchyId": "e3c939f9ef4a7fae272e",
"statusMessage": "Available",
"partition": 2154,
"origin": {
"relatedLinks": {},
"scmId": "git",
"hierarchyId": "e3c939f9ef4a7fae272e",
"statusMessage": "Available",
"partition": 2154,
"archived": true,
"forkable": true,
"defaultBranch": "main",
"slug": "my-repo",
"name": "My repo",
"public": true,
"id": 2154,
"state": "AVAILABLE",
"description": "My repo description",
"scope": "REPOSITORY"
},
"archived": true,
"forkable": true,
"defaultBranch": "main",
"slug": "my-repo",
"name": "My repo",
"public": true,
"id": 2154,
"state": "AVAILABLE",
"description": "My repo description",
"scope": "REPOSITORY"
}
],
"size": 1,
"isLastPage": true,
"nextPageStart": 2154,
"start": 2154,
"limit": 25
}Retrieve a page of projects.
Only projects for which the authenticated user has the PROJECT_VIEW permission will be returned.
Forge and OAuth2 apps cannot access this REST resource.
string
string
number
number
A page of projects.
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/projects' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
"values": [
{
"avatar": "<string>",
"name": "My Cool Project",
"key": "PRJ",
"public": true,
"id": 2154,
"type": "NORMAL",
"description": "The description for my cool project",
"namespace": "<string>",
"scope": "PROJECT"
}
],
"size": 1,
"isLastPage": true,
"nextPageStart": 2154,
"start": 2154,
"limit": 25
}Create a new project.
To include a custom avatar for the project, the project definition should contain an additional attribute with the key avatar and the value a data URI containing Base64-encoded image data. The URI should be in the following format:
data:(content type, e.g. image/png);base64,(data)If the data is not Base64-encoded, or if a character set is defined in the URI, or the URI is otherwise invalid, project creation will fail.
The authenticated user must have PROJECT_CREATE permission to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
The project.
string
string
string
integer
object
The newly created project.
1
2
3
4
5
6
7
8
9
10
11
curl --request POST \
--url 'http://{baseurl}/rest/api/latest/projects' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"avatar": "<string>",
"avatarUrl": "<string>",
"key": "PRJ",
"id": 2154,
"links": {}
}'1
2
3
4
5
6
7
8
9
10
11
{
"avatar": "<string>",
"name": "My Cool Project",
"key": "PRJ",
"public": true,
"id": 2154,
"type": "NORMAL",
"description": "The description for my cool project",
"namespace": "<string>",
"scope": "PROJECT"
}Retrieve the project matching the supplied projectKey.
The authenticated user must have PROJECT_VIEW permission for the specified project to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
RequiredThe project matching the supplied projectKey.
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/projects/{projectKey}' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
10
11
{
"avatar": "<string>",
"name": "My Cool Project",
"key": "PRJ",
"public": true,
"id": 2154,
"type": "NORMAL",
"description": "The description for my cool project",
"namespace": "<string>",
"scope": "PROJECT"
}Update the project matching the projectKey supplied in the resource path.
To include a custom avatar for the updated project, the project definition should contain an additional attribute with the key avatar and the value a data URI containing Base64-encoded image data. The URI should be in the following format:
data:(content type, e.g. image/png);base64,(data)
If the data is not Base64-encoded, or if a character set is defined in the URI, or the URI is otherwise invalid, project creation will fail.
The authenticated user must have PROJECT_ADMIN permission for the specified project to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
RequiredProject parameters to update.
string
string
string
integer
object
The updated project. The project's key was not updated.
1
2
3
4
5
6
7
8
9
10
11
curl --request PUT \
--url 'http://{baseurl}/rest/api/latest/projects/{projectKey}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"avatar": "<string>",
"avatarUrl": "<string>",
"key": "PRJ",
"id": 2154,
"links": {}
}'1
2
3
4
5
6
7
8
9
10
11
{
"avatar": "<string>",
"name": "My Cool Project",
"key": "PRJ",
"public": true,
"id": 2154,
"type": "NORMAL",
"description": "The description for my cool project",
"namespace": "<string>",
"scope": "PROJECT"
}Delete the project matching the supplied projectKey.
The authenticated user must have PROJECT_ADMIN permission for the specified project to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
RequiredThe project matching the supplied projectKey was deleted.
any
1
2
3
curl --request DELETE \
--url 'http://{baseurl}/rest/api/latest/projects/{projectKey}' \
--header 'Accept: application/json'Retrieve the avatar for the project matching the supplied projectKey.
The authenticated user must have PROJECT_VIEW permission for the specified project to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
Requiredstring
The avatar of the project matching the supplied projectKey.
any
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/avatar.png' \
--header 'Accept: application/json'Update the avatar for the project matching the supplied projectKey.
This resource accepts POST multipart form data, containing a single image in a form-field named 'avatar'.
There are configurable server limits on both the dimensions (1024x1024 pixels by default) and uploaded file size (1MB by default). Several different image formats are supported, but PNG and JPEG are preferred due to the file size limit.
This resource has Cross-Site Request Forgery (XSRF) protection. To allow the request to pass the XSRF check the caller needs to send an X-Atlassian-Token HTTP header with the value no-check.
An example curl request to upload an image name 'avatar.png' would be: curl -X POST -u username:password -H "X-Atlassian-Token: no-check" http://example.com/rest/api/1.0/projects/STASH/avatar.png -F avatar=@avatar.png
The authenticated user must have PROJECT_ADMIN permission for the specified project to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
RequiredThe mutlipart form data containing the file.
string
The avatar was uploaded successfully.
any
1
2
3
curl --request POST \
--url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/avatar.png' \
--header 'Accept: application/json'Return a page of hook scripts configured for the specified project.
This endpoint requires PROJECT_ADMIN permission.
Forge and OAuth2 apps cannot access this REST resource.
string
Requirednumber
number
A page of hook scripts.
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/hook-scripts' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
{
"values": [
{
"script": {
"updatedDate": "<string>",
"createdDate": "<string>",
"version": 2154,
"name": "<string>",
"id": 2154,
"type": "POST",
"description": "<string>",
"pluginKey": "<string>"
},
"scope": {
"resourceId": 2,
"type": "GLOBAL"
},
"triggerIds": [
"<string>"
]
}
],
"size": 1,
"isLastPage": true,
"nextPageStart": 2154,
"start": 2154,
"limit": 25
}Creates/updates the hook script configuration for the provided hook script and project.
This endpoint requires PROJECT_ADMIN permission.
Forge and OAuth2 apps cannot access this REST resource.
string
Requiredstring
RequiredThe hook triggers for which the hook script should be run
array<string>
The updated hook script.
1
2
3
4
5
6
7
8
9
curl --request PUT \
--url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/hook-scripts/{scriptId}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"triggerIds": [
"<string>"
]
}'1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
"script": {
"updatedDate": "<string>",
"createdDate": "<string>",
"version": 2154,
"name": "<string>",
"id": 2154,
"type": "POST",
"description": "<string>",
"pluginKey": "<string>"
},
"scope": {
"resourceId": 2,
"type": "GLOBAL"
},
"triggerIds": [
"<string>"
]
}Removes the hook script from the set of hook scripts configured to run in all repositories under the project.
This endpoint requires PROJECT_ADMIN permission.
Forge and OAuth2 apps cannot access this REST resource.
string
Requiredstring
RequiredThe hook script was successfully deleted.
any
1
2
3
curl --request DELETE \
--url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/hook-scripts/{scriptId}' \
--header 'Accept: application/json'Retrieve a page of groups that have been granted at least one permission for the specified project.
The authenticated user must have PROJECT_ADMIN permission for the specified project or a higher global permission to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
Requiredstring
number
number
A page of groups and their highest permissions for the specified project.
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/permissions/groups' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
"values": [
{
"permission": "ADMIN",
"group": {
"name": "group_a"
}
}
],
"size": 1,
"isLastPage": true,
"nextPageStart": 2154,
"start": 2154,
"limit": 25
}Promote or demote a group's permission level for the specified project.
The authenticated user must have PROJECT_ADMIN permission for the specified project or a higher global permission to call this resource. In addition, a user may not demote a group's permission level if theirown permission level would be reduced as a result.
Forge and OAuth2 apps cannot access this REST resource.
string
Requiredstring
string
The requested permission was granted.
any
1
2
3
curl --request PUT \
--url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/permissions/groups' \
--header 'Accept: application/json'Revoke all permissions for the specified project for a group.
The authenticated user must have PROJECT_ADMIN permission for the specified project or a higher global permission to call this resource.
In addition, a user may not revoke a group's permissions if it will reduce their own permission level.
Forge and OAuth2 apps cannot access this REST resource.
string
Requiredstring
All project permissions were revoked from the group for the specified project.
any
1
2
3
curl --request DELETE \
--url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/permissions/groups' \
--header 'Accept: application/json'Retrieve a page of groups that have no granted permissions for the specified project.
The authenticated user must have PROJECT_ADMIN permission for the specified project or a higher
Forge and OAuth2 apps cannot access this REST resource.
string
Requiredstring
number
number
A page of groups that have not been granted any permissions for the specifiedproject.
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/permissions/groups/none' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
10
11
12
13
{
"values": [
{
"deletable": true,
"name": "group-a"
}
],
"size": 1,
"isLastPage": true,
"nextPageStart": 2154,
"start": 2154,
"limit": 25
}Retrieve a page of users that have been granted at least one permission for the specified project.
The authenticated user must have PROJECT_ADMIN permission for the specified project or a higher global permission to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
Requiredstring
number
number
A page of users and their highest permissions for the specified project.
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/permissions/users' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
"values": [
{
"user": {
"slug": "jcitizen",
"emailAddress": "jane@example.com",
"displayName": "Jane Citizen",
"name": "jcitizen",
"id": 101,
"type": "NORMAL",
"active": true
},
"permission": "USER_ADMIN"
}
],
"size": 1,
"isLastPage": true,
"nextPageStart": 2154,
"start": 2154,
"limit": 25
}Promote or demote a user's permission level for the specified project.
The authenticated user must have PROJECT_ADMIN permission for the specified project or a higher global permission to call this resource. In addition, a user may not reduce their own permission level unless they have a global permission that already implies that permission.
Forge and OAuth2 apps cannot access this REST resource.
string
Requiredstring
string
The requested permission was granted.
any
1
2
3
curl --request PUT \
--url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/permissions/users' \
--header 'Accept: application/json'Revoke all permissions for the specified project for a user.
The authenticated user must have PROJECT_ADMIN permission for the specified project or a higher global permission to call this resource.
In addition, a user may not revoke their own project permissions if they do not have a higher global permission.
Forge and OAuth2 apps cannot access this REST resource.
string
Requiredstring
All project permissions were revoked from the user for the specified project.
any
1
2
3
curl --request DELETE \
--url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/permissions/users' \
--header 'Accept: application/json'Retrieve a page of licensed users that have no granted permissions for the specified project.
The authenticated user must have PROJECT_ADMIN permission for the specified project or a higher global permission to call this resource.
Forge and OAuth2 apps cannot access this REST resource.
string
Requiredstring
number
number
A page of users that have not been granted any permissions for the specified project
1
2
3
curl --request GET \
--url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/permissions/users/none' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
10
11
12
13
14