page.max.changes
) and it is not
possible to request subsequent content when that cap is exceeded.
The authenticated user must have REPO_READ permission for the specified repository to call this resource.]]>
The authenticated user must have REPO_READ permission for the context repository to call this resource.]]>
This resource will call all RestFragments that are registered with the key bitbucket.repository.settings.pullRequests. If any fragment fails validations by returning a non-empty Map of errors, then no fragments will execute.
Only the settings that should be updated need to be included in the request.
The property keys for the settings that are bundled with the application are
An explicitly set pull request merge strategy configuration can be deleted by POSTing a document with an empty "mergeConfig" attribute. i.e:
{ "mergeConfig": { } }Upon completion of this request, the effective configuration will be:
This resource will call all RestFragments that are registered with the key bitbucket.repository.settings.pullRequests. If any fragment fails validations by returning a non-empty Map of errors, then no fragments will execute.
The property keys for the settings that are bundled with the application are
avatar
and the value a data URI containing Base64-encoded image data. The URI should be in
the following format:
data:(content type, e.g. image/png);base64,(data)If the data is not Base64-encoded, or if a character set is defined in the URI, or the URI is otherwise invalid, project creation will fail.
The authenticated user must have PROJECT_CREATE permission to call this resource.]]>
The authenticated user must have PROJECT_ADMIN permission for the specified project to call this resource.]]>
To include a custom avatar for the updated project, the project definition should contain an additional attribute
with the key avatar
and the value a data URI containing Base64-encoded image data. The URI should be
in the following format:
data:(content type, e.g. image/png);base64,(data)
If the data is not Base64-encoded, or if a character set is defined in the URI, or the URI is otherwise invalid,
project creation will fail.
The authenticated user must have PROJECT_ADMIN permission for the specified project to call this resource.]]>
The authenticated user must have PROJECT_VIEW permission for the specified project to call this resource.]]>
The authenticated user must have PROJECT_VIEW permission for the specified project to call this resource.]]>
This resource accepts POST multipart form data, containing a single image in a form-field named 'avatar'.
There are configurable server limits on both the dimensions (1024x1024 pixels by default) and uploaded file size (1MB by default). Several different image formats are supported, but PNG and JPEG are preferred due to the file size limit.
This resource has Cross-Site Request Forgery (XSRF) protection. To allow the request to
pass the XSRF check the caller needs to send an X-Atlassian-Token
HTTP header with the
value no-check
.
An example curl request to upload an image name 'avatar.png' would be:
curl -X POST -u username:password -H "X-Atlassian-Token: no-check" http://example.com/rest/api/1.0/projects/STASH/avatar.png -F avatar=@avatar.png
The authenticated user must have PROJECT_ADMIN permission for the specified project to call this resource.]]>
Note on permissions. In absence of the permission
query parameter the implicit 'read' permission
is assumed. Please note that this permission is lower than the REPO_READ permission rather than being equal to
it. The implicit 'read' permission for a given repository is assigned to any user that has any of the higher
permissions, such as REPO_READ, as well as to anonymous users if the repository is marked as public.
The important implication of the above is that an anonymous request to this resource with a permission level
REPO_READ is guaranteed to receive an empty list of repositories as a result. For anonymous requests
it is therefore recommended to not specify the permission parameter at all.]]>
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.
The authenticated user must have REPO_WRITE permission for the repository that this pull request targets to call this resource.]]>
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.
The authenticated user must have REPO_WRITE permission for the repository that this pull request targets to call this resource.
Deprecated since 4.2. Use /rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/participants/{userSlug} instead.]]>
status
are UNAPPROVED, NEEDS_WORK, or
APPROVED.
If the new status
is NEEDS_WORK or APPROVED then the
lastReviewedCommit
for the participant will be updated to the latest commit of the source branch of the
pull request.
The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.]]>
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.
The authenticated user must have REPO_WRITE permission for the repository that this pull request targets to call this resource.
Deprecated since 4.2. Use /rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/participants/{userSlug} instead.]]>
The authenticated user must have the ADMIN permission to call this resource.]]>
false
to not add them to a group]]>The authenticated user must have the ADMIN permission to call this resource.]]>
This endpoint does not perform the actual user erasure, and will not modify the application in any way.
The authenticated user must have the ADMIN permission to call this resource.]]>
User erasure can only be performed on a deleted user. If the user has not been deleted first then this endpoint will return a bad request and no erasure will be performed.
Erasing user data is irreversible and may lead to a degraded user experience. This method should not be used as part of a standard user deletion and cleanup process.
Plugins can participate in user erasure by defining a <user-erasure-handler>
module. If one or more plugin
modules fail, an error summary of the failing modules is returned.
The authenticated user must have the ADMIN permission to call this resource.]]>
The authenticated user must have the ADMIN permission to call this resource.]]>
Add a user to a group.
In the request entity, the context attribute is the group and the itemName is the user.
The authenticated user must have the ADMIN permission to call this resource.]]>
Add a user to a group. This is very similar to groups/add-user
, but with the context and
itemName attributes of the supplied request entity reversed. On the face of it this may appear
redundant, but it facilitates a specific UI component in Stash.
In the request entity, the context attribute is the user and the itemName is the group.
The authenticated user must have the ADMIN permission to call this resource.]]>
Remove a user from a group.
The authenticated user must have the ADMIN permission to call this resource.
In the request entity, the context attribute is the group and the itemName is the user.]]>
In the request entity, the context attribute is the user and the itemName is the group.
The authenticated user must have the ADMIN permission to call this resource.]]>
The authenticated user must have the LICENSED_USER permission to call this resource.]]>
The authenticated user must have the LICENSED_USER permission to call this resource.]]>
The authenticated user must have REPO_ADMIN permission for the specified repository or a higher project or global permission to call this resource.]]>
The authenticated user must have REPO_ADMIN permission for the specified repository or a higher project or global permission to call this resource. In addition, a user may not demote a group's permission level if their own permission level would be reduced as a result.]]>
In addition, a user may not revoke a group's permissions if it will reduce their own permission level.]]>
The authenticated user must have REPO_ADMIN permission for the specified repository or a higher project or global permission to call this resource. In addition, a user may not reduce their own permission level unless they have a project or global permission that already implies that permission.]]>
In addition, a user may not revoke their own repository permissions if they do not have a higher project or global permission.]]>
size
, type
, blame
or noContent
.
size
will return a response like {"size":10000}
type
will return a response like {"type":"FILE"}, where possible values are
"DIRECTORY", "FILE" and "SUBMODULE"
blame
without noContent
will include blame for the lines of
content returned on the pageblame
with noContent
will omit file contents and only return
blame for the requested linesnoContent
without blame
is ignored and does nothing?size=true&type=true
will return a size
response, not a type
one; the type
parameter will
be ignored.
The blame
and noContent
query parameters are handled differently from
size
and type
. For blame
and noContent
, the
presence of the parameter implies "true" if no value is specified; size
and
and type
both require an explicit =true
or they're treated as "false".
?blame
is the same as ?blame=true
?blame&noContent
is the same as ?blame=true&noContent=true
?size
is the same as ?size=false
?type
is the same as ?type=false
The authenticated user must have REPO_READ permission for the specified repository to call this resource.]]>
repository
and branch
.
This resource accepts PUT multipart form data, containing the file in a form-field named content
.
An example curl request to update 'README.md' would be:
curl -X PUT -u username:password -F content=@README.md -F 'message=Updated using file-edit REST API' -F branch=master -F sourceCommitId=5636641a50b http://example.com/rest/api/latest/projects/PROJECT_1/repos/repo_1/browse/README.md
path
should be modified or createdpath
The file can be updated or created on a new branch. In this case, the sourceBranch
parameter should
be provided to identify the starting point for the new branch and the branch
parameter identifies
the branch to create the new commit on.]]>
size
, type
, blame
or noContent
.
size
will return a response like {"size":10000}
type
will return a response like {"type":"FILE"}, where possible values are
"DIRECTORY", "FILE" and "SUBMODULE"
blame
without noContent
will include blame for the lines of
content returned on the pageblame
with noContent
will omit file contents and only return
blame for the requested linesnoContent
without blame
is ignored and does nothing?size=true&type=true
will return a size
response, not a type
one; the type
parameter will
be ignored.
The blame
and noContent
query parameters are handled differently from
size
and type
. For blame
and noContent
, the
presence of the parameter implies "true" if no value is specified; size
and
and type
both require an explicit =true
or they're treated as "false".
?blame
is the same as ?blame=true
?blame&noContent
is the same as ?blame=true&noContent=true
?size
is the same as ?size=false
?type
is the same as ?type=false
The authenticated user must have REPO_READ permission for the specified repository to call this resource.]]>
The authenticated user must have ADMIN permission or higher to call this resource.]]>
While this endpoint can be used to verify that all selectors in the request apply as intended, it should be noted that a subsequent, actual export might contain a different set of repositories, as they might have been added or deleted in the meantime.
Note that the overall response from this endpoint can become very large when a lot of repositories end up in the selection. This is why the server is streaming the response while it is being generated (as opposed to creating it in memory and then sending it all at once) and it can be consumed in a streaming way, too.
Also, due to the potential size of the response, projects and repositories are listed with fewer details than in other REST responses.
For a more detailed description of selectors, see the endpoint documentation for starting an export.
The authenticated user must have ADMIN permission or higher to call this resource.]]>
Only 2 concurrent exports are supported per cluster node. If a request ends up on a node that is already running that many export jobs, the request will be rejected and an error returned.
The response includes a description of the job that has been started, and its ID can be used to query these details again, including the current progress, warnings and errors that occurred while processing the job, and to interrupt and cancel the execution of this job.
The request to start an export is similar to the one for previewing an export. Additionally, it accepts an optional parameter, exportLocation, which can be used to specify a relative path within data/migration/export in the shared home directory. No locations outside of that directory will be accepted for exports.
There are essentially three ways to select repositories for export. Regardless of which you use, a few general rules apply:
Now, a single repository can be selected like this:
{ "projectKey": "PRJ", "slug": "my-repo" }
Second, all repositories in a specific project can be selected like this:
{ "projectKey": "PRJ", "slug": *" }
And third, all projects and repositories in the system would be selected like this:
{ "projectKey": "*", "slug": *" }
The authenticated user must have ADMIN permission or higher to call this resource.]]>
The path in the request must point to a valid archive file. The file must be located within the data/migration/import directory in the shared home directory.
The authenticated user must have ADMIN permission or higher to call this resource.]]>
The authenticated user must have ADMIN permission or higher to call this resource.]]>
Note that import jobs are not canceled as instantaneously as export jobs. Rather, once the request has been accepted, there are a number of checkpoints at which the job will actually apply it and stop. This is to keep the system in a reasonably consistent state:
A client should always actively query the job status to confirm that a job has been successfully canceled.
The authenticated user must have ADMIN permission or higher to call this resource.]]>
There might be a small delay between accepting the request and actually cancelling the job. In most cases, the delay will be close to instantaneously. In the unlikely case of communication issues across a cluster, it can however take a few seconds to cancel a job.
A client should always actively query the job status to confirm that a job has been successfully canceled.
The authenticated user must have ADMIN permission or higher to call this resource.]]>
filter
value]]>REVIEWER
, orPARTICIPANT
]]>
The filename=
query parameter may be used to specify the exact filename to include in the
"Content-Disposition"
header. If an explicit filename is not provided, one will be automatically
generated based on what is being archived. Its format depends on the at=
value:
at=
commit:
<slug>-<default-branch-name>@<commit>.<format>
;
e.g. example-master@43c2f8a0fe8.zipat=sha
: <slug>-<at>.<format>
; e.g.
example-09bcbb00100cfbb5310fb6834a1d5ce6cac253e9.tar.gzat=branchOrTag
: <slug>-<branchOrTag>@<commit>.<format>
;
e.g. example-feature@bbb225f16e1.tar
refs/heads/master
, the short name
(master
) will be included in the filenamerelease/4.6
),
they will be converted to hyphens in the filename (release-4.5
)
Archives may be requested in the following formats by adding the format=
query parameter:
zip
: A zip file using standard compression (Default)tar
: An uncompressed tarballtar.gz
or tgz
: A GZip-compressed tarballpath=
query parameter to specify paths to
include. path=
may be specified multiple times to include multiple paths.
The prefix=
query parameter may be used to define a directory (or multiple directories) where
the archive's contents should be placed. If the prefix does not end with /
, one will be added
automatically. The prefix is always treated as a directory; it is not possible to use it to prepend
characters to the entries in the archive.
Archives of public repositories may be streamed by any authenticated or anonymous user. Streaming archives for non-public repositories requires an authenticated user with at least REPO_READ permission.]]>
srcPath
must also be specified to
produce the correct diff.
Note: This RESTful endpoint is currently not paged. The server will internally apply a hard cap to the streamed lines, and it is not possible to request subsequent pages if that cap is exceeded.
The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.]]>
true
this works as a hint to the system to attach the correct set of comments to the diff]]>false
to stream the diff without comments]]>srcPath
must also be specified to
produce the correct diff.
Note: This RESTful endpoint is currently not paged. The server will internally apply a hard cap to the streamed lines, and it is not possible to request subsequent pages if that cap is exceeded.
The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.]]>
true
this works as a hint to the system to attach the correct set of comments to the diff]]>false
to stream the diff without comments]]>General pull request comment:
{ "text": "An insightful general comment on a pull request." }Reply to a comment:
{ "text": "A measured reply.", "parent": { "id": 1 } }General file comment:
{ "text": "An insightful general comment on a file.", "anchor": { "diffType": "RANGE", "fromHash": "6df3858eeb9a53a911cd17e66a9174d44ffb02cd", "path": "path/to/file", "srcPath": "path/to/file", "toHash": "04c7c5c931b9418ca7b66f51fe934d0bd9b2ba4b" } }File line comment:
{ "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" } }
Add a new task.
Tasks are just comments with the attribute 'severity' set to 'BLOCKER':
General pull request task:
{ "text": "A task on a pull request.", "severity": "BLOCKER" }
Add a pending comment.
Pending comments are just comments with the attribute 'state' set to 'PENDING':
Pending comment:
{ "text": "This is a pending comment", "state": "PENDING" }
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.
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:
The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.]]>
ORPHANED
to stream the orphaned comments;
ALL
to stream both the active and the orphaned comments;]]>RANGE
to stream comments related to a commit range between two arbitrary commits
(requires fromHash
and toHash
);
COMMIT
to stream comments related to a commit between two arbitrary commits (requires
fromHash
and toHash
)]]>COMMIT
arbitrary change scope]]>COMMIT
arbitrary change scope]]>Convert a comment to a task or vice versa.
Comments can be converted to tasks by setting the 'severity' attribute to 'BLOCKER':
{ "severity": "BLOCKER" }
Tasks can be converted to comments by setting the 'severity' attribute to 'NORMAL':
{ "severity": "NORMAL" }
Resolve a task.
Tasks can be resolved by setting the 'state' attribute to 'RESOLVED':
{ "state": "RESOLVED" }
Note: the supplied JSON object must contain a version
that must match the
server's version of the comment or the update will fail. To determine the current version of
the comment, the comment should be fetched from the server prior to the update. Look for the
'version' attribute in the returned JSON structure.
The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.]]>
The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.]]>
true
by default, will be used]]>true
by default, will be used]]>"true"
, the content is streamed without markup]]>The authenticated user must have:
The authenticated user must have:
POST_RECEIVE
]]>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.]]>
The authenticated user must have PROJECT_ADMIN permission for the specified project to call this resource.
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.]]>
Only authenticated users may call this resource.]]>
username.N
parameter, and the optional role.N
and approved.N
parameters.
username.N
- the "root" of a single participant filter, where "N" is a natural number
starting from 1. This allows clients to specify multiple participant filters, by providing consecutive
filters as username.1
, username.2
etc. Note that the filters numbering has to start
with 1 and be continuous for all filters to be processed. The total allowed number of participant
filters is 10 and all filters exceeding that limit will be dropped.
role.N
(optional) the role associated with username.N
.
This must be one of AUTHOR
, REVIEWER
, orPARTICIPANT
approved.N
(optional) the approved status associated with username.N
.
That is whether username.N
has approved the PR. Either true
, or false
refs/heads/master
]]>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.
The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.]]>
The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.]]>
The authenticated user must either:
{ "version": 1 }
]]>page.max.changes
) and it is not
possible to request subsequent content when that cap is exceeded.
The authenticated user must have REPO_READ permission for the specified repository to call this resource.]]>
false
to stream changes without comment counts]]>Only the strategies provided will be enabled, the default must be set and included in the set of strategies.
An explicitly set pull request merge strategy configuration can be deleted by POSTing a document with an empty "mergeConfig" attribute. i.e:
{ "mergeConfig": { } }Upon completion of this request, the effective configuration will be the configuration explicitly set for the SCM, or if no such explicit configuration is set then the default configuration will be used.]]>
General pull request blocker comment:
{ "text": "A task on a pull request." }Blocker reply to a comment:
{ "text": "This reply is a task.", "parent": { "id": 1 } }General blocker file comment:
{ "text": "A blocker comment on a file.", "anchor": { "diffType": "RANGE", "fromHash": "6df3858eeb9a53a911cd17e66a9174d44ffb02cd", "path": "path/to/file", "srcPath": "path/to/file", "toHash": "04c7c5c931b9418ca7b66f51fe934d0bd9b2ba4b" } }Blocker file line comment:
{ "text": "A task 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" } }
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.
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:
The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.]]>
The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.]]>
Convert a comment to a task or vice versa.
Comments can be converted to tasks by setting the 'severity' attribute to 'BLOCKER':
{ "severity": "BLOCKER" }
Tasks can be converted to comments by setting the 'severity' attribute to 'NORMAL':
{ "severity": "NORMAL" }
Resolve a blocker comment.
Blocker comments can be resolved by setting the 'state' attribute to 'RESOLVED':
{ "state": "RESOLVED" }
Note: the supplied JSON object must contain a version
that must match the
server's version of the comment or the update will fail. To determine the current version of
the comment, the comment should be fetched from the server prior to the update. Look for the
'version' attribute in the returned JSON structure.
The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.]]>
The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.]]>
to
commit.
If either the from
or to
commit are not specified, they will be replaced by the
default branch of their containing repository.]]>
to
commit.
If either the from
or to
commit are not specified, they will be replaced by the
default branch of their containing repository.]]>
to
commit.
If either the from
or to
commit are not specified, they will be replaced by the
default branch of their containing repository.]]>
Warning: It is possible to downgrade the license during update, applying a license with a lower number of permitted users. If the number of currently-licensed users exceeds the limits of the new license, pushing will be disabled until the licensed user count is brought into compliance with the new license.
The authenticated user must have SYS_ADMIN permission. ADMIN users may view the current license details, but they may not update the license.]]>
]]>
The authenticated user must have REPO_READ permission for the specified repository to call this resource.]]>
GET /projects/{key}/repos/{slug}/default-branch
instead,
which allows retrieving the configured default branch even if the ref has not been created yet.
The authenticated user must have REPO_READ permission for the specified repository to call this resource.]]>
PUT /projects/{key}/repos/{slug}/default-branch
instead.
The authenticated user must have REPO_ADMIN permission for the specified repository to call this resource.]]>
POST_RECEIVE
]]>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.]]>
The authenticated user must have REPO_ADMIN permission for the specified repository to call this resource.
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.]]>
The authenticated user must have REPO_ADMIN permission for the specified repository to call this resource.]]>
The authenticated user must have REPO_READ permission for the specified repository to call this resource.]]>
until
.]]>at
commit or, if not specified, from the tip of the default branch.
Unless the repository is public, the authenticated user must have REPO_READ access to call this resource.]]>
at
commit does not contain the requested path.]]>at
commit or, if not specified, from the tip of the default branch.
Unless the repository is public, the authenticated user must have REPO_READ access to call this resource.]]>
at
commit does not contain the requested path.]]>]]>
]]>
]]>
Filters are provided in query parameters in a standard name=value
fashion. The following filters are
currently supported:
filter
- return only users, whose username, name or email address contain the
filter
value
group
- return only users who are members of the given group
permission
- the "root" of a permission filter, whose value must be a valid global,
project, or repository permission. Additional filter parameters referring to this filter that specify the
resource (project or repository) to apply the filter to must be prefixed with permission.
. See the
section "Permission Filters" below for more details.
permission.N
- the "root" of a single permission filter, similar to the permission
parameter, where "N" is a natural number starting from 1. This allows clients to specify multiple permission
filters, by providing consecutive filters as permission.1
, permission.2
etc. Note that
the filters numbering has to start with 1 and be continuous for all filters to be processed. The total allowed
number of permission filters is 50 and all filters exceeding that limit will be dropped. See the section
"Permission Filters" below for more details on how the permission filters are processed.
The following three sub-sections list parameters supported for permission filters (where [root]
is
the root permission filter name, e.g. permission
, permission.1
etc.) depending on the
permission resource. The system determines which filter to apply (Global, Project or Repository permission)
based on the [root]
permission value. E.g. ADMIN
is a global permission,
PROJECT_ADMIN
is a project permission and REPO_ADMIN
is a repository permission. Note
that the parameters for a given resource will be looked up in the order as they are listed below, that is e.g.
for a project resource, if both projectId
and projectKey
are provided, the system will
use projectId
for the lookup.
The permission value under [root]
is the only required and recognized parameter, as global
permissions do not apply to a specific resource.
Example valid filter: permission=ADMIN
.
[root]
- specifies the project permission[root].projectId
- specifies the project ID to lookup the project by[root].projectKey
- specifies the project key to lookup the project by
Example valid filter: permission.1=PROJECT_ADMIN&permission.1.projectKey=TEST_PROJECT
.
[root]
- specifies the repository permission[root].projectId
- specifies the repository ID to lookup the repository by[root].projectKey
and [root].repositorySlug
- specifies the project key and
repository slug to lookup the repository by; both values need to be provided for this look up to be
triggeredpermission.2=REPO_ADMIN&permission.2.projectKey=TEST_PROJECT&permission.2.repositorySlug=test_repo
.]]>This resource accepts POST multipart form data, containing a single image in a form-field named 'avatar'.
There are configurable server limits on both the dimensions (1024x1024 pixels by default) and uploaded file size (1MB by default). Several different image formats are supported, but PNG and JPEG are preferred due to the file size limit.
This resource has Cross-Site Request Forgery (XSRF) protection. To allow the request to
pass the XSRF check the caller needs to send an X-Atlassian-Token
HTTP header with the
value no-check
.
An example curl request to upload an image name 'avatar.png' would be:
curl -X POST -u username:password -H "X-Atlassian-Token: no-check" http://example.com/rest/api/latest/users/jdoe/avatar.png -F avatar=@avatar.png
Users are always allowed to update their own avatar. To update someone else's avatar the authenticated user must have global ADMIN permission, or global SYS_ADMIN permission to update a SYS_ADMIN user's avatar.]]>
]]>
false
otherwise]]>include
, to include both merge commits and non-merge
commits or only
, to only return merge commits.]]>The authenticated user must have REPO_READ permission for the specified repository to call this resource.]]>
Deprecated since 4.2. Use /rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/participants/{userSlug} instead]]>
Deprecated since 4.2. Use /rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/participants/{userSlug} instead]]>
truncated
flags will be set to
true
on the segments, hunks and diffs substructures in the returned JSON response.
The authenticated user must have REPO_READ permission for the specified repository to call this resource.]]>
truncated
flags will be set to
true
on the segments, hunks and diffs substructures in the returned JSON response.
The authenticated user must have REPO_READ permission for the specified repository to call this resource.]]>
changeScope
query parameter is set to unreviewed
, the application will attempt to stream
unreviewed changes based on the lastReviewedCommit
of the current user, which are the changes between the
lastReviewedCommit
and the latest commit of the source branch. The current user is considered to
not have any unreviewed changes for the pull request when the lastReviewedCommit
is either
null
(everything is unreviewed, so all changes are streamed), equal to the latest commit of the source
branch (everything is reviewed), or no longer on the source branch (the source branch has been rebased). In these
cases, the application will fall back to streaming all changes (the default), which is the effective diff for the
pull request. The type of changes streamed can be determined by the changeScope
parameter included in the
properties map of the response.
Note: This resource is currently not paged. The server will return at most one page. The server will truncate the number of changes to either the request's page limit or an internal maximum, whichever is smaller. The start parameter of the page request is also ignored.
The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.]]>
RANGE
to stream changes between two arbitrary commits (requires sinceId
and
untilId
); otherwise ALL
to stream all changes (the default)]]>false
to stream changes without comment counts]]>Only the strategies provided will be enabled, only one may be set to default
An explicitly set pull request merge strategy configuration can be deleted by POSTing a document with an empty "mergeConfig" attribute. i.e:
{ "mergeConfig": { } }Upon completion of this request, the effective configuration will be the default configuration.]]>
The authenticated user must have REPO_READ permission for the specified project to call this resource.]]>
Every repository has a configured default branch, but that branch may not actually exist in the repository. For example, a newly-created repository will have a configured default branch even though no branches have been pushed yet.
The authenticated user must have REPO_READ permission for the specified repository to call this resource.]]>
The authenticated user must have sufficient permissions specified by the repository delete policy to call this resource. The default permission required is REPO_ADMIN permission.]]>
POST
is not required to contain any properties. Even the name may
be omitted. The following properties will be used, if provided:
"name":"Fork name"
- Specifies the forked repository's name
"defaultBranch":"main"
- Specifies the forked repository's default branch
"project":{"key":"TARGET_KEY"}
- Specifies the forked repository's target project by key
The authenticated user must have REPO_READ permission for the specified repository and PROJECT_ADMIN on the target project to call this resource. Note that users always have PROJECT_ADMIN permission on their personal projects.]]>
The authenticated user must have REPO_READ permission for the specified repository to call this resource.]]>
The repository's slug is derived from its name. If the name changes the slug may also change.
This resource can be used to change the repository's default branch by specifying a new default branch in the
request. For example: "defaultBranch":"main"
This resource can be used to move the repository to a different project by specifying a new project in the
request. For example: "project":{"key":"NEW_KEY"}
The authenticated user must have REPO_ADMIN permission for the specified repository to call this resource.]]>
CONTRIBUTINGfile, optionally with an
mdor
txtextension, and, if found, streams it. By default, the raw content of the file is streamed. Appending
?markupto the URL will stream an HTML-rendered version instead.
The authenticated user must have REPO_READ permission for the specified repository to call this resource.]]>
true
by default, will be used]]>true
by default, will be used]]>"true"
, the content is streamed without markup]]>LICENSEfile, optionally with an
mdor
txtextension, and, if found, streams it. By default, the raw content of the file is streamed. Appending
?markupto the URL will stream an HTML-rendered version instead.
The authenticated user must have REPO_READ permission for the specified repository to call this resource.]]>
true
by default, will be used]]>true
by default, will be used]]>"true"
, the content is streamed without markup]]>READMEfile, optionally with an
mdor
txtextension, and, if found, streams it. By default, the raw content of the file is streamed. Appending
?markupto the URL will stream an HTML-rendered version instead. Note that, when streaming HTML, relative URLs in the README will not work if applied relative to this URL.
The authenticated user must have REPO_READ permission for the specified repository to call this resource.]]>
true
by default, will be used]]>true
by default, will be used]]>"true"
, the content is streamed without markup]]>truncated
flags will be set to
true
on the "segments"
, "hunks"
and "diffs"
properties, as well as the top-level
object, in the returned JSON response.
The authenticated user must have REPO_READ permission for the specified repository to call this resource.]]>
false
otherwise. Requires the path
to be provided.]]>false
to stream the diff without comments]]>false
otherwise. Requires the path
to be provided.]]>truncated
flags will be set to
true
on the "segments"
, "hunks"
and "diffs"
properties, as well as the top-level
object, in the returned JSON response.
The authenticated user must have REPO_READ permission for the specified repository to call this resource.]]>
false
otherwise. Requires the path
to be provided.]]>false
to stream the diff without comments]]>false
otherwise. Requires the path
to be provided.]]>General commit comment:
{ "text": "An insightful general comment on a commit." }Reply to a comment:
{ "text": "A measured reply.", "parent": { "id": 1 } }General file comment:
{ "text": "An insightful general comment on a file.", "anchor": { "diffType": "COMMIT", "fromHash": "6df3858eeb9a53a911cd17e66a9174d44ffb02cd", "path": "path/to/file", "srcPath": "path/to/file", "toHash": "04c7c5c931b9418ca7b66f51fe934d0bd9b2ba4b" } }File line comment:
{ "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" } }Note: general file comments are an experimental feature and may change in the near future!
For file and line comments, 'path' refers to the path of the file to which the comment should be applied and 'srcPath' refers to the path the that file used to have (only required for copies and moves). Also, fromHash and toHash refer to the sinceId / untilId (respectively) used to produce the diff on which the comment was added. Finally diffType refers to the type of diff the comment was added on.
For line comments, 'line' refers to the line in the diff that the comment should apply to. 'lineType' refers to the type of diff hunk, which can be:
The authenticated user must have REPO_READ permission for the repository that the commit is in to call this resource.]]>
sinceId
that the comments anchored from.
The authenticated user must have REPO_READ permission for the repository that the commit is in to call this resource.]]>
Note: the supplied supplied JSON object must contain a version
that must match
the server's version of the comment or the update will fail. To determine the current version of the comment,
the comment should be fetched from the server prior to the update. Look for the 'version' attribute in the
returned JSON structure.
The authenticated user must have REPO_READ permission for the repository that the commit is in to call this resource.]]>
The authenticated user must have REPO_READ permission for the repository that the commit is in to call this resource.]]>
The authenticated user must have PROJECT_ADMIN permission for the specified project or a higher global permission to call this resource.]]>
In addition, a user may not revoke a group's permissions if it will reduce their own permission level.]]>
In addition, a user may not revoke their own project permissions if they do not have a higher global permission.]]>