nhyatt/go-bitbucket-v1
1
0
Fork 0
mirror of https://github.com/gfleury/go-bitbucket-v1.git synced 2025-04-05 01:10:12 -05:00
Code Issues Packages Projects Releases Wiki Activity
go-bitbucket-v1/docs/bitbucketV1-rest-swagger.yaml
gfleury eabcdbeccb Updating Swagger files
2020-03-17 21:42:36 -03:00

5274 lines
204 KiB
YAML
Raw Blame History

swagger: "2.0"
host: example.com
info:
title: Bitbucket Server API
description: Bitbucket Server API (former stash).
version: 1.0.0
basePath: /rest/
schemes:
- http
- https
paths:
/api/1.0/admin/cluster:
parameters: []
get:
responses:
"200":
description: Successful Response
description: |-
Gets information about the nodes that currently make up the stash cluster.
<p>
The authenticated user must have the <strong>SYS_ADMIN</strong> permission to call this resource.
operationId: getInformation
/api/1.0/admin/groups:
parameters: []
delete:
parameters:
- description: the name identifying the group to delete
in: query
name: name
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Deletes the specified group, removing them from the system. This also removes any permissions that may have been
granted to the group.
<p>
A user may not delete the last group that is granting them administrative permissions, or a group with greater
permissions than themselves.
<p>
The authenticated user must have the <strong>ADMIN</strong> permission to call this resource.
operationId: deleteGroup
get:
parameters:
- description: if specified only group names containing the supplied string will be returned
in: query
name: filter
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Retrieve a page of groups.
<p>
The authenticated user must have <strong>LICENSED_USER</strong> permission or higher to call this resource.
operationId: getGroupsAdmin
post:
parameters:
- description: Name of the group.
in: query
name: name
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Create a new group.
<p>
The authenticated user must have <strong>ADMIN</strong> permission or higher to call this resource.
operationId: createGroup
/api/1.0/admin/groups/add-user:
parameters: []
post:
parameters: []
responses:
"200":
description: Successful Response
description: |-
<strong>Deprecated since 2.10</strong>. Use /rest/users/add-groups instead.
<p>
Add a user to a group.
<p>
In the request entity, the <em>context</em> attribute is the group and the <em>itemName</em> is the user.
<p>
The authenticated user must have the <strong>ADMIN</strong> permission to call this resource.
operationId: addUserToGroup
/api/1.0/admin/groups/add-users:
parameters: []
post:
parameters: []
responses:
"200":
description: Successful Response
description: |-
Add multiple users to a group.
<p>
The authenticated user must have the <strong>ADMIN</strong> permission to call this resource.
operationId: addUsersToGroup
/api/1.0/admin/groups/more-members:
parameters: []
get:
parameters:
- description: the group which should be used to locate members
in: query
name: context
required: false
type: string
- default: ""
description: |-
if specified only users with usernames, display names or email addresses containing the
supplied string will be returned
in: query
name: filter
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Retrieves a list of users that are members of a specified group.
<p>
The authenticated user must have the <strong>LICENSED_USER</strong> permission to call this resource.
operationId: findUsersInGroup
/api/1.0/admin/groups/more-non-members:
parameters: []
get:
parameters:
- description: the group which should be used to locate non-members
in: query
name: context
required: false
type: string
- default: ""
description: |-
if specified only users with usernames, display names or email addresses containing the
supplied string will be returned
in: query
name: filter
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Retrieves a list of users that are <em>not</em> members of a specified group.
<p>
The authenticated user must have the <strong>LICENSED_USER</strong> permission to call this resource.
operationId: findUsersNotInGroup
/api/1.0/admin/groups/remove-user:
parameters: []
post:
parameters: []
responses:
"200":
description: Successful Response
description: |-
<strong>Deprecated since 2.10</strong>. Use /rest/users/remove-groups instead.
<p>
Remove a user from a group.
<p>
The authenticated user must have the <strong>ADMIN</strong> permission to call this resource.
<p>
In the request entity, the <em>context</em> attribute is the group and the <em>itemName</em> is the user.
operationId: removeUserFromGroup
/api/1.0/admin/license:
parameters: []
get:
responses:
"200":
description: Successful Response
description: |-
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).
<p>
The authenticated user must have <b>ADMIN</b> permission. Unauthenticated users, and non-administrators, are
not permitted to access license details.
operationId: getLicense
post:
parameters: []
responses:
"200":
description: Successful Response
description: |-
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:
<ul>
<li>It is for a different product</li>
<li>It is already expired</li>
</ul>
Otherwise, if the license is updated successfully, details for the new license are returned with a 200 response.
<p>
<b>Warning</b>: 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.
<p>
The authenticated user must have <b>SYS_ADMIN</b> permission. <b>ADMIN</b> users may <i>view</i> the current
license details, but they may not <i>update</i> the license.
operationId: updateLicense
/api/1.0/admin/mail-server:
parameters: []
delete:
responses:
"200":
description: Successful Response
description: |-
Deletes the current mail configuration.
<p>
The authenticated user must have the <strong>SYS_ADMIN</strong> permission to call this resource.
operationId: deleteMailConfig
get:
responses:
"200":
description: Successful Response
description: |-
Retrieves the current mail configuration.
The authenticated user must have the <strong>SYS_ADMIN</strong> permission to call this resource.
operationId: getMailConfig
put:
parameters: []
responses:
"200":
description: Successful Response
description: |-
Updates the mail configuration
The authenticated user must have the <strong>SYS_ADMIN</strong> permission to call this resource.
operationId: setMailConfig
/api/1.0/admin/mail-server/sender-address:
parameters: []
delete:
responses:
"200":
description: Successful Response
description: |-
Clears the server email address.
<p>
The authenticated user must have the <strong>ADMIN</strong> permission to call this resource.
operationId: clearSenderAddress
get:
responses:
"200":
description: Successful Response
description: Retrieves the server email address
operationId: getSenderAddress
put:
parameters: []
responses:
"200":
description: Successful Response
description: |-
Updates the server email address
The authenticated user must have the <strong>ADMIN</strong> permission to call this resource.
operationId: setSenderAddress
/api/1.0/admin/permissions/groups:
parameters: []
delete:
parameters:
- description: the name of the group
in: query
name: name
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Revoke all global permissions for a group.
<p>
The authenticated user must have:
<ul>
<li><strong>ADMIN</strong> permission or higher; and</li>
<li>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)</li>
</ul>
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.
operationId: revokePermissionsForGroupAll
get:
parameters:
- default: ""
description: if specified only group names containing the supplied string will be returned
in: query
name: filter
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Retrieve a page of groups that have been granted at least one global permission.
<p>
The authenticated user must have <strong>ADMIN</strong> permission or higher to call this resource.
operationId: getGroupsWithAnyPermission
put:
parameters:
- description: the permission to grant
in: query
name: permission
required: false
type: string
- description: the names of the groups
in: query
name: name
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Promote or demote a user's global permission level. Available global permissions are:
<ul>
<li>LICENSED_USER</li>
<li>PROJECT_CREATE</li>
<li>ADMIN</li>
<li>SYS_ADMIN</li>
</ul>
See the <a href="https://confluence.atlassian.com/display/BitbucketServer/Global+permissions">Bitbucket Server
documentation</a> for a detailed explanation of what each permission entails.
<p>
The authenticated user must have:
<ul>
<li><strong>ADMIN</strong> permission or higher; and</li>
<li>the permission they are attempting to grant or higher; and</li>
<li>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)</li>
</ul>
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.
operationId: setPermissionForGroups
/api/1.0/admin/permissions/groups/none:
parameters: []
get:
parameters:
- default: ""
description: if specified only group names containing the supplied string will be returned
in: query
name: filter
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Retrieve a page of groups that have no granted global permissions.
<p>
The authenticated user must have <strong>ADMIN</strong> permission or higher to call this resource.
operationId: getGroupsWithoutAnyPermission
/api/1.0/admin/permissions/users:
parameters: []
delete:
parameters:
- description: the name of the user
in: query
name: name
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Revoke all global permissions for a user.
<p>
The authenticated user must have:
<ul>
<li><strong>ADMIN</strong> permission or higher; and</li>
<li>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)</li>
</ul>
to call this resource. In addition, a user may not demote their own permission level.
operationId: revokePermissionsForUserAll
get:
parameters:
- default: ""
description: if specified only user names containing the supplied string will be returned
in: query
name: filter
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Retrieve a page of users that have been granted at least one global permission.
<p>
The authenticated user must have <strong>ADMIN</strong> permission or higher to call this resource.
operationId: getUsersWithAnyPermissionAll
put:
parameters:
- description: the names of the users
in: query
name: name
required: false
type: string
- description: the permission to grant
in: query
name: permission
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Promote or demote the global permission level of a user. Available global permissions are:
<ul>
<li>LICENSED_USER</li>
<li>PROJECT_CREATE</li>
<li>ADMIN</li>
<li>SYS_ADMIN</li>
</ul>
See the <a href="https://confluence.atlassian.com/display/BitbucketServer/Global+permissions">Bitbucket Server
documentation</a> for a detailed explanation of what each permission entails.
<p>
The authenticated user must have:
<ul>
<li><strong>ADMIN</strong> permission or higher; and</li>
<li>the permission they are attempting to grant; and</li>
<li>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)</li>
</ul>
to call this resource. In addition, a user may not demote their own permission level.
operationId: setPermissionForUsers
/api/1.0/admin/permissions/users/none:
parameters: []
get:
parameters:
- default: ""
description: if specified only user names containing the supplied string will be returned
in: query
name: filter
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Retrieve a page of users that have no granted global permissions.
<p>
The authenticated user must have <strong>ADMIN</strong> permission or higher to call this resource.
operationId: getUsersWithoutAnyPermission
"/api/1.0/admin/pull-requests/{scmId}":
parameters:
- description: the id of the scm to get strategies for
in: path
name: scmId
required: true
type: string
get:
responses:
"200":
description: Successful Response
description: |-
Retrieve the merge strategies available for this instance.
<p>
The user must be authenticated to call this resource.
operationId: getMergeConfig
post:
parameters: []
responses:
"200":
description: Successful Response
description: |-
Update the pull request merge strategies for the context repository.
<p>
The authenticated user must have <strong>ADMIN</strong> permission for the context repository to call this
resource.
<p>
Only the strategies provided will be enabled, only one may be set to default
<p>
An explicitly set pull request merge strategy configuration can be deleted by POSTing a document with
an empty "mergeConfig" attribute. i.e:
<pre>
{
"mergeConfig": {
}
}
</pre>
Upon completion of this request, the effective configuration will be the default configuration.
operationId: setMergeConfig
/api/1.0/admin/users:
parameters: []
delete:
parameters:
- description: the username identifying the user to delete
in: query
name: name
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Deletes the specified user, removing them from the system. This also removes any permissions that may have been
granted to the user.
<p>
A user may not delete themselves, and a user with <strong>ADMIN</strong> permissions may not delete a user with
<strong>SYS_ADMIN</strong>permissions.
<p>
The authenticated user must have the <strong>ADMIN</strong> permission to call this resource.
operationId: deleteUser
get:
parameters:
- description: |-
if specified only users with usernames, display name or email addresses containing the supplied
string will be returned
in: query
name: filter
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Retrieve a page of users.
<p>
The authenticated user must have the <strong>LICENSED_USER</strong> permission to call this resource.
operationId: getUsers
post:
parameters:
- description: the username for the new user
in: query
name: name
required: false
type: string
- description: the password for the new user
in: query
name: password
required: false
type: string
- description: the display name for the new user
in: query
name: displayName
required: false
type: string
- description: the e-mail address for the new user
in: query
name: emailAddress
required: false
type: string
- default: true
description: |-
<code>true</code> to add the user to the default group, which can be used to grant them
a set of initial permissions; otherwise, <code>false</code> to not add them to a group
in: query
name: addToDefaultGroup
required: false
type: boolean
- description: |-
if present and not <code>false</code> 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
in: query
name: notify
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Creates a new user from the assembled query parameters.
<p>
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.
<p>
The authenticated user must have the <strong>ADMIN</strong> permission to call this resource.
operationId: createUser
put:
parameters: []
responses:
"200":
description: Successful Response
description: |-
Update a user's details.
<p>
The authenticated user must have the <strong>ADMIN</strong> permission to call this resource.
operationId: updateUserDetails
/api/1.0/admin/users/add-group:
parameters: []
post:
parameters: []
responses:
"200":
description: Successful Response
description: |-
<strong>Deprecated since 2.10</strong>. Use /rest/users/add-groups instead.
<p>
Add a user to a group. This is very similar to <code>groups/add-user</code>, but with the <em>context</em> and
<em>itemName</em> 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.
<p>
In the request entity, the <em>context</em> attribute is the user and the <em>itemName</em> is the group.
<p>
The authenticated user must have the <strong>ADMIN</strong> permission to call this resource.
operationId: addGroupToUser
/api/1.0/admin/users/add-groups:
parameters: []
post:
parameters: []
responses:
"200":
description: Successful Response
description: |-
Add a user to one or more groups.
<p>
The authenticated user must have the <strong>ADMIN</strong> permission to call this resource.
operationId: addUserToGroups
/api/1.0/admin/users/captcha:
parameters: []
delete:
parameters:
- in: query
name: name
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
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.
<p>
The authenticated user must have the <strong>ADMIN</strong> permission to call this resource, and may not clear
the CAPTCHA of a user with greater permissions than themselves.
operationId: clearUserCaptchaChallenge
/api/1.0/admin/users/credentials:
parameters: []
put:
parameters: []
responses:
"200":
description: Successful Response
description: |-
Update a user's password.
<p>
The authenticated user must have the <strong>ADMIN</strong> permission to call this resource, and may not update
the password of a user with greater permissions than themselves.
operationId: updateUserPassword
/api/1.0/admin/users/more-members:
parameters: []
get:
parameters:
- description: the user which should be used to locate groups
in: query
name: context
required: false
type: string
- default: ""
description: if specified only groups with names containing the supplied string will be returned
in: query
name: filter
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Retrieves a list of groups the specified user is a member of.
<p>
The authenticated user must have the <strong>LICENSED_USER</strong> permission to call this resource.
operationId: findGroupsForUser
/api/1.0/admin/users/more-non-members:
parameters: []
get:
parameters:
- description: the user which should be used to locate groups
in: query
name: context
required: false
type: string
- default: ""
description: if specified only groups with names containing the supplied string will be returned
in: query
name: filter
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Retrieves a list of groups the specified user is <em>not</em> a member of.
<p>
The authenticated user must have the <strong>LICENSED_USER</strong> permission to call this resource.
operationId: findOtherGroupsForUser
/api/1.0/admin/users/remove-group:
parameters: []
post:
parameters: []
responses:
"200":
description: Successful Response
description: |-
Remove a user from a group. This is very similar to <code>groups/remove-user</code>, but with the <em>context</em>
and <em>itemName</em> 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.
<p>
In the request entity, the <em>context</em> attribute is the user and the <em>itemName</em> is the group.
<p>
The authenticated user must have the <strong>ADMIN</strong> permission to call this resource.
operationId: removeGroupFromUser
/api/1.0/admin/users/rename:
parameters: []
post:
parameters: []
responses:
"200":
description: Successful Response
description: |-
Rename a user.
<p>
The authenticated user must have the <strong>ADMIN</strong> permission to call this resource.
operationId: renameUser
/api/1.0/application-properties:
parameters: []
get:
responses:
"200":
description: Successful Response
description: |-
Retrieve version information and other application properties.
<p>
No authentication is required to call this resource.
operationId: getApplicationProperties
/api/1.0/dashboard/pull-request-suggestions:
parameters: []
get:
parameters:
- default: "172800"
description: |-
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.
in: query
name: changesSince
required: false
type: string
- default: 3
description: restricts the result set to return at most this many suggestions.
format: int32
in: query
name: limit
required: false
type: integer
responses:
"200":
description: Successful Response
description: |-
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.
<p>
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.
operationId: getPullRequestSuggestions
/api/1.0/dashboard/pull-requests:
parameters: []
get:
parameters:
- description: |-
(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 <strong>OPEN</strong>,
<strong>DECLINED</strong> or <strong>MERGED</strong>.
Omit this parameter to return pull request in any state.
in: query
name: state
required: false
type: string
- description: |-
(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 <strong>REVIEWER</strong>, <strong>AUTHOR</strong> or <strong>PARTICIPANT</strong>.
in: query
name: role
required: false
type: string
- description: |-
(optional, defaults to returning pull requests with any participant status). A comma
separated list of participant status. That is, one or more of
<strong>UNAPPROVED</strong>, <strong>NEEDS_WORK</strong>, or <strong>APPROVED</strong>.
in: query
name: participantStatus
required: false
type: string
- description: |-
(optional, defaults to <strong>NEWEST</strong>) the order to return pull requests in, either
<strong>OLDEST</strong> (as in: "oldest first"), <strong>NEWEST</strong>,
<strong>PARTICIPANT_STATUS</strong>, or <strong>CLOSED_DATE</strong>. Where
<strong>CLOSED_DATE</strong> 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.
in: query
name: order
required: false
type: string
- description: |-
(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.
in: query
name: closedSince
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
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.
operationId: getPullRequests
/api/1.0/groups:
parameters: []
get:
parameters:
- description: if specified only group names containing the supplied string will be returned
in: query
name: filter
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Retrieve a page of group names.
<p>
The authenticated user must have <strong>PROJECT_ADMIN</strong> permission or higher to call this resource.
operationId: getGroups
"/api/1.0/hooks/{hookKey}/avatar":
parameters:
- description: the complete module key of the hook module
in: path
name: hookKey
required: true
type: string
get:
parameters:
- description: |-
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.
in: query
name: version
required: false
type: string
responses:
"200":
description: Successful Response
description: Retrieve the avatar for the project matching the supplied <strong>moduleKey</strong>.
operationId: getAvatar
/api/1.0/inbox/pull-requests:
parameters: []
get:
parameters:
- default: 0
format: int32
in: query
name: start
required: false
type: integer
- default: 25
format: int32
in: query
name: limit
required: false
type: integer
- default: reviewer
in: query
name: role
required: false
type: string
responses:
"200":
description: Successful Response
operationId: getPullRequestsInbox
/api/1.0/inbox/pull-requests/count:
parameters: []
get:
responses:
"200":
description: Successful Response
operationId: getPullRequestCount
"/api/1.0/logs/logger/{loggerName}":
parameters:
- description: the name of the logger.
in: path
name: loggerName
required: true
type: string
get:
responses:
"200":
description: Successful Response
description: |-
Retrieve the current log level for a given logger.
<p>
The authenticated user must have <strong>ADMIN</strong> permission or higher to call this resource.
operationId: getLevel
"/api/1.0/logs/logger/{loggerName}/{levelName}":
parameters:
- description: "the level to set the logger to. Either TRACE, DEBUG, INFO, WARN or ERROR"
in: path
name: levelName
required: true
type: string
- description: the name of the logger.
in: path
name: loggerName
required: true
type: string
put:
responses:
"200":
description: Successful Response
description: |-
Set the current log level for a given logger.
<p>
The authenticated user must have <strong>ADMIN</strong> permission or higher to call this resource.
operationId: setLevel
/api/1.0/logs/rootLogger:
parameters: []
get:
responses:
"200":
description: Successful Response
description: |-
Retrieve the current log level for the root logger.
<p>
The authenticated user must have <strong>ADMIN</strong> permission or higher to call this resource.
operationId: getRootLevel
"/api/1.0/logs/rootLogger/{levelName}":
parameters:
- description: "the level to set the logger to. Either TRACE, DEBUG, INFO, WARN or ERROR"
in: path
name: levelName
required: true
type: string
put:
responses:
"200":
description: Successful Response
description: |-
Set the current log level for the root logger.
<p>
The authenticated user must have <strong>ADMIN</strong> permission or higher to call this resource.
operationId: setRootLevel
/api/1.0/markup/preview:
parameters: []
post:
parameters:
- description: |-
(Optional) The UrlMode used when building the url. One of: ABSOLUTE, RELATIVE and CONFIGURED
By default this is RELATIVE.
in: query
name: urlMode
required: false
type: string
- description: |-
(Optional) Whether the markup implementation should convert newlines to breaks.
By default this is false which reflects the standard markdown specification.
in: query
name: hardwrap
required: false
type: boolean
- description: "(Optional) true if HTML should be escaped in the input markup, false otherwise."
in: query
name: htmlEscape
required: false
type: boolean
responses:
"200":
description: Successful Response
description: |-
Preview the generated html for given markdown contents.
<p>
Only authenticated users may call this resource.
operationId: preview
/api/1.0/profile/recent/repos:
parameters: []
get:
parameters:
- description: |-
(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 <code>REPO_READ</code> permission level will be assumed.
in: query
name: permission
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Retrieve a page of recently accessed repositories for the currently authenticated user.
<p>
Repositories are ordered from most recently to least recently accessed.
<p>
Only authenticated users may call this resource.
operationId: getRepositoriesRecentlyAccessed
/api/1.0/projects:
parameters: []
get:
parameters:
- in: query
name: name
required: false
type: string
- in: query
name: permission
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Retrieve a page of projects.
<p>
Only projects for which the authenticated user has the <strong>PROJECT_VIEW</strong> permission will be returned.
operationId: getProjects
post:
parameters: []
responses:
"200":
description: Successful Response
description: |-
Create a new project.
<p>
To include a custom avatar for the project, the project definition should contain an additional attribute with
the key <code>avatar</code> and the value a data URI containing Base64-encoded image data. The URI should be in
the following format:
<pre>
data:(content type, e.g. image/png);base64,(data)
</pre>
If the data is not Base64-encoded, or if a character set is defined in the URI, or the URI is otherwise invalid,
<em>project creation will fail</em>.
<p>
The authenticated user must have <strong>PROJECT_CREATE</strong> permission to call this resource.
operationId: createProject
"/api/1.0/projects/{projectKey}":
parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
delete:
responses:
"200":
description: Successful Response
description: |-
Delete the project matching the supplied <strong>projectKey</strong>.
<p>
The authenticated user must have <strong>PROJECT_ADMIN</strong> permission for the specified project to call this
resource.
operationId: deleteProject
get:
responses:
"200":
description: Successful Response
description: |-
Retrieve the project matching the supplied <strong>projectKey</strong>.
<p>
The authenticated user must have <strong>PROJECT_VIEW</strong> permission for the specified project to call this
resource.
operationId: getProject
put:
responses:
"200":
description: Successful Response
description: |-
Update the project matching the <strong>projectKey</strong> supplied in the resource path.
<p>
To include a custom avatar for the updated project, the project definition should contain an additional attribute
with the key <code>avatar</code> and the value a data URI containing Base64-encoded image data. The URI should be
in the following format:
<code>
data:(content type, e.g. image/png);base64,(data)
</code>
If the data is not Base64-encoded, or if a character set is defined in the URI, or the URI is otherwise invalid,
<em>project creation will fail</em>.
<p>
The authenticated user must have <strong>PROJECT_ADMIN</strong> permission for the specified project to call this
resource.
operationId: updateProject
"/api/1.0/projects/{projectKey}/avatar.png":
parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
get:
parameters:
- default: 0
description: |-
The desired size of the image. The server will return an image as close as possible to the specified
size.
format: int32
in: query
name: s
required: false
type: integer
responses:
"200":
description: Successful Response
description: |-
Retrieve the avatar for the project matching the supplied <strong>projectKey</strong>.
<p>
The authenticated user must have <strong>PROJECT_VIEW</strong> permission for the specified project to call this
resource.
operationId: getProjectAvatar
post:
responses:
"200":
description: Successful Response
description: |-
Update the avatar for the project matching the supplied <strong>projectKey</strong>.
<p>
This resource accepts POST multipart form data, containing a single image in a form-field named 'avatar'.
<p>
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 <strong>PNG</strong> and
<strong>JPEG</strong> are preferred due to the file size limit.
<p>
This resource has Cross-Site Request Forgery (XSRF) protection. To allow the request to
pass the XSRF check the caller needs to send an <code>X-Atlassian-Token</code> HTTP header with the
value <code>no-check</code>.
<p>
An example <a href="http://curl.haxx.se/">curl</a> request to upload an image name 'avatar.png' would be:
<pre>
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
</pre>
<p>
The authenticated user must have <strong>PROJECT_ADMIN</strong> permission for the specified project to call this
resource.
operationId: uploadAvatarProject
"/api/1.0/projects/{projectKey}/permissions/groups":
parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
delete:
parameters:
- description: the name of the group
in: query
name: name
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Revoke all permissions for the specified project for a group.
<p>
The authenticated user must have <strong>PROJECT_ADMIN</strong> permission for the specified project or a higher
global permission to call this resource.
<p>
In addition, a user may not revoke a group's permissions if it will reduce their own permission level.
operationId: revokePermissionsForGroupProject
get:
parameters:
- description: if specified only group names containing the supplied string will be returned
in: query
name: filter
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Retrieve a page of groups that have been granted at least one permission for the specified project.
<p>
The authenticated user must have <strong>PROJECT_ADMIN</strong> permission for the specified project or a higher
global permission to call this resource.
operationId: getGroupsWithAnyPermissionProject
put:
parameters:
- description: |-
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:
<ul>
<li>PROJECT_READ</li>
<li>PROJECT_WRITE</li>
<li>PROJECT_ADMIN</li>
</ul>
in: query
name: permission
required: false
type: string
- description: the names of the groups
in: query
name: name
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Promote or demote a group's permission level for the specified project.
<p>
The authenticated user must have <strong>PROJECT_ADMIN</strong> 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.
operationId: setPermissionForGroupsProject
"/api/1.0/projects/{projectKey}/permissions/groups/none":
parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
get:
parameters:
- description: if specified only group names containing the supplied string will be returned
in: query
name: filter
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Retrieve a page of groups that have no granted permissions for the specified project.
<p>
The authenticated user must have <strong>PROJECT_ADMIN</strong> permission for the specified project or a higher
global permission to call this resource.
operationId: getGroupsWithoutAnyPermissionProject
"/api/1.0/projects/{projectKey}/permissions/users":
parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
delete:
parameters:
- description: the name of the user
in: query
name: name
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Revoke all permissions for the specified project for a user.
<p>
The authenticated user must have <strong>PROJECT_ADMIN</strong> permission for the specified project or a higher
global permission to call this resource.
<p>
In addition, a user may not revoke their own project permissions if they do not have a higher global permission.
operationId: revokePermissionsForUserProject
get:
parameters:
- description: if specified only group names containing the supplied string will be returned
in: query
name: filter
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Retrieve a page of users that have been granted at least one permission for the specified project.
<p>
The authenticated user must have <strong>PROJECT_ADMIN</strong> permission for the specified project or a higher
global permission to call this resource.
operationId: getUsersWithAnyPermissionProject
put:
parameters:
- description: the names of the users
in: query
name: name
required: false
type: string
- description: |-
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:
<ul>
<li>PROJECT_READ</li>
<li>PROJECT_WRITE</li>
<li>PROJECT_ADMIN</li>
</ul>
in: query
name: permission
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Promote or demote a user's permission level for the specified project.
<p>
The authenticated user must have <strong>PROJECT_ADMIN</strong> 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.
operationId: setPermissionForUsersProject
"/api/1.0/projects/{projectKey}/permissions/users/none":
parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
get:
parameters:
- description: if specified only group names containing the supplied string will be returned
in: query
name: filter
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Retrieve a page of <i>licensed</i> users that have no granted permissions for the specified project.
<p>
The authenticated user must have <strong>PROJECT_ADMIN</strong> permission for the specified project or a higher
global permission to call this resource.
operationId: getUsersWithoutPermissionProject
"/api/1.0/projects/{projectKey}/permissions/{permission}/all":
parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: |-
the permission to grant
Available project permissions are:
<ul>
<li>PROJECT_READ</li>
<li>PROJECT_WRITE</li>
<li>PROJECT_ADMIN</li>
</ul>
in: path
name: permission
required: true
type: string
get:
responses:
"200":
description: Successful Response
description: |-
Check whether the specified permission is the default permission (granted to all users) for a project.
<p>
The authenticated user must have <strong>PROJECT_ADMIN</strong> permission for the specified project or a higher
global permission to call this resource.
operationId: hasAllUserPermission
post:
parameters:
- description: "<em>true</em> to grant the specified permission to all users, or <em>false</em> to revoke it"
in: query
name: allow
required: false
type: boolean
responses:
"200":
description: Successful Response
description: |-
Grant or revoke a project permission to all users, i.e. set the default permission.
<p>
The authenticated user must have <strong>PROJECT_ADMIN</strong> permission for the specified project or a higher
global permission to call this resource.
operationId: modifyAllUserPermission
"/api/1.0/projects/{projectKey}/repos":
parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
get:
responses:
"200":
description: Successful Response
description: |-
Retrieve repositories from the project corresponding to the supplied <strong>projectKey</strong>.
<p>
The authenticated user must have <strong>REPO_READ</strong> permission for the specified project to call this
resource.
operationId: getRepositories
post:
parameters: []
responses:
"200":
description: Successful Response
description: |-
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.
<p>
The authenticated user must have <strong>PROJECT_ADMIN</strong> permission for the context project to call this
resource.
operationId: createRepository
"/api/1.0/projects/{projectKey}/repos/{repositorySlug}":
parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
delete:
responses:
"200":
description: Successful Response
description: |-
Schedule the repository matching the supplied <strong>projectKey</strong> and <strong>repositorySlug</strong> to
be deleted. If the request repository is not present
<p>
The authenticated user must have <strong>REPO_ADMIN</strong> permission for the specified repository to call this
resource.
operationId: deleteRepository
get:
responses:
"200":
description: Successful Response
description: |-
Retrieve the repository matching the supplied <strong>projectKey</strong> and <strong>repositorySlug</strong>.
<p>
The authenticated user must have <strong>REPO_READ</strong> permission for the specified repository to call this
resource.
operationId: getRepository
post:
parameters: []
responses:
"200":
description: Successful Response
description: |-
Create a new repository forked from an existing repository.
<p>
The JSON body for this {@code POST} is not required to contain <i>any</i> properties. Even the name may be
omitted. The following properties will be used, if provided:
<ul>
<li>{@code "name":"Fork name"} - Specifies the forked repository's name
<ul>
<li>Defaults to the name of the origin repository if not specified</li>
</ul>
</li>
<li>{@code "project":{"key":"TARGET_KEY"}} - Specifies the forked repository's target project by key
<ul>
<li>Defaults to the current user's personal project if not specified</li>
</ul>
</li>
</ul>
<p>
The authenticated user must have <strong>REPO_READ</strong> permission for the specified repository and
<strong>PROJECT_ADMIN</strong> on the target project to call this resource. Note that users <i>always</i>
have <b>PROJECT_ADMIN</b> permission on their personal projects.
operationId: forkRepository
put:
parameters: []
responses:
"200":
description: Successful Response
description: |-
Update the repository matching the <strong>repositorySlug</strong> supplied in the resource path.
<p>
The repository's slug is derived from its name. If the name changes the slug may also change.
<p>
This API can be used to move the repository to a different project by setting the new project in the request,
example: {@code {"project":{"key":"NEW_KEY"}}} .
<p>
The authenticated user must have <strong>REPO_ADMIN</strong> permission for the specified repository to call this
resource.
operationId: updateRepository
"/api/1.0/projects/{projectKey}/repos/{repositorySlug}/archive":
parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
get:
parameters:
- description: "the commit to stream an archive of; if not supplied, an archive of the default branch is streamed"
in: query
name: at
required: false
type: string
- description: a filename to include the "Content-Disposition" header
in: query
name: filename
required: false
type: string
- description: "the format to stream the archive in; must be one of: zip, tar, tar.gz or tgz"
in: query
name: format
required: false
type: string
- description: paths to include in the streamed archive; may be repeated to include multiple paths
in: query
name: path
required: false
type: string
- description: |-
a prefix to apply to all entries in the streamed archive; if the supplied prefix does not end
with a trailing <code>/</code>, one will be added automatically
in: query
name: prefix
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Streams an archive of the repository's contents at the requested commit. If no <code>at=</code> commit is
requested, an archive of the default branch is streamed.
<p>
The <code>filename=</code> query parameter may be used to specify the exact filename to include in the
<code>"Content-Disposition"</code> header. If an explicit filename is not provided, one will be automatically
generated based on what is being archived. Its format depends on the <code>at=</code> value:
<ul>
<li>No <code>at=</code> commit:
<code>&lt;slug&gt;-&lt;default-branch-name&gt;@&lt;commit&gt;.&lt;format&gt;</code>;
e.g. example-master@43c2f8a0fe8.zip</li>
<li><code>at=sha</code>: <code>&lt;slug&gt;-&lt;at&gt;.&lt;format&gt;</code>; e.g.
example-09bcbb00100cfbb5310fb6834a1d5ce6cac253e9.tar.gz</li>
<li><code>at=branchOrTag</code>: <code>&lt;slug&gt;-&lt;branchOrTag&gt;@&lt;commit&gt;.&lt;format&gt;</code>;
e.g. example-feature@bbb225f16e1.tar
<ul>
<li>If the branch or tag is qualified (e.g. <code>refs/heads/master</code>, the short name
(<code>master</code>) will be included in the filename</li>
<li>If the branch or tag's <i>short name</i> includes slashes (e.g. <code>release/4.6</code>),
they will be converted to hyphens in the filename (<code>release-4.5</code>)</li>
</ul>
</li>
</ul>
<p>
Archives may be requested in the following formats by adding the <code>format=</code> query parameter:
<ul>
<li><code>zip</code>: A zip file using standard compression (Default)</li>
<li><code>tar</code>: An uncompressed tarball</li>
<li><code>tar.gz</code> or <code>tgz</code>: A GZip-compressed tarball</li>
</ul>
The contents of the archive may be filtered by using the <code>path=</code> query parameter to specify paths to
include. <code>path=</code> may be specified multiple times to include multiple paths.
<p>
The <code>prefix=</code> 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 <code>/</code>, one will be added
automatically. The prefix is <i>always</i> treated as a directory; it is not possible to use it to prepend
characters to the entries in the archive.
<p>
Archives of public repositories may be streamed by any authenticated or anonymous user. Streaming archives for
non-public repositories requires an <i>authenticated user</i> with at least <b>REPO_READ</b> permission.
operationId: getArchive
"/api/1.0/projects/{projectKey}/repos/{repositorySlug}/branches":
parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
get:
parameters:
- description: base branch or tag to compare each branch to (for the metadata providers that uses that information)
in: query
name: base
required: false
type: string
- description: whether to retrieve plugin-provided metadata about each branch
in: query
name: details
required: false
type: boolean
- description: the text to match on
in: query
name: filterText
required: false
type: string
- description: ordering of refs either ALPHABETICAL (by name) or MODIFICATION (last updated)
in: query
name: orderBy
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Retrieve the branches matching the supplied <strong>filterText</strong> param.
<p>
The authenticated user must have <strong>REPO_READ</strong> permission for the specified repository to call this
resource.
operationId: getBranches
post:
parameters: []
responses:
"200":
description: Successful Response
description: |-
Creates a branch using the information provided in the {@link RestCreateBranchRequest request}
<p>
The authenticated user must have <strong>REPO_WRITE</strong> permission for the context repository to call
this resource.
operationId: createBranch
"/api/1.0/projects/{projectKey}/repos/{repositorySlug}/branches/default":
parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
get:
responses:
"200":
description: Successful Response
description: |-
Get the default branch of the repository.
<p>
The authenticated user must have <strong>REPO_READ</strong> permission for the specified repository to call this
resource.
operationId: getDefaultBranch
put:
parameters: []
responses:
"200":
description: Successful Response
description: |-
Update the default branch of a repository.
<p>
The authenticated user must have <strong>REPO_ADMIN</strong> permission for the specified repository to call this
resource.
operationId: setDefaultBranch
"/api/1.0/projects/{projectKey}/repos/{repositorySlug}/browse":
parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
get:
parameters:
- default: ""
description: the commit ID or ref to retrieve the content for.
in: query
name: at
required: false
type: string
- default: false
description: if true only the type will be returned for the file path instead of the contents.
in: query
name: type
required: false
type: boolean
- description: if present the blame will be returned for the file as well.
in: query
name: blame
required: false
type: string
- description: if present and used with blame only the blame is retrieved instead of the contents.
in: query
name: noContent
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Retrieve a page of content for a file path at a specified revision.
<p>
The authenticated user must have <strong>REPO_READ</strong> permission for the specified repository to call this
resource.
operationId: getContentBrowse
"/api/1.0/projects/{projectKey}/repos/{repositorySlug}/browse/{path}":
parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
- default: ""
description: the file path to retrieve content from
in: path
name: path
required: true
type: string
get:
parameters:
- default: ""
description: the commit ID or ref to retrieve the content for.
in: query
name: at
required: false
type: string
- default: false
description: if true only the type will be returned for the file path instead of the contents.
in: query
name: type
required: false
type: boolean
- description: if present the blame will be returned for the file as well.
in: query
name: blame
required: false
type: string
- description: if present and used with blame only the blame is retrieved instead of the contents.
in: query
name: noContent
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Retrieve a page of content for a file path at a specified revision.
<p>
The authenticated user must have <strong>REPO_READ</strong> permission for the specified repository to call this
resource.
operationId: getContentFile
put:
responses:
"200":
description: Successful Response
description: |-
Update the content of <code>path</code>, on the given <code>repository</code> and <code>branch</code>.
<p>
This resource accepts PUT multipart form data, containing the file in a form-field named <code>content</code>.
<p>
An example <a href="http://curl.haxx.se/">curl</a> request to update 'README.md' would be:
<pre>
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
</pre>
<p>
<ui>
<li>branch: the branch on which the <code>path</code> should be modified or created</li>
<li>content: the full content of the file at <code>path</code> </li>
<li>message: the message associated with this change, to be used as the commit message.
Or null if the default message should be used.</li>
<li>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</li>
</ui>
<p>
The file can be updated or created on a new branch. In this case, the <code>sourceBranch</code> parameter should
be provided to identify the starting point for the new branch and the <code>branch</code> parameter identifies
the branch to create the new commit on.
operationId: editFile
"/api/1.0/projects/{projectKey}/repos/{repositorySlug}/changes":
parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
get:
parameters:
- description: |-
the commit to which <code>until</code> should be compared to produce a page of changes.
If not specified the commit's first parent is assumed (if one exists)
in: query
name: since
required: false
type: string
- description: the commit to retrieve changes for
in: query
name: until
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Retrieve a page of changes made in a specified commit.
<p>
<strong>Note:</strong> The implementation will apply a hard cap ({@code page.max.changes}) and it is not
possible to request subsequent content when that cap is exceeded.
<p>
The authenticated user must have <strong>REPO_READ</strong> permission for the specified repository to call this
resource.
operationId: getChanges
"/api/1.0/projects/{projectKey}/repos/{repositorySlug}/commits":
parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
get:
parameters:
- default: false
description: |-
if <code>true</code>, the commit history of the specified file will be followed past renames.
Only valid for a path to a single file.
in: query
name: followRenames
required: false
type: boolean
- default: false
description: "<code>true</code> to ignore missing commits, <code>false</code> otherwise"
in: query
name: ignoreMissing
required: false
type: boolean
- description: |-
if present, controls how merge commits should be filtered. Can be either <code>exclude</code>,
to exclude merge commits, <code>include</code>, to include both merge commits and non-merge
commits or <code>only</code>, to only return merge commits.
in: query
name: merges
required: false
type: string
- description: an optional path to filter commits by
in: query
name: path
required: false
type: string
- description: the commit ID or ref (exclusively) to retrieve commits after
in: query
name: since
required: false
type: string
- description: the commit ID (SHA1) or ref (inclusively) to retrieve commits before
in: query
name: until
required: false
type: string
- default: false
description: optionally include the total number of commits and total number of unique authors
in: query
name: withCounts
required: false
type: boolean
responses:
"200":
description: Successful Response
description: |-
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.
<p>
The authenticated user must have <b>REPO_READ</b> permission for the specified repository to call this
resource.
operationId: getCommits
"/api/1.0/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}":
parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
- description: the commit ID to retrieve
in: path
name: commitId
required: true
type: string
get:
parameters:
- description: |-
an optional path to filter the commit by. If supplied the details returned <i>may not</i>
be for the specified commit. Instead, starting from the specified commit, they will be the
details for the first commit affecting the specified path.
in: query
name: path
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Retrieve a single commit <i>identified by its ID</i>>. In general, that ID is a SHA1. <u>From 2.11, ref names
like "refs/heads/master" are no longer accepted by this resource.</u>
<p>
The authenticated user must have <strong>REPO_READ</strong> permission for the specified repository to call this
resource.
operationId: getCommit
? "/api/1.0/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/changes"
: parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
- description: the commit to retrieve changes for
in: path
name: commitId
required: true
type: string
get:
parameters:
- description: |-
the commit to which <code>until</code> should be compared to produce a page of changes.
If not specified the commit's first parent is assumed (if one exists)
in: query
name: since
required: false
type: string
- default: true
description: |-
{@code true} to apply comment counts in the changes (the default); otherwise, {@code false}
to stream changes without comment counts
in: query
name: withComments
required: false
type: boolean
responses:
"200":
description: Successful Response
description: |-
Retrieve a page of changes made in a specified commit.
<p>
<strong>Note:</strong> The implementation will apply a hard cap ({@code page.max.changes}) and it is not
possible to request subsequent content when that cap is exceeded.
<p>
The authenticated user must have <strong>REPO_READ</strong> permission for the specified repository to call this
resource.
operationId: getChangesFile
? "/api/1.0/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/comments"
: parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
- description: the commit to which the comments must be anchored
in: path
name: commitId
required: true
type: string
get:
parameters:
- description: the path to the file on which comments were made
in: query
name: path
required: false
type: string
- description: |-
For a merge commit, a parent can be provided to specify which diff the comments are on. For
a commit range, a {@code sinceId} can be provided to specify where the comments are anchored
from.
in: query
name: since
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Retrieves the commit discussion comments that match the specified search criteria.
<p>
It is possible to retrieve commit discussion comments that are anchored to a range of commits by providing the
{@code sinceId} that the comments anchored from.
<p>
The authenticated user must have <strong>REPO_READ</strong> permission for the repository that the commit
is in to call this resource.
operationId: getComments
post:
parameters:
- description: |-
For a merge commit, a parent can be provided to specify which diff the comments should be on. For
a commit range, a {@code sinceId} can be provided to specify where the comments should be
anchored from.
in: query
name: since
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Add a new comment.
<p>
Comments can be added in a few places by setting different attributes:
<p>
General commit comment:
<pre>
{
"text": "An insightful general comment on a commit."
}
</pre>
Reply to a comment:
<pre>
{
"text": "A measured reply.",
"parent": {
"id": 1
}
}
</pre>
General file comment:
<pre>
{
"text": "An insightful general comment on a file.",
"anchor": {
"diffType": "COMMIT",
"fromHash": "6df3858eeb9a53a911cd17e66a9174d44ffb02cd",
"path": "path/to/file",
"srcPath": "path/to/file",
"toHash": "04c7c5c931b9418ca7b66f51fe934d0bd9b2ba4b"
}
}
</pre>
File line comment:
<pre>
{
"text": "A pithy comment on a particular line within a file.",
"anchor": {
"diffType": "COMMIT",
"line": 1,
"lineType": "CONTEXT",
"fileType": "FROM",
"fromHash": "6df3858eeb9a53a911cd17e66a9174d44ffb02cd",
"path": "path/to/file",
"srcPath": "path/to/file",
"toHash": "04c7c5c931b9418ca7b66f51fe934d0bd9b2ba4b"
}
}
</pre>
<strong>Note: general file comments are an experimental feature and may change in the near future!</strong>
<p>
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.
<p>
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:
<ul>
<li>'ADDED' - for an added line;</li>
<li>'REMOVED' - for a removed line; or</li>
<li>'CONTEXT' - for a line that was unmodified but is in the vicinity of the diff.</li>
</ul>
'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:
<ul>
<li>'FROM' - the source file of the diff</li>
<li>'TO' - the destination file of the diff</li>
</ul>
If the current user is not a participant the user is added as one and updated to watch the commit.
<p>
The authenticated user must have <strong>REPO_READ</strong> permission for the repository that the commit
is in to call this resource.
operationId: createComment
? "/api/1.0/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/comments/{commentId}"
: parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
- description: the commit to which the comments must be anchored
in: path
name: commitId
required: true
type: string
- description: the ID of the comment to retrieve
format: int64
in: path
name: commentId
required: true
type: integer
delete:
parameters:
- default: -1
description: |-
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.
format: int32
in: query
name: version
required: false
type: integer
responses:
"200":
description: Successful Response
description: |-
Delete a commit comment. Anyone can delete their own comment. Only users with <strong>REPO_ADMIN</strong>
and above may delete comments created by other users. Comments which have replies <i>may not be deleted</i>,
regardless of the user's granted permissions.
<p>
The authenticated user must have <strong>REPO_READ</strong> permission for the repository that the commit
is in to call this resource.
operationId: deleteComment
get:
responses:
"200":
description: Successful Response
description: |-
Retrieves a commit discussion comment.
<p>
The authenticated user must have <strong>REPO_READ</strong> permission for the repository that the commit
is in to call this resource.
operationId: getComment
put:
parameters: []
responses:
"200":
description: Successful Response
description: |-
Update the text of a comment. Only the user who created a comment may update it.
<p>
<strong>Note:</strong> the supplied supplied JSON object must contain a <code>version</code> 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.
<p>
The authenticated user must have <strong>REPO_READ</strong> permission for the repository that the commit
is in to call this resource.
operationId: updateComment
? "/api/1.0/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/diff"
: parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
- in: path
name: commitId
required: true
type: string
get:
parameters:
- default: false
description: |-
{@code true} to automatically try to find the source path when it's not provided,
{@code false} otherwise. Requires the {@code path} to be provided.
in: query
name: autoSrcPath
required: false
type: boolean
- default: -1
description: the number of context lines to include around added/removed lines in the diff
format: int32
in: query
name: contextLines
required: false
type: integer
- description: the base revision to diff from. If omitted the parent revision of the until revision is used
in: query
name: since
required: false
type: string
- description: "the source path for the file, if it was copied, moved or renamed"
in: query
name: srcPath
required: false
type: string
- description: "optional whitespace flag which can be set to {@code ignore-all}"
in: query
name: whitespace
required: false
type: string
- default: true
description: |-
{@code true} to embed comments in the diff (the default); otherwise {@code false}
to stream the diff without comments
in: query
name: withComments
required: false
type: boolean
responses:
"200":
description: Successful Response
description: |-
Retrieve the diff between two provided revisions.
<p>
<strong>Note:</strong> This resource is currently <i>not paged</i>. 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 {@code truncated} flags will be set to
{@code true} on the {@code "segments"}, {@code "hunks"} and {@code "diffs"} properties, as well as the top-level
object, in the returned JSON response.
<p>
The authenticated user must have <strong>REPO_READ</strong> permission for the specified repository to call this
resource.
operationId: streamDiffCommit
? "/api/1.0/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/diff/{path}"
: parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
- in: path
name: commitId
required: true
type: string
- description: the path to the file which should be diffed (optional)
in: path
name: path
required: true
type: string
get:
parameters:
- default: false
description: |-
{@code true} to automatically try to find the source path when it's not provided,
{@code false} otherwise. Requires the {@code path} to be provided.
in: query
name: autoSrcPath
required: false
type: boolean
- default: -1
description: the number of context lines to include around added/removed lines in the diff
format: int32
in: query
name: contextLines
required: false
type: integer
- description: the base revision to diff from. If omitted the parent revision of the until revision is used
in: query
name: since
required: false
type: string
- description: "the source path for the file, if it was copied, moved or renamed"
in: query
name: srcPath
required: false
type: string
- description: "optional whitespace flag which can be set to {@code ignore-all}"
in: query
name: whitespace
required: false
type: string
- default: true
description: |-
{@code true} to embed comments in the diff (the default); otherwise {@code false}
to stream the diff without comments
in: query
name: withComments
required: false
type: boolean
responses:
"200":
description: Successful Response
description: |-
Retrieve the diff between two provided revisions.
<p>
<strong>Note:</strong> This resource is currently <i>not paged</i>. 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 {@code truncated} flags will be set to
{@code true} on the {@code "segments"}, {@code "hunks"} and {@code "diffs"} properties, as well as the top-level
object, in the returned JSON response.
<p>
The authenticated user must have <strong>REPO_READ</strong> permission for the specified repository to call this
resource.
operationId: streamDiffCommits
? "/api/1.0/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/watch"
: parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
- description: "the <i>full {@link Commit#getId() ID}</i> of the commit within the repository"
in: path
name: commitId
required: true
type: string
delete:
responses:
"200":
description: Successful Response
description: |-
Removes the authenticated user as a watcher for the specified commit.
<p>
The authenticated user must have <strong>REPO_READ</strong> permission for the repository containing the commit
to call this resource.
operationId: unwatch
post:
responses:
"200":
description: Successful Response
description: |-
Adds the authenticated user as a watcher for the specified commit.
<p>
The authenticated user must have <strong>REPO_READ</strong> permission for the repository containing the commit
to call this resource.
operationId: watchCommit
"/api/1.0/projects/{projectKey}/repos/{repositorySlug}/compare/changes":
parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
get:
parameters:
- description: the source commit (can be a partial/full commit ID or qualified/unqualified ref name)
in: query
name: from
required: false
type: string
- description: the target commit (can be a partial/full commit ID or qualified/unqualified ref name)
in: query
name: to
required: false
type: string
- default: ""
description: |-
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 <em>fromRepo=42</em> or by its project key plus its repo slug separated by
a slash: <em>fromRepo=projectKey/repoSlug</em>
in: query
name: fromRepo
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Gets the file changes available in the {@code from} commit but not in the {@code to} commit.
<p>
If either the {@code from} or {@code to} commit are not specified, they will be replaced by the
default branch of their containing repository.
operationId: streamChangesCompare
"/api/1.0/projects/{projectKey}/repos/{repositorySlug}/compare/commits":
parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
get:
parameters:
- description: the source commit (can be a partial/full commit ID or qualified/unqualified ref name)
in: query
name: from
required: false
type: string
- description: the target commit (can be a partial/full commit ID or qualified/unqualified ref name)
in: query
name: to
required: false
type: string
- default: ""
description: |-
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 <em>fromRepo=42</em> or by its project key plus its repo slug separated by
a slash: <em>fromRepo=projectKey/repoSlug</em>
in: query
name: fromRepo
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Gets the commits accessible from the {@code from} commit but not in the {@code to} commit.
<p>
If either the {@code from} or {@code to} commit are not specified, they will be replaced by the
default branch of their containing repository.
operationId: streamCommits
"/api/1.0/projects/{projectKey}/repos/{repositorySlug}/compare/diff{path}":
parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
- description: the path to the file to diff (optional)
in: path
name: path
required: true
type: string
get:
parameters:
- description: the source commit (can be a partial/full commit ID or qualified/unqualified ref name)
in: query
name: from
required: false
type: string
- description: the target commit (can be a partial/full commit ID or qualified/unqualified ref name)
in: query
name: to
required: false
type: string
- default: ""
description: |-
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 <em>fromRepo=42</em> or by its project key plus its repo slug separated by
a slash: <em>fromRepo=projectKey/repoSlug</em>
in: query
name: fromRepo
required: false
type: string
- in: query
name: srcPath
required: false
type: string
- default: -1
description: an optional number of context lines to include around each added or removed lines in the diff
format: int32
in: query
name: contextLines
required: false
type: integer
- description: an optional whitespace flag which can be set to <code>ignore-all</code>
in: query
name: whitespace
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Gets a diff of the changes available in the {@code from} commit but not in the {@code to} commit.
<p>
If either the {@code from} or {@code to} commit are not specified, they will be replaced by the
default branch of their containing repository.
operationId: streamDiffCompare
"/api/1.0/projects/{projectKey}/repos/{repositorySlug}/diff":
parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
get:
parameters:
- default: -1
description: the number of context lines to include around added/removed lines in the diff
format: int32
in: query
name: contextLines
required: false
type: integer
- description: the base revision to diff from. If omitted the parent revision of the until revision is used
in: query
name: since
required: false
type: string
- description: "the source path for the file, if it was copied, moved or renamed"
in: query
name: srcPath
required: false
type: string
- description: the target revision to diff to (required)
in: query
name: until
required: false
type: string
- description: optional whitespace flag which can be set to <code>ignore-all</code>
in: query
name: whitespace
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Retrieve the diff for a specified file path between two provided revisions.
<p>
<strong>Note:</strong> This resource is currently <i>not paged</i>. 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 <code>truncated</code> flags will be set to
<code>true</code> on the segments, hunks and diffs substructures in the returned JSON response.
<p>
The authenticated user must have <strong>REPO_READ</strong> permission for the specified repository to call this
resource.
operationId: streamDiffRepository
"/api/1.0/projects/{projectKey}/repos/{repositorySlug}/diff/{path}":
parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
- description: the path to the file which should be diffed (required)
in: path
name: path
required: true
type: string
get:
parameters:
- default: -1
description: the number of context lines to include around added/removed lines in the diff
format: int32
in: query
name: contextLines
required: false
type: integer
- description: the base revision to diff from. If omitted the parent revision of the until revision is used
in: query
name: since
required: false
type: string
- description: "the source path for the file, if it was copied, moved or renamed"
in: query
name: srcPath
required: false
type: string
- description: the target revision to diff to (required)
in: query
name: until
required: false
type: string
- description: optional whitespace flag which can be set to <code>ignore-all</code>
in: query
name: whitespace
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Retrieve the diff for a specified file path between two provided revisions.
<p>
<strong>Note:</strong> This resource is currently <i>not paged</i>. 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 <code>truncated</code> flags will be set to
<code>true</code> on the segments, hunks and diffs substructures in the returned JSON response.
<p>
The authenticated user must have <strong>REPO_READ</strong> permission for the specified repository to call this
resource.
operationId: streamDiffRepositoryFile
"/api/1.0/projects/{projectKey}/repos/{repositorySlug}/files":
parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
get:
parameters:
- description: |-
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.
in: query
name: at
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
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.
<p>
The authenticated user must have <strong>REPO_READ</strong> permission for the specified repository to call this
resource.
operationId: streamFiles
"/api/1.0/projects/{projectKey}/repos/{repositorySlug}/files/{path}":
parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
- default: ""
description: the directory to list files for.
in: path
name: path
required: true
type: string
get:
parameters:
- description: |-
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.
in: query
name: at
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
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.
<p>
The authenticated user must have <strong>REPO_READ</strong> permission for the specified repository to call this
resource.
operationId: streamFilesRepository
"/api/1.0/projects/{projectKey}/repos/{repositorySlug}/forks":
parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
get:
responses:
"200":
description: Successful Response
description: |-
Retrieve repositories which have been forked from this one. Unlike {@link #getRelatedRepositories(Repository,
PageRequest) 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.
<p>
Only repositories to which the authenticated user has <b>REPO_READ</b> permission will be included, even
if other repositories have been forked from this one.
operationId: getForkedRepositories
"/api/1.0/projects/{projectKey}/repos/{repositorySlug}/last-modified":
parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
get:
parameters:
- description: the commit to use as the starting point when listing files and calculating modifications
in: query
name: at
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Streams files in the requested <code>path</code> with the last commit to modify each file. Commit modifications
are traversed starting from the <code>at</code> commit or, if not specified, from the tip of the default branch.
<p>
Unless the repository is public, the authenticated user must have <b>REPO_READ</b> access to call this resource.
operationId: stream
"/api/1.0/projects/{projectKey}/repos/{repositorySlug}/last-modified/{path}":
parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
- description: the path within the repository whose files should be streamed
in: path
name: path
required: true
type: string
get:
parameters:
- description: the commit to use as the starting point when listing files and calculating modifications
in: query
name: at
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Streams files in the requested <code>path</code> with the last commit to modify each file. Commit modifications
are traversed starting from the <code>at</code> commit or, if not specified, from the tip of the default branch.
<p>
Unless the repository is public, the authenticated user must have <b>REPO_READ</b> access to call this resource.
operationId: streamFilesLastMofied
"/api/1.0/projects/{projectKey}/repos/{repositorySlug}/participants":
parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
get:
parameters:
- default: incoming
description: |-
(optional, defaults to <strong>INCOMING</strong>) the direction relative to the specified
repository. Either <strong>INCOMING</strong> or <strong>OUTGOING</strong>.
in: query
name: direction
required: false
type: string
- description: |-
(optional) return only users, whose username, name or email address <i>contain</i>
the {@code filter} value
in: query
name: filter
required: false
type: string
- description: |-
(optional) The role associated with the pull request participant.
This must be one of {@code AUTHOR}, {@code REVIEWER}, or{@code PARTICIPANT}
in: query
name: role
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Retrieve a page of participant users for all the pull requests to or from the specified repository.
<p>
<p>
Optionally clients can specify following filters.
operationId: search
"/api/1.0/projects/{projectKey}/repos/{repositorySlug}/permissions/groups":
parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
delete:
parameters:
- description: the name of the group
in: query
name: name
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Revoke all permissions for the specified repository for a group.
<p>
The authenticated user must have <strong>REPO_ADMIN</strong> permission for the specified repository or a higher
project or global permission to call this resource.
<p>
In addition, a user may not revoke a group's permissions if it will reduce their own permission level.
operationId: revokePermissionsForGroup
get:
parameters:
- description: if specified only group names containing the supplied string will be returned
in: query
name: filter
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Retrieve a page of groups that have been granted at least one permission for the specified repository.
<p>
The authenticated user must have <strong>REPO_ADMIN</strong> permission for the specified repository or a higher
project or global permission to call this resource.
operationId: getGroupsWithAnyPermissionRepository
put:
parameters:
- description: the permission to grant
in: query
name: permission
required: false
type: string
- description: the names of the groups
in: query
name: name
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Promote or demote a group's permission level for the specified repository. Available repository permissions are:
<ul>
<li>REPO_READ</li>
<li>REPO_WRITE</li>
<li>REPO_ADMIN</li>
</ul>
See the <a href="https://confluence.atlassian.com/display/BitbucketServer/Using+repository+permissions">Bitbucket
Server documentation</a> for a detailed explanation of what each permission entails.
<p>
The authenticated user must have <strong>REPO_ADMIN</strong> 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.
operationId: setPermissionForGroup
? "/api/1.0/projects/{projectKey}/repos/{repositorySlug}/permissions/groups/none"
: parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
get:
parameters:
- description: if specified only group names containing the supplied string will be returned
in: query
name: filter
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Retrieve a page of groups that have no granted permissions for the specified repository.
<p>
The authenticated user must have <strong>REPO_ADMIN</strong> permission for the specified repository or a higher
project or global permission to call this resource.
operationId: getGroupsWithoutAnyPermissionRepository
"/api/1.0/projects/{projectKey}/repos/{repositorySlug}/permissions/users":
parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
delete:
parameters:
- description: the name of the user
in: query
name: name
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Revoke all permissions for the specified repository for a user.
<p>
The authenticated user must have <strong>REPO_ADMIN</strong> permission for the specified repository or a higher
project or global permission to call this resource.
<p>
In addition, a user may not revoke their own repository permissions if they do not have a higher
project or global permission.
operationId: revokePermissionsForUser
get:
parameters:
- description: if specified only group names containing the supplied string will be returned
in: query
name: filter
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Retrieve a page of users that have been granted at least one permission for the specified repository.
<p>
The authenticated user must have <strong>REPO_ADMIN</strong> permission for the specified repository or a higher
project or global permission to call this resource.
operationId: getUsersWithAnyPermission
put:
parameters:
- description: the names of the users
in: query
name: name
required: false
type: string
- description: the permission to grant
in: query
name: permission
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Promote or demote a user's permission level for the specified repository. Available repository permissions are:
<ul>
<li>REPO_READ</li>
<li>REPO_WRITE</li>
<li>REPO_ADMIN</li>
</ul>
See the <a href="https://confluence.atlassian.com/display/BitbucketServer/Using+repository+permissions">Bitbucket
Server documentation</a> for a detailed explanation of what each permission entails.
<p>
The authenticated user must have <strong>REPO_ADMIN</strong> 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.
operationId: setPermissionForUser
? "/api/1.0/projects/{projectKey}/repos/{repositorySlug}/permissions/users/none"
: parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
get:
parameters:
- description: if specified only group names containing the supplied string will be returned
in: query
name: filter
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Retrieve a page of <i>licensed</i> users that have no granted permissions for the specified repository.
<p>
The authenticated user must have <strong>REPO_ADMIN</strong> permission for the specified repository or a higher
project or global permission to call this resource.
operationId: getUsersWithoutPermission
"/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests":
parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
get:
parameters:
- default: incoming
description: |-
(optional, defaults to <strong>INCOMING</strong>) the direction relative to the specified
repository. Either <strong>INCOMING</strong> or <strong>OUTGOING</strong>.
in: query
name: direction
required: false
type: string
- description: |-
(optional) a <i>fully-qualified</i> branch ID to find pull requests to or from,
such as {@code refs/heads/master}
in: query
name: at
required: false
type: string
- description: |-
(optional, defaults to <strong>OPEN</strong>). Supply <strong>ALL</strong> to return pull request
in any state. If a state is supplied only pull requests in the specified state will be returned.
Either <strong>OPEN</strong>, <strong>DECLINED</strong> or <strong>MERGED</strong>.
in: query
name: state
required: false
type: string
- description: |-
(optional, defaults to <strong>NEWEST</strong>) the order to return pull requests in, either
<strong>OLDEST</strong> (as in: "oldest first") or <strong>NEWEST</strong>.
in: query
name: order
required: false
type: string
- default: true
description: "(optional) defaults to true, whether to return additional pull request attributes"
in: query
name: withAttributes
required: false
type: boolean
- default: true
description: "(optional) defaults to true, whether to return additional pull request properties"
in: query
name: withProperties
required: false
type: boolean
responses:
"200":
description: Successful Response
description: |-
Retrieve a page of pull requests to or from the specified repository.
<p>
The authenticated user must have <strong>REPO_READ</strong> permission for the specified repository to call
this resource.
Optionally clients can specify PR participant filters. Each filter has a mandatory {@code username.N}
parameter, and the optional {@code role.N} and {@code approved.N} parameters.
<ul>
<li>
{@code 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 {@code username.1}, {@code 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.
</li>
<li>
{@code role.N}(optional) the role associated with {@code username.N}.
This must be one of {@code AUTHOR}, {@code REVIEWER}, or{@code PARTICIPANT}
</li>
<li>
{@code approved.N}(optional) the approved status associated with {@code username.N}.
That is whether {@code username.N} has approved the PR. Either {@code true}, or {@code false}
</li>
</ul>
operationId: getPage
post:
parameters: []
responses:
"200":
description: Successful Response
description: |-
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 {@link Repository#getHierarchyId() hierarchy}.
<p>
The authenticated user must have <strong>REPO_READ</strong> permission for the "from" and "to"repositories to
call this resource.
operationId: create
? "/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}"
: parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
- description: the ID of the pull request within the repository
format: int64
in: path
name: pullRequestId
required: true
type: integer
delete:
parameters: []
responses:
"200":
description: Successful Response
description: |-
Deletes a pull request.
<p>
To call this resource, users must be authenticated and have permission to view the pull request.
Additionally, they must:
<ul>
<li>
be the pull request author, if the system is configured to allow authors to delete their own
pull requests (this is the default) OR
</li>
<li>have repository administrator permission for the repository the pull request is targeting</li>
</ul>
A body containing the version of the pull request must be provided with this request.
<pre><code>{ "version": 1 }</code></pre>
operationId: delete
get:
responses:
"200":
description: Successful Response
description: |-
Retrieve a pull request.
<p>
The authenticated user must have <strong>REPO_READ</strong> permission for the repository that this pull request
targets to call this resource.
operationId: get
put:
parameters: []
responses:
"200":
description: Successful Response
description: |-
Update the title, description, reviewers or destination branch of an existing pull request.
<p>
<strong>Note:</strong> the <em>reviewers</em> list may be updated using this resource. However the
<em>author</em> and <em>participants</em> list may not.
<p>
The authenticated user must either:
<ul>
<li>be the author of the pull request and have the <strong>REPO_READ</strong> permission for the repository
that this pull request targets; or</li>
<li>have the <strong>REPO_WRITE</strong> permission for the repository that this pull request targets</li>
</ul>
to call this resource.
operationId: update
? "/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/activities"
: parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
- description: the id of the pull request within the repository
format: int64
in: path
name: pullRequestId
required: true
type: integer
get:
parameters:
- description: (optional) the id of the activity item to use as the first item in the returned page
format: int64
in: query
name: fromId
required: false
type: integer
- description: |-
(required if <strong>fromId</strong> is present) the type of the activity item specified by
<strong>fromId</strong> (either <strong>COMMENT</strong> or <strong>ACTIVITY</strong>)
in: query
name: fromType
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Retrieve a page of activity associated with a pull request.
<p>
Activity items include comments, approvals, rescopes (i.e. adding and removing of commits), merges and more.
<p>
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.
<p>
The authenticated user must have <strong>REPO_READ</strong> permission for the repository that this pull request
targets to call this resource.
operationId: getActivities
? "/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/approve"
: parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
- description: the id of the pull request within the repository
format: int64
in: path
name: pullRequestId
required: true
type: integer
delete:
responses:
"200":
description: Successful Response
description: |-
Remove approval from a pull request as the current user. This does not remove the user as a participant.
<p>
The authenticated user must have <strong>REPO_READ</strong> permission for the repository that this pull request
targets to call this resource.
<p>
<strong>Deprecated since 4.2</strong>. Use
/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/participants/{userSlug} instead
operationId: withdrawApproval
post:
responses:
"200":
description: Successful Response
description: |-
Approve a pull request as the current user. Implicitly adds the user as a participant if they are not already.
<p>
The authenticated user must have <strong>REPO_READ</strong> permission for the repository that this pull request
targets to call this resource.
<p>
<strong>Deprecated since 4.2</strong>. Use
/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/participants/{userSlug} instead
operationId: approve
? "/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/changes"
: parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
- description: the id of the pull request within the repository
format: int64
in: path
name: pullRequestId
required: true
type: integer
get:
parameters:
- default: ALL
description: |-
{@code UNREVIEWED} to stream the unreviewed changes for the current user (if they exist);
{@code RANGE} to stream changes between two arbitrary commits (requires {@code sinceId} and
{@code untilId}); otherwise {@code ALL} to stream all changes (the default)
in: query
name: changeScope
required: false
type: string
- description: "the since commit hash to stream changes for a {@code RANGE} arbitrary change scope"
in: query
name: sinceId
required: false
type: string
- description: "the until commit hash to stream changes for a {@code RANGE} arbitrary change scope"
in: query
name: untilId
required: false
type: string
- default: true
description: |-
{@code true} to apply comment counts in the changes (the default); otherwise, {@code false}
to stream changes without comment counts
in: query
name: withComments
required: false
type: boolean
responses:
"200":
description: Successful Response
description: |-
Gets changes for the specified PullRequest.
<p>
If the {@code changeScope} query parameter is set to {@code unreviewed}, the application will attempt to stream
unreviewed changes based on the {@code lastReviewedCommit} of the current user, which are the changes between the
{@code lastReviewedCommit} and the latest commit of the source branch. The current user is considered to
<i>not</i> have any unreviewed changes for the pull request when the {@code lastReviewedCommit} is either
{@code 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 {@code changeScope} parameter included in the
properties map of the response.
<p>
Note: This resource is currently <i>not paged</i>. 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.
<p>
The authenticated user must have <strong>REPO_READ</strong> permission for the repository that this pull request
targets to call this resource.
operationId: streamChanges
? "/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/comments"
: parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
- description: the id of the pull request within the repository
format: int64
in: path
name: pullRequestId
required: true
type: integer
get:
parameters:
- default: ACTIVE
description: |-
{@code ACTIVE} to stream the active comments;
{@code ORPHANED} to stream the orphaned comments;
{@code ALL} to stream both the active and the orphaned comments;
in: query
name: anchorState
required: false
type: string
- description: |-
{@code EFFECTIVE} to stream the comments related to the effective diff of the pull request;
{@code RANGE} to stream comments related to a commit range between two arbitrary commits
(requires {@code fromHash} and {@code toHash});
{@code COMMIT} to stream comments related to a commit between two arbitrary commits (requires
{@code fromHash} and {@code toHash})
in: query
name: diffType
required: false
type: string
- description: "the from commit hash to stream comments for a {@code RANGE} or {@code COMMIT} arbitrary change scope"
in: query
name: fromHash
required: false
type: string
- description: the path to stream comments for a given path
in: query
name: path
required: false
type: string
- description: "the to commit hash to stream comments for a {@code RANGE} or {@code COMMIT} arbitrary change scope"
in: query
name: toHash
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Gets comments for the specified PullRequest.
<p>
The authenticated user must have <strong>REPO_READ</strong> permission for the repository that this pull request
targets to call this resource.
operationId: getCommentsCommit
post:
parameters: []
responses:
"200":
description: Successful Response
description: |-
Add a new comment.
<p>
Comments can be added in a few places by setting different attributes:
<p>
General pull request comment:
<pre>
{
"text": "An insightful general comment on a pull request."
}
</pre>
Reply to a comment:
<pre>
{
"text": "A measured reply.",
"parent": {
"id": 1
}
}
</pre>
General file comment:
<pre>
{
"text": "An insightful general comment on a file.",
"anchor": {
"diffType": "RANGE",
"fromHash": "6df3858eeb9a53a911cd17e66a9174d44ffb02cd",
"path": "path/to/file",
"srcPath": "path/to/file",
"toHash": "04c7c5c931b9418ca7b66f51fe934d0bd9b2ba4b"
}
}
</pre>
File line comment:
<pre>
{
"text": "A pithy comment on a particular line within a file.",
"anchor": {
"diffType": "COMMIT",
"line": 1,
"lineType": "CONTEXT",
"fileType": "FROM",
"fromHash": "6df3858eeb9a53a911cd17e66a9174d44ffb02cd",
"path": "path/to/file",
"srcPath": "path/to/file",
"toHash": "04c7c5c931b9418ca7b66f51fe934d0bd9b2ba4b"
}
}
</pre>
<p>
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.
<p>
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:
<ul>
<li>'ADDED' - for an added line;</li>
<li>'REMOVED' - for a removed line; or</li>
<li>'CONTEXT' - for a line that was unmodified but is in the vicinity of the diff.</li>
</ul>
'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:
<ul>
<li>'FROM' - the source file of the diff</li>
<li>'TO' - the destination file of the diff</li>
</ul>
If the current user is not a participant the user is added as a watcher of the pull request.
<p>
The authenticated user must have <strong>REPO_READ</strong> permission for the repository that this pull request
targets to call this resource.
operationId: createCommentCommit
? "/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/comments/{commentId}"
: parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
- description: the id of the pullRequest to retrieve
format: int64
in: path
name: pullRequestId
required: true
type: integer
- description: the id of the comment to retrieve
format: int64
in: path
name: commentId
required: true
type: integer
delete:
parameters:
- default: -1
description: |-
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.
format: int32
in: query
name: version
required: false
type: integer
responses:
"200":
description: Successful Response
description: |-
Delete a pull request comment. Anyone can delete their own comment. Only users with <strong>REPO_ADMIN</strong>
and above may delete comments created by other users.
<p>
The authenticated user must have <strong>REPO_READ</strong> permission for the repository that this pull request
targets to call this resource.
operationId: deleteCommentCommit
get:
responses:
"200":
description: Successful Response
description: |-
Retrieves a pull request comment.
<p>
The authenticated user must have <strong>REPO_READ</strong> permission for the repository that this pull request
targets to call this resource.
operationId: getCommentCommit
put:
parameters: []
responses:
"200":
description: Successful Response
description: |-
Update the text of a comment. Only the user who created a comment may update it.
<p>
<strong>Note:</strong> the supplied supplied JSON object must contain a <code>version</code> 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.
<p>
The authenticated user must have <strong>REPO_READ</strong> permission for the repository that this pull request
targets to call this resource.
operationId: updateCommentCommit
? "/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/commits"
: parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
- format: int64
in: path
name: pullRequestId
required: true
type: integer
get:
parameters:
- description: |-
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.
in: query
name: withCounts
required: false
type: boolean
responses:
"200":
description: Successful Response
description: |-
Retrieve commits for the specified pull request.
<p>
The authenticated user must have <strong>REPO_READ</strong> permission for the repository that this pull request
targets to call this resource.
operationId: getCommitsPR
? "/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/decline"
: parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
- format: int64
in: path
name: pullRequestId
required: true
type: integer
post:
parameters:
- default: -1
description: |-
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.
format: int32
in: query
name: version
required: false
type: integer
responses:
"200":
description: Successful Response
description: |-
Decline a pull request.
<p>
The authenticated user must have <strong>REPO_READ</strong> permission for the repository that this pull request
targets to call this resource.
operationId: decline
? "/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/diff"
: parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
- format: int64
in: path
name: pullRequestId
required: true
type: integer
get:
parameters:
- default: -1
description: the number of context lines to include around added/removed lines in the diff
format: int32
in: query
name: contextLines
required: false
type: integer
- default: EFFECTIVE
description: |-
the type of diff being requested. When {@code withComments} is {@code true}
this works as a hint to the system to attach the correct set of comments to the diff
in: query
name: diffType
required: false
type: string
- description: the since commit hash to stream a diff between two arbitrary hashes
in: query
name: sinceId
required: false
type: string
- description: "the previous path to the file, if the file has been copied, moved or renamed"
in: query
name: srcPath
required: false
type: string
- description: the until commit hash to stream a diff between two arbitrary hashes
in: query
name: untilId
required: false
type: string
- description: optional whitespace flag which can be set to <code>ignore-all</code>
in: query
name: whitespace
required: false
type: string
- default: true
description: |-
<code>true</code> to embed comments in the diff (the default); otherwise, <code>false</code>
to stream the diff without comments
in: query
name: withComments
required: false
type: boolean
responses:
"200":
description: Successful Response
description: |-
Streams a diff within a pull request.
<p>
If the specified file has been copied, moved or renamed, the <code>srcPath</code> must also be specified to
produce the correct diff.
<p>
Note: This RESTful endpoint is currently <i>not paged</i>. 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.
<p>
The authenticated user must have <strong>REPO_READ</strong> permission for the repository that this pull request
targets to call this resource.
operationId: streamDiffPR
? "/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/diff/{path}"
: parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
- format: int64
in: path
name: pullRequestId
required: true
type: integer
- description: the path to the file which should be diffed (optional)
in: path
name: path
required: true
type: string
get:
parameters:
- default: -1
description: the number of context lines to include around added/removed lines in the diff
format: int32
in: query
name: contextLines
required: false
type: integer
- default: EFFECTIVE
description: |-
the type of diff being requested. When {@code withComments} is {@code true}
this works as a hint to the system to attach the correct set of comments to the diff
in: query
name: diffType
required: false
type: string
- description: the since commit hash to stream a diff between two arbitrary hashes
in: query
name: sinceId
required: false
type: string
- description: "the previous path to the file, if the file has been copied, moved or renamed"
in: query
name: srcPath
required: false
type: string
- description: the until commit hash to stream a diff between two arbitrary hashes
in: query
name: untilId
required: false
type: string
- description: optional whitespace flag which can be set to <code>ignore-all</code>
in: query
name: whitespace
required: false
type: string
- default: true
description: |-
<code>true</code> to embed comments in the diff (the default); otherwise, <code>false</code>
to stream the diff without comments
in: query
name: withComments
required: false
type: boolean
responses:
"200":
description: Successful Response
description: |-
Streams a diff within a pull request.
<p>
If the specified file has been copied, moved or renamed, the <code>srcPath</code> must also be specified to
produce the correct diff.
<p>
Note: This RESTful endpoint is currently <i>not paged</i>. 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.
<p>
The authenticated user must have <strong>REPO_READ</strong> permission for the repository that this pull request
targets to call this resource.
operationId: streamDiff
? "/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/merge"
: parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
- description: the ID of the pull request within the repository
format: int64
in: path
name: pullRequestId
required: true
type: integer
get:
responses:
"200":
description: Successful Response
description: |-
Test whether a pull request can be merged.
<p>
A pull request may not be merged if:
<ul>
<li>there are conflicts that need to be manually resolved before merging; and/or</li>
<li>one or more merge checks have vetoed the merge.</li>
</ul>
<p>
The authenticated user must have <strong>REPO_READ</strong> permission for the repository that this pull request
targets to call this resource.
operationId: canMerge
post:
parameters:
- default: -1
description: |-
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.
format: int32
in: query
name: version
required: false
type: integer
responses:
"200":
description: Successful Response
description: |-
Merge the specified pull request.
<p>
The authenticated user must have <strong>REPO_WRITE</strong> permission for the repository that this pull request
targets to call this resource.
operationId: merge
? "/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/participants"
: parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
- description: the id of the pull request within the repository
format: int64
in: path
name: pullRequestId
required: true
type: integer
delete:
parameters:
- description: the participant's user name
in: query
name: username
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Unassigns a participant from the REVIEWER role they may have been given in a pull request.
<p>
If the participant has no explicit role this method has no effect.
<p>
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.
<p>
The authenticated user must have <strong>REPO_WRITE</strong> permission for the repository that this pull request
targets to call this resource.
<p>
<strong>Deprecated since 4.2</strong>. Use
/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/participants/{userSlug}
instead.
operationId: unassignParticipantRolePR
get:
responses:
"200":
description: Successful Response
description: |-
Retrieves a page of the participants for a given pull request.
<p>
The authenticated user must have <strong>REPO_READ</strong> permission for the repository that this pull request
targets to call this resource.
operationId: listParticipants
post:
parameters: []
responses:
"200":
description: Successful Response
description: |-
Assigns a participant to an explicit role in pull request. Currently only the REVIEWER role may be assigned.
<p>
If the user is not yet a participant in the pull request, they are made one and assigned the supplied role.
<p>
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.
<p>
The authenticated user must have <strong>REPO_WRITE</strong> permission for the repository that this pull request
targets to call this resource.
operationId: assignParticipantRole
? "/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/participants/{userSlug}"
: parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
- description: the id of the pull request within the repository
format: int64
in: path
name: pullRequestId
required: true
type: integer
- description: the slug for the user changing their status
in: path
name: userSlug
required: true
type: string
delete:
responses:
"200":
description: Successful Response
description: |-
Unassigns a participant from the REVIEWER role they may have been given in a pull request.
<p>
If the participant has no explicit role this method has no effect.
<p>
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.
<p>
The authenticated user must have <strong>REPO_WRITE</strong> permission for the repository that this pull request
targets to call this resource.
<p>
<strong>Deprecated since 4.2</strong>. Use
/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/participants/{userSlug}
instead.
operationId: unassignParticipantRole
put:
responses:
"200":
description: Successful Response
description: |-
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.
<p>
The possible values for {@code status} are <strong>UNAPPROVED</strong>, <strong>NEEDS_WORK</strong>, or
<strong>APPROVED</strong>.
<p>
If the new {@code status} is <strong>NEEDS_WORK</strong> or <strong>APPROVED</strong> then the
{@code lastReviewedCommit} for the participant will be updated to the latest commit of the source branch of the
pull request.
<p>
The authenticated user must have <strong>REPO_READ</strong> permission for the repository that this pull request
targets to call this resource.
operationId: updateStatus
? "/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/reopen"
: parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
- description: the id of the pull request within the repository
format: int64
in: path
name: pullRequestId
required: true
type: integer
post:
parameters:
- default: -1
description: |-
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.
format: int32
in: query
name: version
required: false
type: integer
responses:
"200":
description: Successful Response
description: |-
Re-open a declined pull request.
<p>
The authenticated user must have <strong>REPO_READ</strong> permission for the repository that this pull request
targets to call this resource.
operationId: reopen
? "/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/tasks"
: parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
- description: the id of the pull request within the repository
format: int64
in: path
name: pullRequestId
required: true
type: integer
get:
responses:
"200":
description: Successful Response
description: Retrieve the tasks associated with a pull request.
operationId: getPullRequestTasks
? "/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/tasks/count"
: parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
- description: the id of the pull request within the repository
format: int64
in: path
name: pullRequestId
required: true
type: integer
get:
responses:
"200":
description: Successful Response
description: |-
Retrieve the total number of {@link TaskState#OPEN open} and
{@link TaskState#RESOLVED resolved} tasks associated with a pull request.
operationId: countPullRequestTasks
? "/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/watch"
: parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
- description: the id of the pull request within the repository
format: int64
in: path
name: pullRequestId
required: true
type: integer
delete:
responses:
"200":
description: Successful Response
description: |-
Make the authenticated user stop watching the specified pull request.
<p>
The authenticated user must have <strong>REPO_READ</strong> permission for the repository that this pull request
targets to call this resource.
operationId: unwatchPR
post:
responses:
"200":
description: Successful Response
description: |-
Make the authenticated user watch the specified pull request.
<p>
The authenticated user must have <strong>REPO_READ</strong> permission for the repository that this pull request
targets to call this resource.
operationId: watchPR
"/api/1.0/projects/{projectKey}/repos/{repositorySlug}/raw":
parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
get:
parameters:
- description: the commit ID or ref to retrieve the content for.
in: query
name: at
required: false
type: string
- description: |-
if present or <code>"true"</code>, triggers the raw content to be markup-rendered and returned
as HTML; otherwise, if not specified, or any value other than <code>"true"</code>, the content
is streamed without markup
in: query
name: markup
required: false
type: string
- description: |-
(Optional) Whether the markup implementation should convert newlines to breaks.
If not specified, {@link MarkupService} will use the value of the
<code>markup.render.hardwrap</code> property, which is <code>true</code> by default
in: query
name: hardwrap
required: false
type: boolean
- description: |-
(Optional) true if HTML should be escaped in the input markup, false otherwise.
If not specified, {@link MarkupService} will use the value of the
<code>markup.render.html.escape</code> property, which is <code>true</code> by default
in: query
name: htmlEscape
required: false
type: boolean
responses:
"200":
description: Successful Response
description: |-
Retrieve the raw content for a file path at a specified revision.
<p>
The authenticated user must have <strong>REPO_READ</strong> permission for the specified repository to call this
resource.
operationId: getContentRepository
"/api/1.0/projects/{projectKey}/repos/{repositorySlug}/raw/{path}":
parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
- description: the file path to retrieve content from
in: path
name: path
required: true
type: string
get:
parameters:
- description: the commit ID or ref to retrieve the content for.
in: query
name: at
required: false
type: string
- description: |-
if present or <code>"true"</code>, triggers the raw content to be markup-rendered and returned
as HTML; otherwise, if not specified, or any value other than <code>"true"</code>, the content
is streamed without markup
in: query
name: markup
required: false
type: string
- description: |-
(Optional) Whether the markup implementation should convert newlines to breaks.
If not specified, {@link MarkupService} will use the value of the
<code>markup.render.hardwrap</code> property, which is <code>true</code> by default
in: query
name: hardwrap
required: false
type: boolean
- description: |-
(Optional) true if HTML should be escaped in the input markup, false otherwise.
If not specified, {@link MarkupService} will use the value of the
<code>markup.render.html.escape</code> property, which is <code>true</code> by default
in: query
name: htmlEscape
required: false
type: boolean
responses:
"200":
description: Successful Response
description: |-
Retrieve the raw content for a file path at a specified revision.
<p>
The authenticated user must have <strong>REPO_READ</strong> permission for the specified repository to call this
resource.
operationId: getContentRepositoryPath
"/api/1.0/projects/{projectKey}/repos/{repositorySlug}/recreate":
parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
post:
responses:
"200":
description: Successful Response
description: |-
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.
<p>
The authenticated user must have <strong>PROJECT_ADMIN</strong> permission for the specified project to call this
resource.
operationId: retryCreateRepository
"/api/1.0/projects/{projectKey}/repos/{repositorySlug}/related":
parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
get:
responses:
"200":
description: Successful Response
description: |-
Retrieve repositories which are related to this one. Related repositories are from the same
{@link Repository#getHierarchyId() hierarchy} as this repository.
<p>
Only repositories to which the authenticated user has <b>REPO_READ</b> permission will be included, even
if more repositories are part of this repository's hierarchy.
operationId: getRelatedRepositories
"/api/1.0/projects/{projectKey}/repos/{repositorySlug}/settings/hooks":
parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
get:
parameters:
- default: ""
description: the optional type to filter by. Valid values are <code>PRE_RECEIVE</code> or <code>POST_RECEIVE</code>
in: query
name: type
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Retrieve a page of repository hooks for this repository.
<p>
The authenticated user must have <strong>REPO_READ</strong> permission for the specified repository to call this
resource.
operationId: getRepositoryHooksSettings
? "/api/1.0/projects/{projectKey}/repos/{repositorySlug}/settings/hooks/{hookKey}"
: parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
- in: path
name: hookKey
required: true
type: string
delete:
responses:
"200":
description: Successful Response
description: |-
Delete repository hook configuration for the supplied <strong>hookKey</strong> and <strong>repositorySlug</strong>
<p>
The authenticated user must have <strong>REPO_ADMIN</strong> permission for the specified repository to call this
resource.
operationId: deleteRepositoryHook
get:
responses:
"200":
description: Successful Response
description: |-
Retrieve a repository hook for this repository.
<p>
The authenticated user must have <strong>REPO_READ</strong> permission for the specified repository to call this
resource.
operationId: getRepositoryHookSettings
? "/api/1.0/projects/{projectKey}/repos/{repositorySlug}/settings/hooks/{hookKey}/enabled"
: parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
- in: path
name: hookKey
required: true
type: string
delete:
responses:
"200":
description: Successful Response
description: |-
Disable a repository hook for this repository.
<p>
The authenticated user must have <strong>REPO_ADMIN</strong> permission for the specified repository to call this
resource.
operationId: disableHookRepo
put:
parameters:
- default: 0
format: int32
in: header
name: Content-Length
required: false
type: integer
responses:
"200":
description: Successful Response
description: |-
Enable a repository hook for this repository and optionally apply new configuration.
<p>
The authenticated user must have <strong>REPO_ADMIN</strong> permission for the specified repository to call this
resource.
<p>
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.
operationId: enableHookRepo
? "/api/1.0/projects/{projectKey}/repos/{repositorySlug}/settings/hooks/{hookKey}/settings"
: parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
- in: path
name: hookKey
required: true
type: string
get:
responses:
"200":
description: Successful Response
description: |-
Retrieve the settings for a repository hook for this repository.
<p>
The authenticated user must have <strong>REPO_READ</strong> permission for the specified repository to call this
resource.
operationId: getSettingsHook
put:
parameters: []
responses:
"200":
description: Successful Response
description: |-
Modify the settings for a repository hook for this repository.
<p>
The service will reject any settings which are too large, the current limit is 32KB once serialized.
<p>
The authenticated user must have <strong>REPO_ADMIN</strong> permission for the specified repository to call this
resource.
<p>
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.
operationId: setSettings
? "/api/1.0/projects/{projectKey}/repos/{repositorySlug}/settings/pull-requests"
: parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
get:
responses:
"200":
description: Successful Response
description: |-
Retrieve the pull request settings for the context repository.
<p>
The authenticated user must have <strong>REPO_READ</strong> permission for the context repository to call this
resource.
<p>
This resource will call all RestFragments that are registered with the key
<strong>bitbucket.repository.settings.pullRequests</strong>. If any fragment fails validations by returning a
non-empty Map of errors, then no fragments will execute.
<p>
The property keys for the settings that are bundled with the application are
<ul>
<li>mergeConfig - the merge strategy configuration for pull requests</li>
<li>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</li>
<li>com.atlassian.bitbucket.server.bundled-hooks.requiredApproversMergeHook - the merge check configuration for required approvers</li>
<li>requiredAllApprovers - whether or not all approvers must approve a pull request for it to be mergeable</li>
<li>requiredAllTasksComplete - whether or not all tasks on a pull request need to be completed for it to be mergeable</li>
<li>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</li>
<li>com.atlassian.bitbucket.server.bitbucket-build.requiredBuildsMergeCheck - the merge check configuration for required builds</li>
</ul>
operationId: getPullRequestSettings
post:
parameters: []
responses:
"200":
description: Successful Response
description: |-
Update the pull request settings for the context repository.
<p>
The authenticated user must have <strong>REPO_ADMIN</strong> permission for the context repository to call this
resource.
<p>
This resource will call all RestFragments that are registered with the key
<strong>bitbucket.repository.settings.pullRequests</strong>. If any fragment fails validations by returning a
non-empty Map of errors, then no fragments will execute.
<p>
Only the settings that should be updated need to be included in the request.
<p>
The property keys for the settings that are bundled with the application are
<ul>
<li>mergeConfig - the merge strategy configuration for pull requests</li>
<li>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</li>
<li>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)</li>
<li>requiredAllApprovers - whether or not all approvers must approve a pull request for it to be mergeable</li>
<li>requiredAllTasksComplete - whether or not all tasks on a pull request need to be completed for it to be mergeable</li>
<li>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</li>
<li>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)</li>
</ul>
<strong>Merge strategy configuration deletion:</strong>
<p>
An explicitly set pull request merge strategy configuration can be deleted by POSTing a document with an empty
"mergeConfig" attribute. i.e:
<pre>
{
"mergeConfig": {
}
}
</pre>
Upon completion of this request, the effective configuration will be:
<ul>
<li>The configuration set for this repository's SCM type as set at the project level, if present, otherwise</li>
<li>the configuration set for this repository's SCM type as set at the instance level, if present, otherwise</li>
<li>the default configuration for this repository's SCM type</li>
<ul>
operationId: updatePullRequestSettings
"/api/1.0/projects/{projectKey}/repos/{repositorySlug}/tags":
parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
get:
parameters:
- description: the text to match on
in: query
name: filterText
required: false
type: string
- description: ordering of refs either ALPHABETICAL (by name) or MODIFICATION (last updated)
in: query
name: orderBy
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Retrieve the tags matching the supplied <strong>filterText</strong> param.
<p>
The authenticated user must have <strong>REPO_READ</strong> permission for the context repository to call this
resource.
operationId: getTags
post:
parameters: []
responses:
"200":
description: Successful Response
description: |-
Creates a tag using the information provided in the {@link RestCreateTagRequest request}
<p>
The authenticated user must have <strong>REPO_WRITE</strong> permission for the context repository to call this
resource.
operationId: createTag
"/api/1.0/projects/{projectKey}/repos/{repositorySlug}/tags/{name}":
parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
- description: the name of the tag to be retrieved
in: path
name: name
required: true
type: string
get:
responses:
"200":
description: Successful Response
description: |-
Retrieve a tag in the specified repository.
<p>
The authenticated user must have <strong>REPO_READ</strong> permission for the context repository to call this
resource.
operationId: getTag
"/api/1.0/projects/{projectKey}/repos/{repositorySlug}/webhooks":
parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
get:
parameters:
- description: "list of {@link com.atlassian.webhooks.WebhookEvent} ids to filter for"
in: query
name: event
required: false
type: string
- default: false
description: "{@code true} if statistics should be provided for all found webhooks"
in: query
name: statistics
required: false
type: boolean
responses:
"200":
description: Successful Response
description: |-
Find webhooks in this repository.
<p>
The authenticated user must have <strong>REPO_ADMIN</strong> permission for the specified repository to call this
resource.
operationId: findWebhooks
post:
parameters: []
responses:
"200":
description: Successful Response
description: |-
Create a webhook for the repository specified via the URL.
<p>
The authenticated user must have <strong>REPO_ADMIN</strong> permission for the specified repository to call this
resource.
operationId: createWebhook
"/api/1.0/projects/{projectKey}/repos/{repositorySlug}/webhooks/test":
parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
post:
parameters:
- description: the url in which to connect to
in: query
name: url
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Test connectivity to a specific endpoint.
<p>
The authenticated user must have <strong>REPO_ADMIN</strong> permission for the specified repository to call this
resource.
operationId: testWebhook
"/api/1.0/projects/{projectKey}/repos/{repositorySlug}/webhooks/{webhookId}":
parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
- description: the existing webhook id
format: int32
in: path
name: webhookId
required: true
type: integer
delete:
responses:
"200":
description: Successful Response
description: |-
Delete a webhook for the repository specified via the URL.
<p>
The authenticated user must have <strong>REPO_ADMIN</strong> permission for the specified repository to call this
resource.
operationId: deleteWebhook
get:
parameters:
- default: false
in: query
name: statistics
required: false
type: boolean
responses:
"200":
description: Successful Response
description: |-
Get a webhook by id.
<p>
The authenticated user must have <strong>REPO_ADMIN</strong> permission for the specified repository to call this
resource.
operationId: getWebhook
put:
parameters: []
responses:
"200":
description: Successful Response
description: |-
Update an existing webhook.
<p>
The authenticated user must have <strong>REPO_ADMIN</strong> permission for the specified repository to call this
resource.
operationId: updateWebhook
? "/api/1.0/projects/{projectKey}/repos/{repositorySlug}/webhooks/{webhookId}/latest"
: parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
- description: id of the webhook
format: int32
in: path
name: webhookId
required: true
type: integer
get:
parameters:
- description: the string id of a specific event to retrieve the last invocation for.
in: query
name: event
required: false
type: string
- description: |-
the outcome to filter for. Can be SUCCESS, FAILURE, ERROR. None specified means that the all
will be considered
in: query
name: outcome
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Get the latest invocations for a specific webhook.
<p>
The authenticated user must have <strong>REPO_ADMIN</strong> permission for the specified repository to call this
resource.
operationId: getLatestInvocation
? "/api/1.0/projects/{projectKey}/repos/{repositorySlug}/webhooks/{webhookId}/statistics"
: parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
- description: id of the webhook
format: int32
in: path
name: webhookId
required: true
type: integer
get:
parameters:
- description: |-
the string id of a specific event to retrieve the last invocation for. May be empty, in which
case all events are considered
in: query
name: event
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Get the statistics for a specific webhook.
<p>
The authenticated user must have <strong>REPO_ADMIN</strong> permission for the specified repository to call this
resource.
operationId: getStatistics
? "/api/1.0/projects/{projectKey}/repos/{repositorySlug}/webhooks/{webhookId}/statistics/summary"
: parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the repository slug
in: path
name: repositorySlug
required: true
type: string
- description: id of the webhook
format: int32
in: path
name: webhookId
required: true
type: integer
get:
responses:
"200":
description: Successful Response
description: |-
Get the statistics summary for a specific webhook.
<p>
The authenticated user must have <strong>REPO_ADMIN</strong> permission for the specified repository to call this
resource.
operationId: getStatisticsSummary
"/api/1.0/projects/{projectKey}/settings/hooks":
parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
get:
parameters:
- default: ""
description: the optional type to filter by. Valid values are <code>PRE_RECEIVE</code> or <code>POST_RECEIVE</code>
in: query
name: type
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Retrieve a page of repository hooks for this project.
<p>
The authenticated user must have <strong>PROJECT_READ</strong> permission for the specified project to call this
resource.
operationId: getRepositoryHooks
"/api/1.0/projects/{projectKey}/settings/hooks/{hookKey}":
parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- in: path
name: hookKey
required: true
type: string
get:
responses:
"200":
description: Successful Response
description: |-
Retrieve a repository hook for this project.
<p>
The authenticated user must have <strong>PROJECT_READ</strong> permission for the specified project to call this
resource.
operationId: getRepositoryHook
"/api/1.0/projects/{projectKey}/settings/hooks/{hookKey}/enabled":
parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- in: path
name: hookKey
required: true
type: string
delete:
responses:
"200":
description: Successful Response
description: |-
Disable a repository hook for this project.
<p>
The authenticated user must have <strong>PROJECT_ADMIN</strong> permission for the specified project to call this
resource.
operationId: disableHook
put:
parameters:
- default: 0
format: int32
in: header
name: Content-Length
required: false
type: integer
responses:
"200":
description: Successful Response
description: |-
Enable a repository hook for this project and optionally apply new configuration.
<p>
The authenticated user must have <strong>PROJECT_ADMIN</strong> permission for the specified project to call this
resource.
<p>
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.
operationId: enableHook
"/api/1.0/projects/{projectKey}/settings/hooks/{hookKey}/settings":
parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- in: path
name: hookKey
required: true
type: string
get:
responses:
"200":
description: Successful Response
description: |-
Retrieve the settings for a repository hook for this project.
<p>
The authenticated user must have <strong>PROJECT_READ</strong> permission for the specified project to call this
resource.
operationId: getSettings
put:
parameters: []
responses:
"200":
description: Successful Response
description: |-
Modify the settings for a repository hook for this project.
<p>
The service will reject any settings which are too large, the current limit is 32KB once serialized.
<p>
The authenticated user must have <strong>PROJECT_ADMIN</strong> permission for the specified project to call this
resource.
<p>
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.
operationId: setSettingsProject
"/api/1.0/projects/{projectKey}/settings/pull-requests/{scmId}":
parameters:
- description: the parent project key
in: path
name: projectKey
required: true
type: string
- description: the SCM to get strategies for
in: path
name: scmId
required: true
type: string
get:
responses:
"200":
description: Successful Response
description: |-
Retrieve the merge strategy configuration for this project and SCM.
<p>
The authenticated user must have <strong>PROJECT_READ</strong> permission for the context repository to call this
resource.
operationId: getPullRequestSettingsSCM
post:
parameters: []
responses:
"200":
description: Successful Response
description: |-
Update the pull request merge strategy configuration for this project and SCM.
<p>
The authenticated user must have <strong>PROJECT_ADMIN</strong> permission for the context repository to call this
resource.
<p>
Only the strategies provided will be enabled, the default must be set and included in the set of strategies.
<p>
An explicitly set pull request merge strategy configuration can be deleted by POSTing a document with
an empty "mergeConfig" attribute. i.e:
<pre>
{
"mergeConfig": {
}
}
</pre>
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.
operationId: updatePullRequestSettingsSCM
/api/1.0/repos:
parameters: []
get:
parameters:
- description: |-
(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 <code>name</code> parameter will be stripped.
in: query
name: name
required: false
type: string
- description: |-
(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 <code>projectname</code> parameter will
be stripped.
in: query
name: projectname
required: false
type: string
- description: |-
(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 <tt>REPO_READ</tt>, <tt>REPO_WRITE</tt>
and <tt>REPO_ADMIN</tt>.
in: query
name: permission
required: false
type: string
- description: |-
(optional) if specified, this will limit the resulting repository list based on the
repositories visibility. Valid values are <em>public</em> or <em>private</em>.
in: query
name: visibility
required: false
type: string
responses:
"200":
description: Successful Response
description: |-
Retrieve a page of repositories based on query parameters that control the search. See the documentation of the
parameters for more details.
<p>
This resource is anonymously accessible.
<p>
<b>Note on permissions.</b> In absence of the {@code 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 <tt>REPO_READ</tt>, 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
<tt>REPO_READ</tt> is guaranteed to receive an empty list of repositories as a result. For anonymous requests
it is therefore recommended to not specify the <tt>permission</tt> parameter at all.
operationId: getRepositoriesAll
/api/1.0/tasks:
parameters: []
post:
parameters: []
responses:
"200":
description: Successful Response
description: Create a new task.
operationId: createTask
"/api/1.0/tasks/{taskId}":
parameters:
- description: the id identifying the task to delete
format: int64
in: path
name: taskId
required: true
type: integer
delete:
responses:
"200":
description: Successful Response
description: |-
Delete a task.
<p>
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.
operationId: deleteTask
get:
responses:
"200":
description: Successful Response
description: Retrieve a existing task.
operationId: getTask
put:
parameters: []
responses:
"200":
description: Successful Response
description: |-
Update a existing task.
<p>
As of Stash 3.3, only the state and text of a task can be updated.
<p>
Updating the state of a task is allowed for any user having <em>READ</em> 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.
operationId: updateTask
/api/1.0/users:
parameters: []
get:
responses:
"200":
description: Successful Response
description: |-
Retrieve a page of users, optionally run through provided filters.
<p>
Only authenticated users may call this resource.
<h3>Supported Filters</h3>
<p>
Filters are provided in query parameters in a standard <code>name=value</code> fashion. The following filters are
currently supported:
<ul>
<li>
{@code filter} - return only users, whose username, name or email address <i>contain</i> the
{@code filter} value
</li>
<li>
{@code group} - return only users who are members of the given group
</li>
<li>
{@code 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 <code>permission.</code>. See the
section "Permission Filters" below for more details.
</li>
<li>
{@code permission.N} - the "root" of a single permission filter, similar to the {@code permission}
parameter, where "N" is a natural number starting from 1. This allows clients to specify multiple permission
filters, by providing consecutive filters as {@code permission.1}, {@code 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.
</li>
</ul>
<h3>Permission Filters</h3>
<p>
The following three sub-sections list parameters supported for permission filters (where <code>[root]</code> is
the root permission filter name, e.g. {@code permission}, {@code permission.1} etc.) depending on the
permission resource. The system determines which filter to apply (Global, Project or Repository permission)
based on the <code>[root]</code> permission value. E.g. {@code ADMIN} is a global permission,
{@code PROJECT_ADMIN} is a project permission and {@code 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 {@code projectId} and {@code projectKey} are provided, the system will
use {@code projectId} for the lookup.
<h4>Global permissions</h4>
<p>
The permission value under <code>[root]</code> is the only required and recognized parameter, as global
permissions do not apply to a specific resource.
<p>
Example valid filter: <code>permission=ADMIN</code>.
<h4>Project permissions</h4>
<ul>
<li><code>[root]</code>- specifies the project permission</li>
<li><code>[root].projectId</code> - specifies the project ID to lookup the project by</li>
<li><code>[root].projectKey</code> - specifies the project key to lookup the project by</li>
</ul>
<p>
Example valid filter: <code>permission.1=PROJECT_ADMIN&permission.1.projectKey=TEST_PROJECT</code>.
<h4>Repository permissions</h4>
<ul>
<li><code>[root]</code>- specifies the repository permission</li>
<li><code>[root].projectId</code> - specifies the repository ID to lookup the repository by</li>
<li><code>[root].projectKey</code> and <code>[root].repositorySlug</code>- specifies the project key and
repository slug to lookup the repository by; both values <i>need to</i> be provided for this look up to be
triggered</li>
</ul>
Example valid filter: <code>permission.2=REPO_ADMIN&permission.2.projectKey=TEST_PROJECT&permission.2.repositorySlug=test_repo</code>.
operationId: getUsersAll
put:
parameters: []
responses:
"200":
description: Successful Response
description: |-
Update the currently authenticated user's details. The update will always be applied to the currently
authenticated user.
operationId: updateUserDetailsAll
/api/1.0/users/credentials:
parameters: []
put:
parameters: []
responses:
"200":
description: Successful Response
description: Update the currently authenticated user's password.
operationId: updateUserPasswordAll
"/api/1.0/users/{userSlug}":
parameters:
- description: the user slug
in: path
name: userSlug
required: true
type: string
get:
responses:
"200":
description: Successful Response
description: |-
Retrieve the user matching the supplied <strong>userSlug</strong>.
<p>
operationId: getUser
"/api/1.0/users/{userSlug}/avatar.png":
parameters:
- description: the user slug
in: path
name: userSlug
required: true
type: string
delete:
responses:
"200":
description: Successful Response
description: |-
Delete the avatar associated to a user.
<p>
Users are always allowed to delete their own avatar. To delete someone else's avatar the authenticated user must
have global <strong>ADMIN</strong> permission, or global <strong>SYS_ADMIN</strong> permission to update a
<strong>SYS_ADMIN</strong> user's avatar.
operationId: deleteAvatar
post:
responses:
"200":
description: Successful Response
description: |-
Update the avatar for the user with the supplied <strong>slug</strong>.
<p>
This resource accepts POST multipart form data, containing a single image in a form-field named 'avatar'.
<p>
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 <strong>PNG</strong> and
<strong>JPEG</strong> are preferred due to the file size limit.
<p>
This resource has Cross-Site Request Forgery (XSRF) protection. To allow the request to
pass the XSRF check the caller needs to send an <code>X-Atlassian-Token</code> HTTP header with the
value <code>no-check</code>.
<p>
An example <a href="http://curl.haxx.se/">curl</a> request to upload an image name 'avatar.png' would be:
<pre>
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
</pre>
<p>
Users are always allowed to update their own avatar. To update someone else's avatar the authenticated user must
have global <strong>ADMIN</strong> permission, or global <strong>SYS_ADMIN</strong> permission to update a
<strong>SYS_ADMIN</strong> user's avatar.
operationId: uploadAvatar
"/api/1.0/users/{userSlug}/settings":
parameters:
- description: the user slug
in: path
name: userSlug
required: true
type: string
get:
responses:
"200":
description: Successful Response
description: |-
Retrieve a map of user setting key values for a specific user identified by the user slug.
<p>
operationId: getUserSettings
post:
parameters: []
responses:
"200":
description: Successful Response
description: |-
Update the entries of a map of user setting key/values for a specific user identified by the user slug.
<p>
operationId: updateSettings
Reference in New Issue View Git Blame Copy Permalink