WebService::BitbucketServer::Core::V1 - Bindings for a Bitbucket Server REST API
version 0.603
my $stash = WebService::BitbucketServer->new( base_url => 'https://stash.example.com/', username => 'bob', password => 'secret', ); my $api = $stash->core;
This is a Bitbucket Server REST API for Core::V1.
Original API documentation created by and copyright Atlassian.
Get the instance of WebService::BitbucketServer passed to "new".
$api = WebService::BitbucketServer::Core::V1->new(context => $webservice_bitbucketserver_obj);
Create a new API.
Normally you would use $webservice_bitbucketserver_obj->core instead.
$webservice_bitbucketserver_obj->core
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.
GET api/1.0/dashboard/pull-request-suggestions
Parameters:
changesSince - string, default: 172800
changesSince
restrict pull request suggestions to be based on events that occurred since some time in the past. This is expressed in seconds since "now". So to return suggestions based only on activity within the past 48 hours, pass a value of 172800.
limit - int, default: 3
limit
restricts the result set to return at most this many suggestions.
Responses:
200 - page, type: application/json
200
A page of pull requests that match the search criteria.
400 - errors, type: application/json
400
The request was malformed.
401 - errors, type: application/json
401
The current user is not authenticated
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.
GET api/1.0/dashboard/pull-requests
state - string, default: none
state
(optional, defaults to returning pull requests in any state). If a state is supplied only pull requests in the specified state will be returned. Either OPEN, DECLINED or MERGED. Omit this parameter to return pull request in any state.
role - string, default: none
role
(optional, defaults to returning pull requests for any role). If a role is supplied only pull requests where the authenticated user is a participant in the given role will be returned. Either REVIEWER, AUTHOR or PARTICIPANT.
participantStatus - string, default: none
participantStatus
(optional, defaults to returning pull requests with any participant status). A comma separated list of participant status. That is, one or more of UNAPPROVED, NEEDS_WORK, or APPROVED.
order - string, default: none
order
(optional, defaults to NEWEST) the order to return pull requests in, either OLDEST (as in: "oldest first"), NEWEST, PARTICIPANT_STATUS, or CLOSED_DATE. Where CLOSED_DATE is specified and the result set includes pull requests that are not in the closed state, these pull requests will appear first in the result set, followed by most recently closed pull requests.
closedSince - string, default: none
closedSince
(optional, defaults to returning pull requests regardless of closed since date). Permits returning only pull requests with a closed timestamp set more recently that (now - closedSince). Units are in seconds. So for example if closed since 86400 is set only pull requests closed in the previous 24 hours will be returned.
GET api/1.0/inbox/pull-requests
start - int, default: none
start
limit - int, default: 25
role - string, default: reviewer
GET api/1.0/inbox/pull-requests/count
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.
GET api/1.0/admin/cluster
200 - data, type: application/json
Information about the cluster
The currently authenticated user has insufficient permissions to retrieve the cluster information.
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.
DELETE api/1.0/admin/groups
name - string, default: none
name
the name identifying the group to delete
200 - detailedGroup, type: application/json
The deleted group.
The authenticated user does not have the ADMIN permission.
403 - errors, type: application/json
403
The action was disallowed as the authenticated user has a lower permission level than the group being deleted.
404 - errors, type: application/json
404
The specified group does not exist.
409 - errors, type: application/json
409
The action was disallowed as it would lower the authenticated user's permission level.
Create a new group.
The authenticated user must have ADMIN permission or higher to call this resource.
POST api/1.0/admin/groups
Name of the group.
200 - restDetailedGroup, type: application/json
The newly created group.
The currently authenticated user is not an administrator.
A group with this name already exists.
Retrieve a page of groups.
The authenticated user must have LICENSED_USER permission or higher to call this resource.
GET api/1.0/admin/groups
filter - string, default: none
filter
if specified only group names containing the supplied string will be returned
A page of groups.
The currently authenticated user is not a licensed user.
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.
POST api/1.0/admin/groups/add-user
200 - data, type: unknown
The user was added to the group
The action was disallowed as it would exceed the server's licensing limit, or the groups permissions exceed the authenticated user's permission level.
The specified user or group does not exist.
Add multiple users to a group.
POST api/1.0/admin/groups/add-users
<em>>All</em the users were added to the group
The action was disallowed as it would exceed the server's licensing limit, or the group's permissions exceed the authenticated user's permission level.
The specified group or users do not exist.
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.
GET api/1.0/admin/groups/more-members
context - string, default: none
context
the group which should be used to locate members
if specified only users with usernames, display names or email addresses containing the supplied string will be returned
A page of users.
Retrieves a list of users that are not members of a specified group.
GET api/1.0/admin/groups/more-non-members
the group which should be used to locate non-members
Deprecated since 2.10. Use /rest/users/remove-groups instead.
Remove a user from a group.
POST api/1.0/admin/groups/remove-user
The user was removed from the group.
The action was disallowed as the group has a higher permission level than the context user.
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.
GET api/1.0/admin/license
200 - license, type: application/json
The currently-installed license.
The currently authenticated user has insufficient permissions to view the license, or the request is anonymous.
No license has been installed.
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:
It is for a different product
It is already expired
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.
POST api/1.0/admin/license
The newly-installed license.
No encoded license was provided in the JSON body for the POST.
The currently authenticated user has insufficient permissions to update the license.
The encoded license could not be decoded, or it is not valid for use on this server. For example, it may be for a different product, or it may have already expired.
Deletes the current mail configuration.
DELETE api/1.0/admin/mail-server
The currently authenticated user has insufficient permissions to delete the mail server configuration.
204 - data, type: application/json
204
The mail configuration was successfully deleted.
Retrieves the current mail configuration. The authenticated user must have the SYS_ADMIN permission to call this resource.
GET api/1.0/admin/mail-server
200 - mailHostConfiguration, type: application/json
The mail configuration.
The currently authenticated user has insufficient permissions to retrieve the mail configuration.
404 - data, type: application/json
The mail server hasn't been configured
Updates the mail configuration The authenticated user must have the SYS_ADMIN permission to call this resource.
PUT api/1.0/admin/mail-server
200 - mailConfiguration, type: application/json
The updated mail configuration.
The mail configuration was not updated due to a validation error.
The currently authenticated user has insufficient permissions to update the mail configuration.
Clears the server email address.
DELETE api/1.0/admin/mail-server/sender-address
The currently authenticated user has insufficient permissions to clear the server email address.
The server email address was successfully cleared.
Retrieves the server email address
GET api/1.0/admin/mail-server/sender-address
200 - server email address, type: application/json
The server email address
The currently authenticated user has insufficient permissions to retrieve the server email address.
The server email address is not set
Updates the server email address The authenticated user must have the ADMIN permission to call this resource.
PUT api/1.0/admin/mail-server/sender-address
200 - senderAddress, type: application/json
The updated server email address.
The server email address was not updated due to a validation error.
The currently authenticated user has insufficient permissions to update the server email address.
Retrieve a page of groups that have been granted at least one global permission.
GET api/1.0/admin/permissions/groups
A page of groups and their highest global permissions.
Promote or demote a user's global permission level. Available global permissions are:
LICENSED_USER
PROJECT_CREATE
ADMIN
SYS_ADMIN
See the Bitbucket Server documentation for a detailed explanation of what each permission entails.
The authenticated user must have:
ADMIN permission or higher; and
the permission they are attempting to grant or higher; and
greater or equal permissions than the current permission level of the group (a user may not demote the permission level of a group with higher permissions than them)
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.
PUT api/1.0/admin/permissions/groups
permission - string, default: none
permission
the permission to grant
the names of the groups
The request was malformed or the specified permission does not exist.
The currently authenticated user is not an administrator or doesn't have the specified permission they are attempting to grant.
204 - data, type: unknown
The specified permission was granted to the specified user.
The action was disallowed as it would exceed the server's license limits.
The action was disallowed as it would reduce the currently authenticated user's permission level or the currently authenticated user has a lower permission level than the group they are attempting to modify.
Revoke all global permissions for a group.
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.
DELETE api/1.0/admin/permissions/groups
the name of the group
All global permissions were revoked from the group.
Retrieve a page of groups that have no granted global permissions.
GET api/1.0/admin/permissions/groups/none
A page of groups that have not been granted any global permissions.
Revoke all global permissions for a user.
greater or equal permissions than the current permission level of the user (a user may not demote the permission level of a user with higher permissions than them)
to call this resource. In addition, a user may not demote their own permission level.
DELETE api/1.0/admin/permissions/users
the name of the user
All global permissions were revoked from the user.
The specified user does not exist.
The action was disallowed as it would reduce the currently authenticated user's permission level or the currently authenticated user has a lower permission level than the user they are attempting to modify.
Retrieve a page of users that have been granted at least one global permission.
GET api/1.0/admin/permissions/users
if specified only user names containing the supplied string will be returned
A page of users and their highest global permissions.
Promote or demote the global permission level of a user. Available global permissions are:
the permission they are attempting to grant; and
PUT api/1.0/admin/permissions/users
the names of the users
The requested permission was granted.
Retrieve a page of users that have no granted global permissions.
GET api/1.0/admin/permissions/users/none
A page of users that have not been granted any global permissions.
Retrieve the merge strategies available for this instance.
The user must be authenticated to call this resource.
GET api/1.0/admin/pull-requests/{scmId}
scmId - string, default: none
scmId
the id of the scm to get strategies for
The merge configuration of this instance.
The currently authenticated user has insufficient permissions to see the request repository.
The request repository does not exist.
Update the pull request merge strategies for the context repository.
The authenticated user must have ADMIN permission for the context repository 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" : {} }
Upon completion of this request, the effective configuration will be the default configuration.
POST api/1.0/admin/pull-requests/{scmId}
200 - strategies, type: application/json
The repository pull request merge strategies for the context repository.
The repository pull request merge strategies were not updated due to a validation error.
The currently authenticated user has insufficient permissions to administrate the specified repository.
The specified repository does not exist.
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.
POST api/1.0/admin/users
the username for the new user
password - string, default: none
password
the password for the new user
displayName - string, default: none
displayName
the display name for the new user
emailAddress - string, default: none
emailAddress
the e-mail address for the new user
addToDefaultGroup - boolean, default: true
addToDefaultGroup
true to add the user to the default group, which can be used to grant them a set of initial permissions; otherwise, false to not add them to a group
true
false
notify - string, default: none
notify
if present and not false instead of requiring a password, the create user will be notified via email their account has been created and requires a password to be reset. This option can only be used if a mail server has been configured
The authenticated user is not an administrator.
The user was successfully created.
Adding the user to the default group would exceed the server's license limit.
Another user with the same name already exists.
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.
DELETE api/1.0/admin/users
the username identifying the user to delete
200 - detailedUser, type: application/json
The deleted user.
The action was disallowed as the authenticated user has a lower permission level than the user being deleted.
The action was disallowed as a user can not delete themselves.
Update a user's details.
PUT api/1.0/admin/users
The updated user.
The authenticated user does not have the ADMIN permission or has a lower permission level than the user being deleted.
Retrieve a page of users.
GET api/1.0/admin/users
if specified only users with usernames, display name or email addresses containing the supplied string will be returned
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.
groups/add-user
In the request entity, the context attribute is the user and the itemName is the group.
POST api/1.0/admin/users/add-group
Add a user to one or more groups.
POST api/1.0/admin/users/add-groups
The user was added to all the groups
The specified user or groups do not exist.
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.
DELETE api/1.0/admin/users/captcha
The CAPTCHA was successfully cleared.
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.
PUT api/1.0/admin/users/credentials
The user's password was successfully updated.
Retrieves a list of groups the specified user is a member of.
GET api/1.0/admin/users/more-members
the user which should be used to locate groups
if specified only groups with names containing the supplied string will be returned
Retrieves a list of groups the specified user is not a member of.
GET api/1.0/admin/users/more-non-members
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.
groups/remove-user
POST api/1.0/admin/users/remove-group
Rename a user.
POST api/1.0/admin/users/rename
The renamed user.
Retrieve version information and other application properties.
No authentication is required to call this resource.
GET api/1.0/application-properties
200 - applicationProperties, type: application/json
The application properties.
Retrieve a page of group names.
The authenticated user must have PROJECT_ADMIN permission or higher to call this resource.
GET api/1.0/groups
A page of group names.
The currently authenticated user is not a project administrator.
Retrieve the avatar for the project matching the supplied moduleKey.
GET api/1.0/hooks/{hookKey}/avatar
hookKey - string, default: none
hookKey
the complete module key of the hook module
version - string, default: none
version
optional version used for HTTP caching only - any non-blank version will result in a large max-age Cache-Control header. Note that this does not affect the Last-Modified header.
200 - data, type: image/png
The avatar of the project matching the supplied projectKey.
The currently authenticated user has insufficient permissions to view the project.
The specified project does not exist.
Retrieve the current log level for a given logger.
GET api/1.0/logs/logger/{loggerName}
loggerName - string, default: none
loggerName
the name of the logger.
200 - logLevel, type: application/json
The log level of the logger.
The currently authenticated user has insufficient permissions to retrieve the log level.
Set the current log level for a given logger.
PUT api/1.0/logs/logger/{loggerName}/{levelName}
levelName - string, default: none
levelName
the level to set the logger to. Either TRACE, DEBUG, INFO, WARN or ERROR
The log level was invalid.
The currently authenticated user has insufficient permissions to set the log level.
The log level was successfully changed.
Retrieve the current log level for the root logger.
GET api/1.0/logs/rootLogger
Set the current log level for the root logger.
PUT api/1.0/logs/rootLogger/{levelName}
Preview the generated html for given markdown contents.
Only authenticated users may call this resource.
POST api/1.0/markup/preview
urlMode - string, default: none
urlMode
(Optional) The UrlMode used when building the url. One of: ABSOLUTE, RELATIVE and CONFIGURED By default this is RELATIVE.
hardwrap - boolean, default: none
hardwrap
(Optional) Whether the markup implementation should convert newlines to breaks. By default this is false which reflects the standard markdown specification.
htmlEscape - boolean, default: none
htmlEscape
(Optional) true if HTML should be escaped in the input markup, false otherwise.
200 - markup, type: application/json
The rendered markdown.
The markdown was invalid.
The currently authenticated user has insufficient permissions preview rendered markdown.
Retrieve a page of recently accessed repositories for the currently authenticated user.
Repositories are ordered from most recently to least recently accessed.
GET api/1.0/profile/recent/repos
(optional) if specified, it must be a valid repository permission level name and will limit the resulting repository list to ones that the requesting user has the specified permission level to. If not specified, the default REPO_READ permission level will be assumed.
REPO_READ
A page of recently accessed repositories.
The permission level is unknown or not related to repository.
The request is unauthenticated.
Retrieve a page of projects.
Only projects for which the authenticated user has the PROJECT_VIEW permission will be returned.
GET api/1.0/projects
A page of projects.
The permission level is unknown or not related to projects.
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:
avatar
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.
POST api/1.0/projects
201 - project, type: application/json
201
The newly created project.
The project was not created due to a validation error.
The currently authenticated user has insufficient permissions to create a project.
The project key or name is already in use.
Delete the project matching the supplied projectKey.
The authenticated user must have PROJECT_ADMIN permission for the specified project to call this resource.
DELETE api/1.0/projects/{projectKey}
The currently authenticated user has insufficient permissions to delete the project.
The project matching the supplied projectKey was deleted.
The project can not be deleted as it contains repositories.
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.
PUT api/1.0/projects/{projectKey}
200 - project, type: application/json
The updated project. The project's key was not updated.
The updated project. The project's key was updated.
The project was not updated due to a validation error.
The currently authenticated user has insufficient permissions to update the project.
Retrieve the project matching the supplied projectKey.
The authenticated user must have PROJECT_VIEW permission for the specified project to call this resource.
GET api/1.0/projects/{projectKey}
The project matching the supplied projectKey.
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.
X-Atlassian-Token
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
POST api/1.0/projects/{projectKey}/avatar.png
201 - data, type: unknown
The avatar was uploaded successfully.
Retrieve the avatar for the project matching the supplied projectKey.
GET api/1.0/projects/{projectKey}/avatar.png
s - int, default: none
s
The desired size of the image. The server will return an image as close as possible to the specified size.
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.
GET api/1.0/projects/{projectKey}/permissions/groups
A page of groups and their highest permissions for the specified project.
401 - data, type: unknown
The currently authenticated user is not a project administrator for the specified project.
404 - data, type: unknown
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 their own permission level would be reduced as a result.
PUT api/1.0/projects/{projectKey}/permissions/groups
The permission to grant. See the [permissions documentation](https://confluence.atlassian.com/display/BitbucketServer/Using+project+permissions) for a detailed explanation of what each permission entails. Available project permissions are:
PROJECT_READ
PROJECT_WRITE
PROJECT_ADMIN
The currently authenticated user is not an administrator for the specified project.
403 - data, type: unknown
The action was disallowed as it would reduce the currently authenticated user's permission level.
The specified project or group does not exist.
Revoke all permissions for the specified project for a group.
In addition, a user may not revoke a group's permissions if it will reduce their own permission level.
DELETE api/1.0/projects/{projectKey}/permissions/groups
The currently authenticated user is not an administrator of the specified project.
All project permissions were revoked from the group for the specified project.
409 - data, type: unknown
Retrieve a page of groups that have no granted permissions for the specified project.
GET api/1.0/projects/{projectKey}/permissions/groups/none
A page of groups that have not been granted any permissions for the specified project.
Revoke all permissions for the specified project for a user.
In addition, a user may not revoke their own project permissions if they do not have a higher global permission.
DELETE api/1.0/projects/{projectKey}/permissions/users
All project permissions were revoked from the user for the specified project.
Retrieve a page of users that have been granted at least one permission for the specified project.
GET api/1.0/projects/{projectKey}/permissions/users
A page of users and their highest permissions for the specified project.
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.
PUT api/1.0/projects/{projectKey}/permissions/users
the permission to grant. See the [permissions documentation](https://confluence.atlassian.com/display/BitbucketServer/Using+project+permissions) for a detailed explanation of what each permission entails. Available project permissions are:
400 - data, type: unknown
The specified project or user does not exist.
Retrieve a page of licensed users that have no granted permissions for the specified project.
GET api/1.0/projects/{projectKey}/permissions/users/none
A page of users that have not been granted any permissions for the specified project.
Check whether the specified permission is the default permission (granted to all users) for a project.
GET api/1.0/projects/{projectKey}/permissions/{permission}/all
the permission to grant Available project permissions are:
200 - permitted, type: application/json
A simple entity indicating whether the specified permission is the default permission for this project.
Grant or revoke a project permission to all users, i.e. set the default permission.
POST api/1.0/projects/{projectKey}/permissions/{permission}/all
allow - boolean, default: none
allow
true to grant the specified permission to all users, or false to revoke it
The requested permission was successfully granted or revoked.
Retrieve repositories from the project corresponding to the supplied projectKey.
The authenticated user must have REPO_READ permission for the specified project to call this resource.
GET api/1.0/projects/{projectKey}/repos
projectKey - string, default: none
projectKey
the parent project key
The repositories matching the supplied projectKey.
The currently authenticated user has insufficient permissions to see the specified project.
Create a new repository. Requires an existing project in which this repository will be created. The only parameters which will be used are name and scmId.
The authenticated user must have PROJECT_ADMIN permission for the context project to call this resource.
POST api/1.0/projects/{projectKey}/repos
201 - repository, type: application/json
The newly created repository.
The repository was not created due to a validation error.
The currently authenticated user has insufficient permissions to create a repository.
A repository with same name already exists.
Schedule the repository matching the supplied projectKey and repositorySlug to be deleted. If the request repository is not present
The authenticated user must have REPO_ADMIN permission for the specified repository to call this resource.
DELETE api/1.0/projects/{projectKey}/repos/{repositorySlug}
repositorySlug - string, default: none
repositorySlug
the repository slug
202 - message, type: application/json
202
The repository has been scheduled for deletion.
The currently authenticated user has insufficient permissions to delete the repository.
No repository matching the supplied projectKey and repositorySlug was found.
Create a new repository forked from an existing repository.
The JSON body for this POST is not required to contain any properties. Even the name may be omitted. The following properties will be used, if provided:
POST
"name":"Fork name" - Specifies the forked repository's name
"name":"Fork name"
Defaults to the name of the origin repository if not specified
"project":{"key":"TARGET_KEY"} - Specifies the forked repository's target project by key
"project":{"key":"TARGET_KEY"
Defaults to the current user's personal project if not specified
The authenticated user must have REPO_READ permission for the specified repository and PROJECT_ADMIN on the target project to call this resource. Note that users always have PROJECT_ADMIN permission on their personal projects.
POST api/1.0/projects/{projectKey}/repos/{repositorySlug}
The newly created fork.
A validation error prevented the fork from being created. Possible validation errors include: The name or slug for the fork collides with another repository in the target project; an SCM type was specified in the JSON body; a project was specified in the JSON body without a "key" property.
The currently authenticated user has insufficient permissions to create a fork.
The specified repository does not exist, or, if a target project was specified, the target project does not exist.
Retrieve the repository matching the supplied projectKey and repositorySlug.
The authenticated user must have REPO_READ permission for the specified repository to call this resource.
GET api/1.0/projects/{projectKey}/repos/{repositorySlug}
200 - repository, type: application/json
The repository which matches the supplied projectKey and repositorySlug.
The currently authenticated user has insufficient permissions to see the specified repository.
Update the repository matching the repositorySlug supplied in the resource path.
The repository's slug is derived from its name. If the name changes the slug may also change.
This API can be used to move the repository to a different project by setting the new project in the request, example: {"project":{"key":"NEW_KEY"}} .
{"project":{"key":"NEW_KEY"
PUT api/1.0/projects/{projectKey}/repos/{repositorySlug}
The updated repository.
The repository was not updated due to a validation error.
The currently authenticated user has insufficient permissions to update a repository
A repository with same name as the target already exists
Streams an archive of the repository's contents at the requested commit. If no at= commit is requested, an archive of the default branch is streamed.
at=
The filename= query parameter may be used to specify the exact filename to include in the "Content-Disposition" header. If an explicit filename is not provided, one will be automatically generated based on what is being archived. Its format depends on the at= value:
filename=
"Content-Disposition"
No at= commit: <slug>-<default-branch-name>@<commit>.<format>; e.g. example-master@43c2f8a0fe8.zip
<slug>-<default-branch-name>@<commit>.<format>
at=sha: <slug>-<at>.<format>; e.g. example-09bcbb00100cfbb5310fb6834a1d5ce6cac253e9.tar.gz
at=sha
<slug>-<at>.<format>
at=branchOrTag: <slug>-<branchOrTag>@<commit>.<format>; e.g. example-feature@bbb225f16e1.tar
at=branchOrTag
<slug>-<branchOrTag>@<commit>.<format>
If the branch or tag is qualified (e.g. refs/heads/master, the short name (master) will be included in the filename
refs/heads/master
master
If the branch or tag's short name includes slashes (e.g. release/4.6), they will be converted to hyphens in the filename (release-4.5)
release/4.6
release-4.5
Archives may be requested in the following formats by adding the format= query parameter:
format=
zip: A zip file using standard compression (Default)
zip
tar: An uncompressed tarball
tar
tar.gz or tgz: A GZip-compressed tarball
tar.gz
tgz
The contents of the archive may be filtered by using the path= query parameter to specify paths to include. path= may be specified multiple times to include multiple paths.
path=
The prefix= query parameter may be used to define a directory (or multiple directories) where the archive's contents should be placed. If the prefix does not end with /, one will be added automatically. The prefix is always treated as a directory; it is not possible to use it to prepend characters to the entries in the archive.
prefix=
/
Archives of public repositories may be streamed by any authenticated or anonymous user. Streaming archives for non-public repositories requires an authenticated user with at least REPO_READ permission.
GET api/1.0/projects/{projectKey}/repos/{repositorySlug}/archive
at - string, default: none
at
the commit to stream an archive of; if not supplied, an archive of the default branch is streamed
filename - string, default: none
filename
a filename to include the "Content-Disposition" header
format - string, default: none
format
the format to stream the archive in; must be one of: zip, tar, tar.gz or tgz
path - string, default: none
path
paths to include in the streamed archive; may be repeated to include multiple paths
prefix - string, default: none
prefix
a prefix to apply to all entries in the streamed archive; if the supplied prefix does not end with a trailing /, one will be added automatically
200 - archive, type: application/octet-stream; application/x-tar
An archive or the requested commit, in zip, tar or gzipped-tar format.
The requested format is not supported.
The currently authenticated user has insufficient permissions to view the repository.
The repository does not exist or does not contain the at commit.
Retrieve the branches matching the supplied filterText param.
GET api/1.0/projects/{projectKey}/repos/{repositorySlug}/branches
base - string, default: none
base
base branch or tag to compare each branch to (for the metadata providers that uses that information)
details - boolean, default: none
details
whether to retrieve plugin-provided metadata about each branch
filterText - string, default: none
filterText
the text to match on
orderBy - string, default: none
orderBy
ordering of refs either ALPHABETICAL (by name) or MODIFICATION (last updated)
The branches matching the supplied filterText.
The currently authenticated user has insufficient permissions to read the repository.
Creates a branch using the information provided in the request
The authenticated user must have REPO_WRITE permission for the context repository to call this resource.
POST api/1.0/projects/{projectKey}/repos/{repositorySlug}/branches
200 - branch, type: application/json
The created branch
The currently authenticated user has insufficient permissions to write to the repository.
Update the default branch of a repository.
PUT api/1.0/projects/{projectKey}/repos/{repositorySlug}/branches/default
The currently authenticated user has insufficient permissions to update the repository
The operation was successful
Get the default branch of the repository.
GET api/1.0/projects/{projectKey}/repos/{repositorySlug}/branches/default
The specified repository does not exist or the repository has no default branch configured.
Update the content of path, on the given repository and branch.
repository
branch
This resource accepts PUT multipart form data, containing the file in a form-field named content.
content
An example curl request to update 'README.md' would be:
curl -X PUT -u username:password -F content=@README.md -F 'message=Updated using file-edit REST API' -F branch=master -F sourceCommitId=5636641a50b http://example.com/rest/api/latest/projects/PROJECT_1/repos/repo_1/browse/README.md
branch: the branch on which the path should be modified or created
content: the full content of the file at path
message: the message associated with this change, to be used as the commit message. Or null if the default message should be used.
sourceCommitId: the commit ID of the file before it was edited, used to identify if content has changed. Or null if this is a new file
The file can be updated or created on a new branch. In this case, the sourceBranch parameter should be provided to identify the starting point for the new branch and the branch parameter identifies the branch to create the new commit on.
sourceBranch
PUT api/1.0/projects/{projectKey}/repos/{repositorySlug}/browse/{path:.*}
the file path to retrieve content from
The newly created commit
The branch or content parameters were not supplied.
The currently authenticated user does not have write permission for the given repository
The repository does not exist.
The file already exists when trying to create a file, or the given content does not modify the file, or the file has changed since the given sourceCommitId
Retrieve a page of content for a file path at a specified revision.
GET api/1.0/projects/{projectKey}/repos/{repositorySlug}/browse/{path:.*}
the commit ID or ref to retrieve the content for.
type - boolean, default: false
type
if true only the type will be returned for the file path instead of the contents.
blame - string, default: none
blame
if present the blame will be returned for the file as well.
noContent - string, default: none
noContent
if present and used with blame only the blame is retrieved instead of the contents.
A page of contents from a file.
The path or until parameters were not supplied.
Retrieve a page of changes made in a specified commit.
Note: The implementation will apply a hard cap (page.max.changes) and it is not possible to request subsequent content when that cap is exceeded.
page.max.changes
GET api/1.0/projects/{projectKey}/repos/{repositorySlug}/changes
since - string, default: none
since
the commit to which until should be compared to produce a page of changes. If not specified the commit's first parent is assumed (if one exists)
until
until - string, default: none
the commit to retrieve changes for
A page of changes
The until parameter was not supplied
The repository or the since or until parameters supplied does not exist.
Retrieve a page of commits from a given starting commit or "between" two commits. If no explicit commit is specified, the tip of the repository's default branch is assumed. commits may be identified by branch or tag name or by ID. A path may be supplied to restrict the returned commits to only those which affect that path.
GET api/1.0/projects/{projectKey}/repos/{repositorySlug}/commits
followRenames - boolean, default: false
followRenames
if true, the commit history of the specified file will be followed past renames. Only valid for a path to a single file.
ignoreMissing - boolean, default: false
ignoreMissing
true to ignore missing commits, false otherwise
merges - string, default: none
merges
if present, controls how merge commits should be filtered. Can be either exclude, to exclude merge commits, include, to include both merge commits and non-merge commits or only, to only return merge commits.
exclude
include
only
an optional path to filter commits by
the commit ID or ref (exclusively) to retrieve commits after
the commit ID (SHA1) or ref (inclusively) to retrieve commits before
withCounts - boolean, default: false
withCounts
optionally include the total number of commits and total number of unique authors
A page of commits.
One of the supplied commit IDs or refs was invalid.
Retrieve a single commit identified by its ID>. In general, that ID is a SHA1. From 2.11, ref names like "refs/heads/master" are no longer accepted by this resource.
GET api/1.0/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}
commitId - string, default: none
commitId
the commit ID to retrieve
an optional path to filter the commit by. If supplied the details returned may not be for the specified commit. Instead, starting from the specified commit, they will be the details for the first commit affecting the specified path.
200 - commit, type: application/json
A commit.
The supplied commit ID was invalid.
GET api/1.0/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/changes
withComments - boolean, default: true
withComments
true to apply comment counts in the changes (the default); otherwise, false to stream changes without comment counts
Add a new comment.
Comments can be added in a few places by setting different attributes:
General commit comment:
{ "text" : "An insightful general comment on a commit." }
Reply to a comment:
{ "parent" : { "id" : 1 }, "text" : "A measured reply." }
General file comment:
{ "anchor" : { "diffType" : "COMMIT", "fromHash" : "6df3858eeb9a53a911cd17e66a9174d44ffb02cd", "path" : "path/to/file", "srcPath" : "path/to/file", "toHash" : "04c7c5c931b9418ca7b66f51fe934d0bd9b2ba4b" }, "text" : "An insightful general comment on a file." }
File line comment:
{ "anchor" : { "diffType" : "COMMIT", "fileType" : "FROM", "fromHash" : "6df3858eeb9a53a911cd17e66a9174d44ffb02cd", "line" : 1, "lineType" : "CONTEXT", "path" : "path/to/file", "srcPath" : "path/to/file", "toHash" : "04c7c5c931b9418ca7b66f51fe934d0bd9b2ba4b" }, "text" : "A pithy comment on a particular line within a file." }
Note: general file comments are an experimental feature and may change in the near future!
For file and line comments, 'path' refers to the path of the file to which the comment should be applied and 'srcPath' refers to the path the that file used to have (only required for copies and moves). Also, fromHash and toHash refer to the sinceId / untilId (respectively) used to produce the diff on which the comment was added. Finally diffType refers to the type of diff the comment was added on.
For line comments, 'line' refers to the line in the diff that the comment should apply to. 'lineType' refers to the type of diff hunk, which can be:
'ADDED' - for an added line;
'REMOVED' - for a removed line; or
'CONTEXT' - for a line that was unmodified but is in the vicinity of the diff.
'fileType' refers to the file of the diff to which the anchor should be attached - which is of relevance when displaying the diff in a side-by-side way. Currently the supported values are:
'FROM' - the source file of the diff
'TO' - the destination file of the diff
If the current user is not a participant the user is added as one and updated to watch the commit.
The authenticated user must have REPO_READ permission for the repository that the commit is in to call this resource.
POST api/1.0/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/comments
the commit to which the comments must be anchored
For a merge commit, a parent can be provided to specify which diff the comments should be on. For a commit range, a sinceId can be provided to specify where the comments should be anchored from.
sinceId
201 - comment, type: application/json
The newly created comment.
The comment was not created due to a validation error.
The currently authenticated user has insufficient permissions to view the commit, create a comment or watch the commit.
Unable to find the supplied project, repository, commit or parent comment. The missing entity will be specified in the error details.
Retrieves the commit discussion comments that match the specified search criteria.
It is possible to retrieve commit discussion comments that are anchored to a range of commits by providing the sinceId that the comments anchored from.
GET api/1.0/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/comments
the path to the file on which comments were made
For a merge commit, a parent can be provided to specify which diff the comments are on. For a commit range, a sinceId can be provided to specify where the comments are anchored from.
A page of comments that match the search criteria
The currently authenticated user has insufficient permissions to view the comment
Unable to find the supplied project, repository, or commit. The missing entity will be specified in the error details.
Update the text of a comment. Only the user who created a comment may update it.
Note: the supplied supplied JSON object must contain a version that must match the server's version of the comment or the update will fail. To determine the current version of the comment, the comment should be fetched from the server prior to the update. Look for the 'version' attribute in the returned JSON structure.
PUT api/1.0/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/comments/{commentId}
commentId - long, default: none
commentId
the ID of the comment to retrieve
the full ID of the commit within the repository
The newly updated comment.
The comment was not updated due to a validation error.
The currently authenticated user has insufficient permissions to view the commit, update the comment or watch the commit.
Unable to find the supplied project, repository, commit or comment. The missing entity will be specified in the error details.
The comment version supplied does not match the current version.
Delete a commit comment. Anyone can delete their own comment. Only users with REPO_ADMIN and above may delete comments created by other users. Comments which have replies may not be deleted, regardless of the user's granted permissions.
DELETE api/1.0/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/comments/{commentId}
version - int, default: -1
The expected version of the comment. This must match the server's version of the comment or the delete will fail. To determine the current version of the comment, the comment should be fetched from the server prior to the delete. Look for the 'version' attribute in the returned JSON structure.
The currently authenticated user has insufficient permissions to delete the comment.
Unable to find the supplied project, repository or commit. The missing entity will be specified in the error details.
The comment has replies or the version supplied does not match the comment's current version.
Retrieves a commit discussion comment.
GET api/1.0/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/comments/{commentId}
200 - comment, type: application/json
The requested comment.
Retrieve the diff between two provided revisions.
Note: This resource is currently not paged. The server will internally apply a hard cap to the streamed lines, and it is not possible to request subsequent pages if that cap is exceeded. In the event that the cap is reached, the diff will be cut short and one or more truncated flags will be set to true on the "segments", "hunks" and "diffs" properties, as well as the top-level object, in the returned JSON response.
truncated
"segments"
"hunks"
"diffs"
GET api/1.0/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/diff/{path:.*}
the path to the file which should be diffed (optional)
autoSrcPath - boolean, default: false
autoSrcPath
true to automatically try to find the source path when it's not provided, false otherwise. Requires the path to be provided.
contextLines - int, default: -1
contextLines
the number of context lines to include around added/removed lines in the diff
the base revision to diff from. If omitted the parent revision of the until revision is used
srcPath - string, default: none
srcPath
the source path for the file, if it was copied, moved or renamed
whitespace - string, default: none
whitespace
optional whitespace flag which can be set to ignore-all
ignore-all
true to embed comments in the diff (the default); otherwise false to stream the diff without comments
200 - diff, type: application/json
A diff between two revisions.
The until parameter was not supplied.
Removes the authenticated user as a watcher for the specified commit.
The authenticated user must have REPO_READ permission for the repository containing the commit to call this resource.
DELETE api/1.0/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/watch
The currently authenticated user has insufficient permissions to view the pull request.
The user is no longer watching the commit.
The specified project, repository or commit does not exist.
Adds the authenticated user as a watcher for the specified commit.
POST api/1.0/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/watch
The user is now watching the commit.
Gets the file changes available in the from commit but not in the to commit.
from
to
If either the from or to commit are not specified, they will be replaced by the default branch of their containing repository.
GET api/1.0/projects/{projectKey}/repos/{repositorySlug}/compare/changes
from - string, default: none
the source commit (can be a partial/full commit ID or qualified/unqualified ref name)
to - string, default: none
the target commit (can be a partial/full commit ID or qualified/unqualified ref name)
fromRepo - string, default: none
fromRepo
an optional parameter specifying the source repository containing the source commit if that commit is not present in the current repository; the repository can be specified by either its ID fromRepo=42 or by its project key plus its repo slug separated by a slash: fromRepo=projectKey/repoSlug
A page of changes.
The source or target commit does not exist.
Gets the commits accessible from the from commit but not in the to commit.
GET api/1.0/projects/{projectKey}/repos/{repositorySlug}/compare/commits
Gets a diff of the changes available in the from commit but not in the to commit.
GET api/1.0/projects/{projectKey}/repos/{repositorySlug}/compare/diff{path:.*}
the path to the file to diff (optional)
an optional number of context lines to include around each added or removed lines in the diff
an optional whitespace flag which can be set to ignore-all
The diff of the changes.
Retrieve the diff for a specified file path between two provided revisions.
Note: This resource is currently not paged. The server will internally apply a hard cap to the streamed lines, and it is not possible to request subsequent pages if that cap is exceeded. In the event that the cap is reached, the diff will be cut short and one or more truncated flags will be set to true on the segments, hunks and diffs substructures in the returned JSON response.
GET api/1.0/projects/{projectKey}/repos/{repositorySlug}/diff/{path:.*}
the path to the file which should be diffed (required)
the target revision to diff to (required)
A diff of a file path.
Retrieve a page of files from particular directory of a repository. The search is done recursively, so all files from any sub-directory of the specified directory will be returned.
GET api/1.0/projects/{projectKey}/repos/{repositorySlug}/files/{path:.*}
the directory to list files for.
the commit ID or ref (e.g. a branch or tag) to list the files at. If not specified the default branch will be used instead.
A page of files.
The path requested is not a directory at the supplied commit.
The path requested does not exist at the supplied commit.
Retrieve repositories which have been forked from this one. Unlike related repositories, this only looks at a given repository's direct forks. If those forks have themselves been the origin of more forks, such "grandchildren" repositories will not be retrieved.
Only repositories to which the authenticated user has REPO_READ permission will be included, even if other repositories have been forked from this one.
GET api/1.0/projects/{projectKey}/repos/{repositorySlug}/forks
A page of repositories related to the request repository.
Streams files in the requested path with the last commit to modify each file. Commit modifications are traversed starting from the at commit or, if not specified, from the tip of the default branch.
Unless the repository is public, the authenticated user must have REPO_READ access to call this resource.
GET api/1.0/projects/{projectKey}/repos/{repositorySlug}/last-modified/{path:.*}
the path within the repository whose files should be streamed
the commit to use as the starting point when listing files and calculating modifications
200 - modifications, type: application/json
A map of files to the last commit that modified them, and the latest commit to update the requested path.
No at commit was specified. When streaming modifications, an explicit starting commit must be supplied.
The repository does not exist or does not contain the at commit, or the at commit does not contain the requested path.
Retrieve a page of participant users for all the pull requests to or from the specified repository.
Optionally clients can specify following filters.
GET api/1.0/projects/{projectKey}/repos/{repositorySlug}/participants
direction - string, default: incoming
direction
(optional, defaults to INCOMING) the direction relative to the specified repository. Either INCOMING or OUTGOING.
(optional) return only users, whose username, name or email address contain the filter value
(optional) The role associated with the pull request participant. This must be one of AUTHOR, REVIEWER, orPARTICIPANT
AUTHOR
REVIEWER
PARTICIPANT
A page of users that match the search criteria.
The currently authenticated user has insufficient permissions to view the specified repository.
Promote or demote a group's permission level for the specified repository. Available repository permissions are:
REPO_WRITE
REPO_ADMIN
The authenticated user must have REPO_ADMIN permission for the specified repository or a higher project or global permission 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.
PUT api/1.0/projects/{projectKey}/repos/{repositorySlug}/permissions/groups
The currently authenticated user is not an administrator for the specified repository.
The specified repository or group does not exist.
Retrieve a page of groups that have been granted at least one permission for the specified repository.
The authenticated user must have REPO_ADMIN permission for the specified repository or a higher project or global permission to call this resource.
GET api/1.0/projects/{projectKey}/repos/{repositorySlug}/permissions/groups
A page of groups and their highest permissions for the specified repository.
The currently authenticated user is not a repository administrator for the specified repository.
Revoke all permissions for the specified repository for a group.
DELETE api/1.0/projects/{projectKey}/repos/{repositorySlug}/permissions/groups
The currently authenticated user is not an administrator of the specified repository.
All repository permissions were revoked from the group for the specified repository.
Retrieve a page of groups that have no granted permissions for the specified repository.
GET api/1.0/projects/{projectKey}/repos/{repositorySlug}/permissions/groups/none
A page of groups that have not been granted any permissions for the specified repository.
Revoke all permissions for the specified repository for a user.
In addition, a user may not revoke their own repository permissions if they do not have a higher project or global permission.
DELETE api/1.0/projects/{projectKey}/repos/{repositorySlug}/permissions/users
All repository permissions were revoked from the user for the specified repository.
Promote or demote a user's permission level for the specified repository. Available repository permissions are:
The authenticated user must have REPO_ADMIN permission for the specified repository or a higher project or global permission to call this resource. In addition, a user may not reduce their own permission level unless they have a project or global permission that already implies that permission.
PUT api/1.0/projects/{projectKey}/repos/{repositorySlug}/permissions/users
The specified repository or user does not exist.
Retrieve a page of users that have been granted at least one permission for the specified repository.
GET api/1.0/projects/{projectKey}/repos/{repositorySlug}/permissions/users
A page of users and their highest permissions for the specified repository.
Retrieve a page of licensed users that have no granted permissions for the specified repository.
GET api/1.0/projects/{projectKey}/repos/{repositorySlug}/permissions/users/none
A page of users that have not been granted any permissions for the specified repository.
Retrieve a page of pull requests to or from the specified repository.
The authenticated user must have REPO_READ permission for the specified repository to call this resource. Optionally clients can specify PR participant filters. Each filter has a mandatory username.N parameter, and the optional role.N and approved.N parameters.
username.N
role.N
approved.N
username.N - the "root" of a single participant filter, where "N" is a natural number starting from 1. This allows clients to specify multiple participant filters, by providing consecutive filters as username.1, username.2 etc. Note that the filters numbering has to start with 1 and be continuous for all filters to be processed. The total allowed number of participant filters is 10 and all filters exceeding that limit will be dropped.
username.1
username.2
role.N(optional) the role associated with username.N. This must be one of AUTHOR, REVIEWER, orPARTICIPANT
approved.N(optional) the approved status associated with username.N. That is whether username.N has approved the PR. Either true, or false
GET api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests
(optional) a fully-qualified branch ID to find pull requests to or from, such as refs/heads/master
(optional, defaults to OPEN). Supply ALL to return pull request in any state. If a state is supplied only pull requests in the specified state will be returned. Either OPEN, DECLINED or MERGED.
(optional, defaults to NEWEST) the order to return pull requests in, either OLDEST (as in: "oldest first") or NEWEST.
withAttributes - boolean, default: true
withAttributes
(optional) defaults to true, whether to return additional pull request attributes
withProperties - boolean, default: true
withProperties
(optional) defaults to true, whether to return additional pull request properties
The currently authenticated user has insufficient permissions to view the specified pull request.
The specified repository or pull request does not exist.
Create a new pull request between two branches. The branches may be in the same repository, or different ones. When using different repositories, they must still be in the same hierarchy.
The authenticated user must have REPO_READ permission for the "from" and "to"repositories to call this resource.
POST api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests
201 - pullRequest, type: application/json
The newly created pull request.
The pull request entity supplied in the request was malformed.
The currently authenticated user has insufficient permissions to create a pull request between the two specified repositories.
One of the specified repositories or branches does not exist.
One of the following error cases occurred (check the error message for more details):
There was a problem resolving one or more reviewers.
The specified branches were the same.
The to branch is already up-to-date with all the commits on the from branch.
A pull request between the two branches already exists.
Retrieve a pull request.
The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.
GET api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}
pullRequestId - long, default: none
pullRequestId
the ID of the pull request within the repository
200 - pullRequest, type: application/json
The specified pull request.
Update the title, description, reviewers or destination branch of an existing pull request.
Note: the reviewers list may be updated using this resource. However the author and participants list may not.
The authenticated user must either:
be the author of the pull request and have the REPO_READ permission for the repository that this pull request targets; or
have the REPO_WRITE permission for the repository that this pull request targets
to call this resource.
PUT api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}
The updated pull request.
The request tried to modify the author or participants.
The pull request's version attribute was not specified.
A reviewer's username was not specified.
The toRef id value was incorrectly left blank
The currently authenticated user has insufficient permissions to update the specified pull request.
The specified version is out of date.
One of the reviewers could not be added to the pull request.
If updating the destination branch:
There is already an open pull request with an identical to branch
The from and new to branch are the same
The new destination branch up-to-date is up-to-date with all of changes from the from branch, resulting in a pull request with nothing to merge
Deletes a pull request.
To call this resource, users must be authenticated and have permission to view the pull request. Additionally, they must:
be the pull request author, if the system is configured to allow authors to delete their own pull requests (this is the default) OR
have repository administrator permission for the repository the pull request is targeting
A body containing the version of the pull request must be provided with this request.
C<<< { "version": 1 } >>> DELETE api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}
Retrieve a page of activity associated with a pull request.
Activity items include comments, approvals, rescopes (i.e. adding and removing of commits), merges and more.
Different types of activity items may be introduced in newer versions of Stash or by user installed plugins, so clients should be flexible enough to handle unexpected entity shapes in the returned page.
GET api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/activities
the id of the pull request within the repository
fromId - long, default: none
fromId
(optional) the id of the activity item to use as the first item in the returned page
fromType - string, default: none
fromType
(required if fromId is present) the type of the activity item specified by fromId (either COMMENT or ACTIVITY)
A page of activity relating to the specified pull request.
Remove approval from a pull request as the current user. This does not remove the user as a participant.
Deprecated since 4.2. Use /rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/participants/{userSlug} instead
DELETE api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/approve
201 - participant, type: application/json
Details of the updated participant
The specified repository or pull request does not exist or the current user is not a participant on the pull request.
The pull request is not open.
Approve a pull request as the current user. Implicitly adds the user as a participant if they are not already.
POST api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/approve
Details of the new participant
Gets changes for the specified PullRequest.
If the changeScope query parameter is set to unreviewed, the application will attempt to stream unreviewed changes based on the lastReviewedCommit of the current user, which are the changes between the lastReviewedCommit and the latest commit of the source branch. The current user is considered to not have any unreviewed changes for the pull request when the lastReviewedCommit is either null (everything is unreviewed, so all changes are streamed), equal to the latest commit of the source branch (everything is reviewed), or no longer on the source branch (the source branch has been rebased). In these cases, the application will fall back to streaming all changes (the default), which is the effective diff for the pull request. The type of changes streamed can be determined by the changeScope parameter included in the properties map of the response.
changeScope
unreviewed
lastReviewedCommit
null
Note: This resource is currently not paged. The server will return at most one page. The server will truncate the number of changes to either the request's page limit or an internal maximum, whichever is smaller. The start parameter of the page request is also ignored.
GET api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/changes
changeScope - string, default: ALL
UNREVIEWED to stream the unreviewed changes for the current user (if they exist); RANGE to stream changes between two arbitrary commits (requires sinceId and untilId); otherwise ALL to stream all changes (the default)
UNREVIEWED
RANGE
untilId
ALL
sinceId - string, default: none
the since commit hash to stream changes for a RANGE arbitrary change scope
untilId - string, default: none
the until commit hash to stream changes for a RANGE arbitrary change scope
A page of unreviewed Changes for the current user from the supplied pull request, including the unreviewedCommits in the properties map.
The currently authenticated user has insufficient permissions to view the repository or pull request.
The repository or pull request does not exist.
General pull request comment:
{ "text" : "An insightful general comment on a pull request." }
{ "anchor" : { "diffType" : "RANGE", "fromHash" : "6df3858eeb9a53a911cd17e66a9174d44ffb02cd", "path" : "path/to/file", "srcPath" : "path/to/file", "toHash" : "04c7c5c931b9418ca7b66f51fe934d0bd9b2ba4b" }, "text" : "An insightful general comment on a file." }
For file and line comments, 'path' refers to the path of the file to which the comment should be applied and 'srcPath' refers to the path the that file used to have (only required for copies and moves). Also, fromHash and toHash refer to the sinceId / untilId (respectively) used to produce the diff on which the comment was added. Finally diffType refers to the type of diff the comment was added on. For backwards compatibility purposes if no diffType is provided and no fromHash/toHash pair is provided the diffType will be resolved to 'EFFECTIVE'. In any other cases the diffType is REQUIRED.
If the current user is not a participant the user is added as a watcher of the pull request.
POST api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/comments
The currently authenticated user has insufficient permissions to view the pull request, create a comment or watch the pull request.
Unable to find the supplied project, repository, pull request or parent comment
Gets comments for the specified PullRequest.
GET api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/comments
anchorState - string, default: ACTIVE
anchorState
ACTIVE to stream the active comments; ORPHANED to stream the orphaned comments; ALL to stream both the active and the orphaned comments;
ACTIVE
ORPHANED
diffType - string, default: none
diffType
EFFECTIVE to stream the comments related to the effective diff of the pull request; RANGE to stream comments related to a commit range between two arbitrary commits (requires fromHash and toHash); COMMIT to stream comments related to a commit between two arbitrary commits (requires fromHash and toHash)
EFFECTIVE
fromHash
toHash
COMMIT
fromHash - string, default: none
the from commit hash to stream comments for a RANGE or COMMIT arbitrary change scope
the path to stream comments for a given path
toHash - string, default: none
the to commit hash to stream comments for a RANGE or COMMIT arbitrary change scope
A page of Comments from the supplied pull request.
PUT api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/comments/{commentId}
the id of the comment to retrieve
The currently authenticated user has insufficient permissions to view the pull request, update a comment or watch the pull request.
Unable to find the supplied project, repository, pull request or comment
Delete a pull request comment. Anyone can delete their own comment. Only users with REPO_ADMIN and above may delete comments created by other users.
DELETE api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/comments/{commentId}
Unable to find the supplied project, repository or pull request.
The comment has replies or the version supplied does not match the current version.
Retrieves a pull request comment.
GET api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/comments/{commentId}
Retrieve commits for the specified pull request.
GET api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/commits
withCounts - boolean, default: none
if set to true, the service will add "authorCount" and "totalCount" at the end of the page. "authorCount" is the number of different authors and "totalCount" is the total number of commits.
a page of commits from the supplied pull request.
Decline a pull request.
POST api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/decline
the current version of the pull request. If the server's version isn't the same as the specified version the operation will fail. To determine the current version of the pull request it should be fetched from the server prior to this operation. Look for the 'version' attribute in the returned JSON structure.
The pull request was declined.
The pull request is not OPEN or has been updated since the version specified by the request.
Streams a diff within a pull request.
If the specified file has been copied, moved or renamed, the srcPath must also be specified to produce the correct diff.
Note: This RESTful endpoint is currently not paged. The server will internally apply a hard cap to the streamed lines, and it is not possible to request subsequent pages if that cap is exceeded.
GET api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/diff/{path:.*}
diffType - string, default: EFFECTIVE
the type of diff being requested. When withComments is true this works as a hint to the system to attach the correct set of comments to the diff
the since commit hash to stream a diff between two arbitrary hashes
the previous path to the file, if the file has been copied, moved or renamed
the until commit hash to stream a diff between two arbitrary hashes
true to embed comments in the diff (the default); otherwise, false to stream the diff without comments
200 - diffs, type: application/json
a page of differences from a pull request.
If the request was malformed.
Test whether a pull request can be merged.
A pull request may not be merged if:
there are conflicts that need to be manually resolved before merging; and/or
one or more merge checks have vetoed the merge.
GET api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/merge
The mergeability status of the pull request.
The specified pull request is not open.
Merge the specified pull request.
The authenticated user must have REPO_WRITE permission for the repository that this pull request targets to call this resource.
POST api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/merge
The merged pull request.
The currently authenticated user has insufficient permissions to merge the specified pull request.
The pull request has conflicts.
A merge check vetoed the merge.
Retrieves a page of the participants for a given pull request.
GET api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/participants
201 - page, type: application/json
Details of the participants in this pull request
Assigns a participant to an explicit role in pull request. Currently only the REVIEWER role may be assigned.
If the user is not yet a participant in the pull request, they are made one and assigned the supplied role.
If the user is already a participant in the pull request, their previous role is replaced with the supplied role unless they are already assigned the AUTHOR role which cannot be changed and will result in a Bad Request (400) response code.
POST api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/participants
The created or updated participant.
The request does not have the username and role, or is attempting an invalid assignment
The currently authenticated user has insufficient permissions to update the pull request.
Unassigns a participant from the REVIEWER role they may have been given in a pull request.
If the participant has no explicit role this method has no effect.
Afterwards, the user will still remain a participant in the pull request but their role will be reduced to PARTICIPANT. This is because once made a participant of a pull request, a user will forever remain a participant. Only their role may be altered.
Deprecated since 4.2. Use /rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/participants/{userSlug} instead.
DELETE api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/participants/{userSlug}
userSlug - string, default: none
userSlug
the slug for the user changing their status
The request does not have the username
The update completed.
Change the current user's status for a pull request. Implicitly adds the user as a participant if they are not already. If the current user is the author, this method will fail.
The possible values for status are UNAPPROVED, NEEDS_WORK, or APPROVED.
status
If the new status is NEEDS_WORK or APPROVED then the lastReviewedCommit for the participant will be updated to the latest commit of the source branch of the pull request.
PUT api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/participants/{userSlug}
The specified status was invalid.
Re-open a declined pull request.
POST api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/reopen
The currently authenticated user has insufficient permissions to reopen the specified pull request.
The pull request is not in a declined state.
Retrieve the tasks associated with a pull request.
GET api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/tasks
200 - task, type: application/json
A page of tasks associated with the pull request.
If the current user cannot access the pull request
If the pull request does not exist
Retrieve the total number of open and resolved tasks associated with a pull request.
GET api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/tasks/count
200 - taskCount, type: application/json
Total number of open and resolved tasks associated with the pull request.
Make the authenticated user stop watching the specified pull request.
DELETE api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/watch
The user is no longer watching the pull request.
Make the authenticated user watch the specified pull request.
POST api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/watch
The user is now watching the pull request.
Retrieve the raw content for a file path at a specified revision.
GET api/1.0/projects/{projectKey}/repos/{repositorySlug}/raw/{path:.*}
markup - string, default: none
markup
if present or "true", triggers the raw content to be markup-rendered and returned as HTML; otherwise, if not specified, or any value other than "true", the content is streamed without markup
"true"
(Optional) Whether the markup implementation should convert newlines to breaks. If not specified, {@link MarkupService} will user the value of the markup.render.hardwrap which is true by default
markup.render.hardwrap
(Optional) true if HTML should be escaped in the input markup, false otherwise. If not specified, {@link MarkupService} will user the value of the markup.render.html.escape which is true by default
markup.render.html.escape
If a create or fork operation fails, calling this method will clean up the broken repository and try again. The repository must be in an INITIALISATION_FAILED state.
POST api/1.0/projects/{projectKey}/repos/{repositorySlug}/recreate
Retrieve repositories which are related to this one. Related repositories are from the same hierarchy as this repository.
Only repositories to which the authenticated user has REPO_READ permission will be included, even if more repositories are part of this repository's hierarchy.
GET api/1.0/projects/{projectKey}/repos/{repositorySlug}/related
Retrieve a page of repository hooks for this repository.
GET api/1.0/projects/{projectKey}/repos/{repositorySlug}/settings/hooks
type - string, default: none
the optional type to filter by. Valid values are PRE_RECEIVE or POST_RECEIVE
PRE_RECEIVE
POST_RECEIVE
returns a page of repository hooks with their associated enabled state.
The currently authenticated user has insufficient permissions to retrieve the hooks.
Delete repository hook configuration for the supplied hookKey and repositorySlug
DELETE api/1.0/projects/{projectKey}/repos/{repositorySlug}/settings/hooks/{hookKey}
The currently authenticated user has insufficient permissions to delete the hook.
The hook configuration matching the supplied hookKey and repositorySlug was deleted
The specified repository or hook does not exist.
Retrieve a repository hook for this repository.
GET api/1.0/projects/{projectKey}/repos/{repositorySlug}/settings/hooks/{hookKey}
returns the repository hooks with their associated enabled state for the supplied hookKey.
The currently authenticated user has insufficient permissions to retrieve the hook.
The specified repository hook does not exist for the given repository, or the repository does not exist.
Enable a repository hook for this repository and optionally apply new configuration.
A JSON document may be provided to use as the settings for the hook. These structure and validity of the document is decided by the plugin providing the hook.
PUT api/1.0/projects/{projectKey}/repos/{repositorySlug}/settings/hooks/{hookKey}/enabled
Content-Length - int, default: none
Content-Length
The settings specified are invalid.
The currently authenticated user has insufficient permissions to enable the hook.
Disable a repository hook for this repository.
DELETE api/1.0/projects/{projectKey}/repos/{repositorySlug}/settings/hooks/{hookKey}/enabled
The currently authenticated user has insufficient permissions to disable the hook.
Modify the settings for a repository hook for this repository.
The service will reject any settings which are too large, the current limit is 32KB once serialized.
A JSON document can be provided to use as the settings for the hook. These structure and validity of the document is decided by the plugin providing the hook.
PUT api/1.0/projects/{projectKey}/repos/{repositorySlug}/settings/hooks/{hookKey}/settings
The settings for the hook.
The currently authenticated user has insufficient permissions to modify the hook settings.
Retrieve the settings for a repository hook for this repository.
GET api/1.0/projects/{projectKey}/repos/{repositorySlug}/settings/hooks/{hookKey}/settings
The currently authenticated user has insufficient permissions to retrieve the hook settings.
Retrieve the pull request settings for the context repository.
The authenticated user must have REPO_READ permission for the context repository to call this resource.
This resource will call all RestFragments that are registered with the key bitbucket.repository.settings.pullRequests. If any fragment fails validations by returning a non-empty Map of errors, then no fragments will execute.
The property keys for the settings that are bundled with the application are
mergeConfig - the merge strategy configuration for pull requests
requiredApprovers - (Deprecated, please use com.atlassian.bitbucket.server.bundled-hooks.requiredApproversMergeHook instead) the number of approvals required on a pull request for it to be mergeable, or 0 if the merge check is disabled
com.atlassian.bitbucket.server.bundled-hooks.requiredApproversMergeHook - the merge check configuration for required approvers
requiredAllApprovers - whether or not all approvers must approve a pull request for it to be mergeable
requiredAllTasksComplete - whether or not all tasks on a pull request need to be completed for it to be mergeable
requiredSuccessfulBuilds - (Deprecated, please use com.atlassian.bitbucket.server.bitbucket-build.requiredBuildsMergeCheck instead) the number of successful builds on a pull request for it to be mergeable, or 0 if the merge check is disabled
com.atlassian.bitbucket.server.bitbucket-build.requiredBuildsMergeCheck - the merge check configuration for required builds
GET api/1.0/projects/{projectKey}/repos/{repositorySlug}/settings/pull-requests
The repository pull request settings for the context repository.
Update the pull request settings for the context repository.
The authenticated user must have REPO_ADMIN permission for the context repository to call this resource.
Only the settings that should be updated need to be included in the request.
requiredApprovers - (Deprecated, please use com.atlassian.bitbucket.server.bundled-hooks.requiredApproversMergeHook instead) the number of approvals required on a pull request for it to be mergeable, or 0 to disable the merge check
com.atlassian.bitbucket.server.bundled-hooks.requiredApproversMergeHook - a json map containing the keys 'enabled' (a boolean to enable or disable this merge check) and 'count' (an integer to set the number of required approvals)
requiredSuccessfulBuilds - (Deprecated, please use com.atlassian.bitbucket.server.bitbucket-build.requiredBuildsMergeCheck instead) the number of successful builds on a pull request for it to be mergeable, or 0 to disable the merge check
com.atlassian.bitbucket.server.bitbucket-build.requiredBuildsMergeCheck - a json map containing the keys 'enabled' (a boolean to enable or disable this merge check) and 'count' (an integer to set the number of required builds)
Merge strategy configuration deletion:
Upon completion of this request, the effective configuration will be:
The configuration set for this repository's SCM type as set at the project level, if present, otherwise
the configuration set for this repository's SCM type as set at the instance level, if present, otherwise
the default configuration for this repository's SCM type
POST api/1.0/projects/{projectKey}/repos/{repositorySlug}/settings/pull-requests
200 - settings, type: application/json
The repository pull request settings were not updated due to a validation error.
Creates a tag using the information provided in the request
POST api/1.0/projects/{projectKey}/repos/{repositorySlug}/tags
200 - tag, type: application/json
The created tag
Retrieve the tags matching the supplied filterText param.
GET api/1.0/projects/{projectKey}/repos/{repositorySlug}/tags
The tags matching the supplied filterText.
Retrieve a tag in the specified repository.
GET api/1.0/projects/{projectKey}/repos/{repositorySlug}/tags/{name:.*}
the name of the tag to be retrieved
The tag which matches the supplied name.
The specified tag does not exist.
Create a webhook for the repository specified via the URL.
POST api/1.0/projects/{projectKey}/repos/{repositorySlug}/webhooks
200 - webhook, type: application/json
A created webhook.
The webhook parameters were invalid or not supplied.
The currently authenticated user has insufficient permissions to create webhooks in the repository.
Find webhooks in this repository.
GET api/1.0/projects/{projectKey}/repos/{repositorySlug}/webhooks
event - string, default: none
event
list of {@link com.atlassian.webhooks.WebhookEvent} ids to filter for
statistics - boolean, default: false
statistics
true if statistics should be provided for all found webhooks
A list of webhooks.
The currently authenticated user has insufficient permissions to find webhooks in the repository.
Test connectivity to a specific endpoint.
POST api/1.0/projects/{projectKey}/repos/{repositorySlug}/webhooks/test
url - string, default: none
url
the url in which to connect to
a webhook.
The currently authenticated user has insufficient permissions to test a connection.
Delete a webhook for the repository specified via the URL.
DELETE api/1.0/projects/{projectKey}/repos/{repositorySlug}/webhooks/{webhookId}
webhookId - int, default: none
webhookId
the existing webhook id
The currently authenticated user has insufficient permissions to delete webhooks in the repository.
The repository does not exist, or webhook does not exist in this repository.
Get a webhook by id.
GET api/1.0/projects/{projectKey}/repos/{repositorySlug}/webhooks/{webhookId}
The currently authenticated user has insufficient permissions to get a webhook in the repository.
The repository does not exist, or the webhook does not exist in the repository.
Update an existing webhook.
PUT api/1.0/projects/{projectKey}/repos/{repositorySlug}/webhooks/{webhookId}
The currently authenticated user has insufficient permissions to update a webhook in this repository.
Get the latest invocations for a specific webhook.
GET api/1.0/projects/{projectKey}/repos/{repositorySlug}/webhooks/{webhookId}/latest
id of the webhook
the string id of a specific event to retrieve the last invocation for.
outcome - string, default: none
outcome
the outcome to filter for. Can be SUCCESS, FAILURE, ERROR. None specified means that the all will be considered
200 - webhookInvocation, type: application/json
a webhook invocation dataset.
The currently authenticated user has insufficient permissions to get webhook invocations in the repository.
Get the statistics for a specific webhook.
GET api/1.0/projects/{projectKey}/repos/{repositorySlug}/webhooks/{webhookId}/statistics
the string id of a specific event to retrieve the last invocation for. May be empty, in which case all events are considered
The currently authenticated user has insufficient permissions to get webhook statistics in the repository.
Get the statistics summary for a specific webhook.
GET api/1.0/projects/{projectKey}/repos/{repositorySlug}/webhooks/{webhookId}/statistics/summary
The currently authenticated user has insufficient permissions to get webhook statistics summary in the repository.
Retrieve a page of repository hooks for this project.
The authenticated user must have PROJECT_READ permission for the specified project to call this resource.
GET api/1.0/projects/{projectKey}/settings/hooks
Retrieve a repository hook for this project.
GET api/1.0/projects/{projectKey}/settings/hooks/{hookKey}
The specified repository hook does not exist for the given project, or the project does not exist.
Enable a repository hook for this project and optionally apply new configuration.
PUT api/1.0/projects/{projectKey}/settings/hooks/{hookKey}/enabled
The specified project or hook does not exist.
Disable a repository hook for this project.
DELETE api/1.0/projects/{projectKey}/settings/hooks/{hookKey}/enabled
Modify the settings for a repository hook for this project.
PUT api/1.0/projects/{projectKey}/settings/hooks/{hookKey}/settings
Retrieve the settings for a repository hook for this project.
GET api/1.0/projects/{projectKey}/settings/hooks/{hookKey}/settings
Retrieve the merge strategy configuration for this project and SCM.
The authenticated user must have PROJECT_READ permission for the context repository to call this resource.
GET api/1.0/projects/{projectKey}/settings/pull-requests/{scmId}
the SCM to get strategies for
The merge configuration of the request project.
Update the pull request merge strategy configuration for this project and SCM.
The authenticated user must have PROJECT_ADMIN permission for the context repository to call this resource.
Only the strategies provided will be enabled, the default must be set and included in the set of strategies.
Upon completion of this request, the effective configuration will be the configuration explicitly set for the SCM, or if no such explicit configuration is set then the default configuration will be used.
POST api/1.0/projects/{projectKey}/settings/pull-requests/{scmId}
Retrieve a page of repositories based on query parameters that control the search. See the documentation of the parameters for more details.
This resource is anonymously accessible.
Note on permissions. In absence of the permission query parameter the implicit 'read' permission is assumed. Please note that this permission is lower than the REPO_READ permission rather than being equal to it. The implicit 'read' permission for a given repository is assigned to any user that has any of the higher permissions, such as REPO_READ, as well as to anonymous users if the repository is marked as public. The important implication of the above is that an anonymous request to this resource with a permission level REPO_READ is guaranteed to receive an empty list of repositories as a result. For anonymous requests it is therefore recommended to not specify the permission parameter at all.
GET api/1.0/repos
(optional) if specified, this will limit the resulting repository list to ones whose name matches this parameter's value. The match will be done case-insensitive and any leading and/or trailing whitespace characters on the name parameter will be stripped.
projectname - string, default: none
projectname
(optional) if specified, this will limit the resulting repository list to ones whose project's name matches this parameter's value. The match will be done case-insensitive and any leading and/or trailing whitespace characters on the projectname parameter will be stripped.
(optional) if specified, it must be a valid repository permission level name and will limit the resulting repository list to ones that the requesting user has the specified permission level to. If not specified, the default implicit 'read' permission level will be assumed. The currently supported explicit permission values are REPO_READ, REPO_WRITE and REPO_ADMIN.
visibility - string, default: none
visibility
(optional) if specified, this will limit the resulting repository list based on the repositories visibility. Valid values are public or private.
A page of repositories.
The visibility parameter contains an invalid value
Create a new task.
POST api/1.0/tasks
201 - task, type: application/json
A copy of the created task.
If the task data is invalid (for example, if the task's text is missing or blank)
If the anchor of the task (such as a pull request comment) does not exist or is not visible to the current user
Update a existing task.
As of Stash 3.3, only the state and text of a task can be updated.
Updating the state of a task is allowed for any user having READ access to the repository. However only the task's creator, the context's author or an admin of the context's repository can update the task's text. (For a pull request task, those are the task's creator, the pull request's author or an admin on the repository containing the pull request). Additionally the task's text cannot be updated if it has been resolved.
PUT api/1.0/tasks/{taskId}
taskId - long, default: none
taskId
the id identifying the task to delete
A copy of the task if it was successfully updated.
If the current user does not have the permission to update the task
If the task does not exist
If the task to update is in the resolved state
Delete a task.
Note that only the task's creator, the context's author or an admin of the context's repository can delete a task. (For a pull request task, those are the task's creator, the pull request's author or an admin on the repository containing the pull request). Additionally a task cannot be deleted if it has already been resolved.
DELETE api/1.0/tasks/{taskId}
If the current user does not have the permission to delete the task
204 - task, type: unknown
if the task was successfully deleted.
If the task to delete is in the resolved state
Retrieve a existing task.
GET api/1.0/tasks/{taskId}
A copy of the task.
Update the currently authenticated user's details. The update will always be applied to the currently authenticated user.
PUT api/1.0/users
Authentication failed or was not attempted.
Retrieve a page of users, optionally run through provided filters.
Filters are provided in query parameters in a standard name=value fashion. The following filters are currently supported:
name=value
filter - return only users, whose username, name or email address contain the filter value
group - return only users who are members of the given group
group
permission - the "root" of a permission filter, whose value must be a valid global, project, or repository permission. Additional filter parameters referring to this filter that specify the resource (project or repository) to apply the filter to must be prefixed with permission.. See the section "Permission Filters" below for more details.
permission.
permission.N - the "root" of a single permission filter, similar to the permission parameter, where "N" is a natural number starting from 1. This allows clients to specify multiple permission filters, by providing consecutive filters as permission.1, permission.2 etc. Note that the filters numbering has to start with 1 and be continuous for all filters to be processed. The total allowed number of permission filters is 50 and all filters exceeding that limit will be dropped. See the section "Permission Filters" below for more details on how the permission filters are processed.
permission.N
permission.1
permission.2
The following three sub-sections list parameters supported for permission filters (where [root] is the root permission filter name, e.g. permission, permission.1 etc.) depending on the permission resource. The system determines which filter to apply (Global, Project or Repository permission) based on the [root] permission value. E.g. ADMIN is a global permission, PROJECT_ADMIN is a project permission and REPO_ADMIN is a repository permission. Note that the parameters for a given resource will be looked up in the order as they are listed below, that is e.g. for a project resource, if both projectId and projectKey are provided, the system will use projectId for the lookup.
[root]
projectId
The permission value under [root] is the only required and recognized parameter, as global permissions do not apply to a specific resource.
Example valid filter: permission=ADMIN.
permission=ADMIN
[root]- specifies the project permission
[root].projectId - specifies the project ID to lookup the project by
[root].projectId
[root].projectKey - specifies the project key to lookup the project by
[root].projectKey
Example valid filter: permission.1=PROJECT_ADMIN&permission.1.projectKey=TEST_PROJECT.
permission.1=PROJECT_ADMIN&permission.1.projectKey=TEST_PROJECT
[root]- specifies the repository permission
[root].projectId - specifies the repository ID to lookup the repository by
[root].projectKey and [root].repositorySlug- specifies the project key and repository slug to lookup the repository by; both values need to be provided for this look up to be triggered
[root].repositorySlug
Example valid filter: permission.2=REPO_ADMIN&permission.2.projectKey=TEST_PROJECT&permission.2.repositorySlug=test_repo.
permission.2=REPO_ADMIN&permission.2.projectKey=TEST_PROJECT&permission.2.repositorySlug=test_repo
GET api/1.0/users
The search request was invalid, which may happen for multiple reasons, among others:
permission filter for project/repository permission with no parameters specifying the project or repository to apply the filter to
invalid permission name
permission filter for a project/repository permission pointing to a non-existent project or repository
The exact reason for the error and - in most cases - the request parameter name that had invalid value - will be provided in the error message.
Update the currently authenticated user's password.
PUT api/1.0/users/credentials
The request was malformed or the old password was incorrect.
Retrieve the user matching the supplied userSlug.
GET api/1.0/users/{userSlug}
200 - userSlug, type: application/json
The user matching the supplied userSlug. Note, this may not be the user's username, always use the user.slug property.
The currently authenticated user has insufficient permissions to view the user.
Update the avatar for the user with the supplied slug.
curl -X POST -u username:password -H "X-Atlassian-Token: no-check" http://example.com/rest/api/latest/users/jdoe/avatar.png -F avatar=@avatar.png
Users are always allowed to update their own avatar. To update someone else's avatar the authenticated user must have global ADMIN permission, or global SYS_ADMIN permission to update a SYS_ADMIN user's avatar.
POST api/1.0/users/{userSlug}/avatar.png
The currently authenticated user has insufficient permissions to update the avatar.
Delete the avatar associated to a user.
Users are always allowed to delete their own avatar. To delete someone else's avatar the authenticated user must have global ADMIN permission, or global SYS_ADMIN permission to update a SYS_ADMIN user's avatar.
DELETE api/1.0/users/{userSlug}/avatar.png
200 - href, type: application/json
The new avatar URL if the local avatar was successfully deleted or did not exist
The authenticated user has insufficient permissions to delete the specified avatar.
Retrieve a map of user setting key values for a specific user identified by the user slug.
GET api/1.0/users/{userSlug}/settings
The user settings for the specified user slug.
Update the entries of a map of user setting key/values for a specific user identified by the user slug.
POST api/1.0/users/{userSlug}/settings
The were updated successfully
WebService::BitbucketServer
https://developer.atlassian.com/bitbucket/server/docs/latest/
Please report any bugs or feature requests on the bugtracker website https://github.com/chazmcgarvey/WebService-BitbucketServer/issues
When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.
Charles McGarvey <chazmcgarvey@brokenzipper.com>
This software is copyright (c) 2017 by Charles McGarvey.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install WebService::BitbucketServer, copy and paste the appropriate command in to your terminal.
cpanm
cpanm WebService::BitbucketServer
CPAN shell
perl -MCPAN -e shell install WebService::BitbucketServer
For more information on module installation, please visit the detailed CPAN module installation guide.