swagger: '2.0'
info:
title: Bitbucket Addon Issue tracker API
description: Code against the Bitbucket API to automate simple tasks, embed Bitbucket data into your own site, build mobile or desktop apps, or even add custom UI add-ons into Bitbucket itself using the Connect framework.
version: '2.0'
termsOfService: https://www.atlassian.com/legal/customer-agreement
contact:
name: Bitbucket Support
url: https://support.atlassian.com/bitbucket-cloud/
email: support@bitbucket.org
host: api.bitbucket.org
basePath: /2.0
schemes:
- https
consumes:
- application/json
produces:
- application/json
tags:
- name: Issue tracker
description: 'The issue resources provide functionality for getting information on
issues in an issue tracker, creating new issues, updating them and deleting
them.
You can access public issues without authentication, but you can''t gain access
to private repositories'' issues. By authenticating, you will get the ability
to create issues, as well as access to updating data or deleting issues you
have access to. Issue Tracker features are not supported for repositories in workspaces administered through admin.atlassian.com.
'
paths:
/repositories/{workspace}/{repo_slug}/components:
parameters:
- name: repo_slug
in: path
description: 'This can either be the repository slug or the UUID of the repository,
surrounded by curly-braces, for example: `{repository UUID}`.
'
required: true
type: string
- name: workspace
in: path
description: 'This can either be the workspace ID (slug) or the workspace UUID
surrounded by curly-braces, for example: `{workspace UUID}`.
'
required: true
type: string
get:
tags:
- Issue tracker
description: 'Returns the components that have been defined in the issue tracker.
This resource is only available on repositories that have the issue
tracker enabled.'
summary: List components
responses:
'200':
description: The components that have been defined in the issue tracker.
schema:
$ref: '#/definitions/paginated_components'
'404':
description: The specified repository does not exist or does not have the issue tracker enabled.
schema:
$ref: '#/definitions/error'
parameters: []
security:
- oauth2:
- issue
- basic: []
- api_key: []
deprecated: true
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- read:issue:bitbucket
x-atlassian-auth-types:
- api-token
/repositories/{workspace}/{repo_slug}/components/{component_id}:
parameters:
- name: component_id
in: path
description: The component's id
required: true
type: integer
- name: repo_slug
in: path
description: 'This can either be the repository slug or the UUID of the repository,
surrounded by curly-braces, for example: `{repository UUID}`.
'
required: true
type: string
- name: workspace
in: path
description: 'This can either be the workspace ID (slug) or the workspace UUID
surrounded by curly-braces, for example: `{workspace UUID}`.
'
required: true
type: string
get:
tags:
- Issue tracker
description: Returns the specified issue tracker component object.
summary: Get a component for issues
responses:
'200':
description: The specified component object.
schema:
$ref: '#/definitions/component'
'404':
description: The specified repository or component does not exist or does not have the issue tracker enabled.
schema:
$ref: '#/definitions/error'
parameters: []
security:
- oauth2:
- issue
- basic: []
- api_key: []
deprecated: true
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- read:issue:bitbucket
x-atlassian-auth-types:
- api-token
/repositories/{workspace}/{repo_slug}/issues:
parameters:
- name: repo_slug
in: path
description: 'This can either be the repository slug or the UUID of the repository,
surrounded by curly-braces, for example: `{repository UUID}`.
'
required: true
type: string
- name: workspace
in: path
description: 'This can either be the workspace ID (slug) or the workspace UUID
surrounded by curly-braces, for example: `{workspace UUID}`.
'
required: true
type: string
get:
tags:
- Issue tracker
description: Returns the issues in the issue tracker.
summary: List issues
responses:
'200':
description: A paginated list of the issues matching any filter criteria that were provided.
schema:
$ref: '#/definitions/paginated_issues'
'404':
description: The specified repository does not exist or does not have the issue tracker enabled.
schema:
$ref: '#/definitions/error'
parameters: []
security:
- oauth2:
- issue
- basic: []
- api_key: []
deprecated: true
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- read:issue:bitbucket
x-atlassian-auth-types:
- api-token
post:
tags:
- Issue tracker
description: 'Creates a new issue.
This call requires authentication. Private repositories or private
issue trackers require the caller to authenticate with an account that
has appropriate authorization.
The authenticated user is used for the issue''s `reporter` field.'
summary: Create an issue
responses:
'201':
description: The newly created issue.
schema:
$ref: '#/definitions/issue'
headers:
Location:
type: string
description: The (absolute) URL of the newly created issue.
'401':
description: When the request wasn't authenticated.
schema:
$ref: '#/definitions/error'
'403':
description: When the authenticated user isn't authorized to create the issue.
schema:
$ref: '#/definitions/error'
'404':
description: The specified repository does not exist or does not have the issue tracker enabled.
schema:
$ref: '#/definitions/error'
parameters:
- name: _body
in: body
description: The new issue. The only required element is `title`. All other elements can be omitted from the body.
required: true
schema:
$ref: '#/definitions/issue'
security:
- oauth2:
- issue:write
- basic: []
- api_key: []
deprecated: true
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- read:issue:bitbucket
- write:issue:bitbucket
x-atlassian-auth-types:
- api-token
/repositories/{workspace}/{repo_slug}/issues/export:
parameters:
- name: repo_slug
in: path
description: 'This can either be the repository slug or the UUID of the repository,
surrounded by curly-braces, for example: `{repository UUID}`.
'
required: true
type: string
- name: workspace
in: path
description: 'This can either be the workspace ID (slug) or the workspace UUID
surrounded by curly-braces, for example: `{workspace UUID}`.
'
required: true
type: string
post:
tags:
- Issue tracker
description: 'A POST request to this endpoint initiates a new background celery task that archives the repo''s issues.
When the job has been accepted, it will return a 202 (Accepted) along with a unique url to this job in the
''Location'' response header. This url is the endpoint for where the user can obtain their zip files."'
summary: Export issues
responses:
'202':
description: The export job has been accepted
'401':
description: The request wasn't authenticated properly
schema:
$ref: '#/definitions/error'
'403':
description: When the authenticated user does not have admin permission on the repo
schema:
$ref: '#/definitions/error'
'404':
description: The repo does not exist or does not have an issue tracker
schema:
$ref: '#/definitions/error'
parameters:
- name: _body
in: body
description: The options to apply to the export. Available options include `project_key` and `project_name` which, if specified, are used as the project key and name in the exported Jira json format. Option `send_email` specifies whether an email should be sent upon export result. Option `include_attachments` specifies whether attachments are included in the export.
required: false
schema:
$ref: '#/definitions/export_options'
security:
- oauth2:
- issue
- repository:admin
- basic: []
- api_key: []
deprecated: true
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- read:issue:bitbucket
x-atlassian-auth-types:
- forge-oauth2
- api-token
/repositories/{workspace}/{repo_slug}/issues/export/{repo_name}-issues-{task_id}.zip:
parameters:
- name: repo_name
in: path
description: The name of the repo
required: true
type: string
- name: repo_slug
in: path
description: 'This can either be the repository slug or the UUID of the repository,
surrounded by curly-braces, for example: `{repository UUID}`.
'
required: true
type: string
- name: task_id
in: path
description: The ID of the export task
required: true
type: string
- name: workspace
in: path
description: 'This can either be the workspace ID (slug) or the workspace UUID
surrounded by curly-braces, for example: `{workspace UUID}`.
'
required: true
type: string
get:
tags:
- Issue tracker
description: 'This endpoint is used to poll for the progress of an issue export
job and return the zip file after the job is complete.
As long as the job is running, this will return a 202 response
with in the response body a description of the current status.
After the job has been scheduled, but before it starts executing, the endpoint
returns a 202 response with status `ACCEPTED`.
Once it starts running, it is a 202 response with status `STARTED` and progress filled.
After it is finished, it becomes a 200 response with status `SUCCESS` or `FAILURE`.'
summary: Check issue export status
responses:
'202':
description: Export job accepted
schema:
$ref: '#/definitions/issue_job_status'
examples:
application/json:
type: issue_job_status
status: ACCEPTED
phase: Initializing
total: 0
count: 0
pct: 0
'401':
description: The request wasn't authenticated properly
schema:
$ref: '#/definitions/error'
'403':
description: When the authenticated user does not have admin permission on the repo
schema:
$ref: '#/definitions/error'
'404':
description: No export job has begun
schema:
$ref: '#/definitions/error'
parameters: []
security:
- oauth2:
- issue
- repository:admin
- basic: []
- api_key: []
deprecated: true
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- read:issue:bitbucket
x-atlassian-auth-types:
- api-token
/repositories/{workspace}/{repo_slug}/issues/import:
parameters:
- name: repo_slug
in: path
description: 'This can either be the repository slug or the UUID of the repository,
surrounded by curly-braces, for example: `{repository UUID}`.
'
required: true
type: string
- name: workspace
in: path
description: 'This can either be the workspace ID (slug) or the workspace UUID
surrounded by curly-braces, for example: `{workspace UUID}`.
'
required: true
type: string
get:
tags:
- Issue tracker
description: 'When using GET, this endpoint reports the status of the current import task.
After the job has been scheduled, but before it starts executing, the endpoint
returns a 202 response with status `ACCEPTED`.
Once it starts running, it is a 202 response with status `STARTED` and progress filled.
After it is finished, it becomes a 200 response with status `SUCCESS` or `FAILURE`.'
summary: Check issue import status
responses:
'200':
description: Import job complete with either FAILURE or SUCCESS status
schema:
$ref: '#/definitions/issue_job_status'
'202':
description: Import job started
schema:
$ref: '#/definitions/issue_job_status'
examples:
application/json:
type: issue_job_status
status: ACCEPTED
phase: Attachments
total: 15
count: 0
percent: 0
'401':
description: The request wasn't authenticated properly
schema:
$ref: '#/definitions/error'
'403':
description: When the authenticated user does not have admin permission on the repo
schema:
$ref: '#/definitions/error'
'404':
description: No export job has begun
schema:
$ref: '#/definitions/error'
parameters: []
security:
- oauth2:
- issue:write
- repository:admin
- basic: []
- api_key: []
deprecated: true
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- write:issue:bitbucket
- admin:repository:bitbucket
x-atlassian-auth-types:
- api-token
post:
tags:
- Issue tracker
description: 'A POST request to this endpoint will import the zip file given by the archive parameter into the repository. All
existing issues will be deleted and replaced by the contents of the imported zip file.
Imports are done through a multipart/form-data POST. There is one valid and required form field, with the name
"archive," which needs to be a file field:
```
$ curl -u <username> -X POST -F archive=@/path/to/file.zip https://api.bitbucket.org/2.0/repositories/<owner_username>/<repo_slug>/issues/import
```'
summary: Import issues
responses:
'202':
description: Import job accepted
schema:
$ref: '#/definitions/issue_job_status'
examples:
application/json:
type: issue_job_status
status: ACCEPTED
phase: Attachments
total: 15
count: 0
percent: 0
'401':
description: The request wasn't authenticated properly
schema:
$ref: '#/definitions/error'
'403':
description: When the authenticated user does not have admin permission on the repo
schema:
$ref: '#/definitions/error'
'404':
description: No export job has begun
schema:
$ref: '#/definitions/error'
'409':
description: Import already running
schema:
$ref: '#/definitions/error'
parameters: []
security:
- oauth2:
- issue:write
- repository:admin
- basic: []
- api_key: []
deprecated: true
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- write:issue:bitbucket
- admin:repository:bitbucket
x-atlassian-auth-types:
- api-token
/repositories/{workspace}/{repo_slug}/issues/{issue_id}:
parameters:
- name: issue_id
in: path
description: The issue id
required: true
type: string
- name: repo_slug
in: path
description: 'This can either be the repository slug or the UUID of the repository,
surrounded by curly-braces, for example: `{repository UUID}`.
'
required: true
type: string
- name: workspace
in: path
description: 'This can either be the workspace ID (slug) or the workspace UUID
surrounded by curly-braces, for example: `{workspace UUID}`.
'
required: true
type: string
delete:
tags:
- Issue tracker
description: 'Deletes the specified issue. This requires write access to the
repository.'
summary: Delete an issue
responses:
'204':
description: Indicates the issue was deleted successfully.
'403':
description: When the authenticated user isn't authorized to delete the issue.
schema:
$ref: '#/definitions/error'
'404':
description: The specified repository or issue does not exist or does not have the issue tracker enabled.
schema:
$ref: '#/definitions/error'
parameters: []
security:
- oauth2:
- issue:write
- basic: []
- api_key: []
deprecated: true
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- delete:issue:bitbucket
x-atlassian-auth-types:
- api-token
get:
tags:
- Issue tracker
description: Returns the specified issue.
summary: Get an issue
responses:
'200':
description: The issue object.
schema:
$ref: '#/definitions/issue'
'403':
description: When the authenticated user isn't authorized to access the issue.
schema:
$ref: '#/definitions/error'
'404':
description: The specified repository or issue does not exist or does not have the issue tracker enabled.
schema:
$ref: '#/definitions/error'
'410':
description: The specified issue is unavailable.
schema:
$ref: '#/definitions/error'
parameters: []
security:
- oauth2:
- issue
- basic: []
- api_key: []
deprecated: true
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- read:issue:bitbucket
x-atlassian-auth-types:
- api-token
put:
tags:
- Issue tracker
description: "Modifies the issue.\n\n```\n$ curl https://api.bitbucket.org/2.0/repostories/evzijst/dogslow/issues/123 \\\n -u evzijst -s -X PUT -H 'Content-Type: application/json' \\\n -d '{\n \"title\": \"Updated title\",\n \"assignee\": {\n \"account_id\": \"5d5355e8c6b9320d9ea5b28d\"\n },\n \"priority\": \"minor\",\n \"version\": {\n \"name\": \"1.0\"\n },\n \"component\": null\n}'\n```\n\nThis example changes the `title`, `assignee`, `priority` and the\n`version`. It also removes the value of the `component` from the issue\nby setting the field to `null`. Any field not present keeps its existing\nvalue.\n\nEach time an issue is edited in the UI or through the API, an immutable\nchange record is created under the `/issues/123/changes` endpoint. It\nalso has a comment associated with the change."
summary: Update an issue
responses:
'200':
description: The updated issue object.
schema:
$ref: '#/definitions/issue'
'403':
description: When the authenticated user isn't authorized to access the issue.
schema:
$ref: '#/definitions/error'
'404':
description: The specified repository or issue does not exist or does not have the issue tracker enabled.
schema:
$ref: '#/definitions/error'
parameters: []
security:
- oauth2:
- issue:write
- basic: []
- api_key: []
deprecated: true
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- read:issue:bitbucket
- write:issue:bitbucket
x-atlassian-auth-types:
- api-token
/repositories/{workspace}/{repo_slug}/issues/{issue_id}/attachments:
parameters:
- name: issue_id
in: path
description: The issue id
required: true
type: string
- name: repo_slug
in: path
description: 'This can either be the repository slug or the UUID of the repository,
surrounded by curly-braces, for example: `{repository UUID}`.
'
required: true
type: string
- name: workspace
in: path
description: 'This can either be the workspace ID (slug) or the workspace UUID
surrounded by curly-braces, for example: `{workspace UUID}`.
'
required: true
type: string
get:
tags:
- Issue tracker
description: 'Returns all attachments for this issue.
This returns the files'' meta data. This does not return the files''
actual contents.
The files are always ordered by their upload date.'
summary: List attachments for an issue
responses:
'200':
description: A paginated list of all attachments for this issue.
schema:
$ref: '#/definitions/paginated_issue_attachments'
'401':
description: If the issue tracker is private and the request was not authenticated.
'404':
description: The specified repository or issue does not exist or does not have the issue tracker enabled.
schema:
$ref: '#/definitions/error'
parameters: []
security:
- oauth2:
- issue
- basic: []
- api_key: []
deprecated: true
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- read:issue:bitbucket
x-atlassian-auth-types:
- api-token
post:
tags:
- Issue tracker
description: 'Upload new issue attachments.
To upload files, perform a `multipart/form-data` POST containing one
or more file fields.
When a file is uploaded with the same name as an existing attachment,
then the existing file will be replaced.'
summary: Upload an attachment to an issue
responses:
'201':
description: An empty response document.
headers:
Location:
type: string
description: The URL to the issue's collection of attachments.
'400':
description: If no files were uploaded, or if the wrong `Content-Type` was used.
'401':
description: If the issue tracker is private and the request was not authenticated.
'404':
description: The specified repository or issue does not exist or does not have the issue tracker enabled.
schema:
$ref: '#/definitions/error'
parameters: []
security:
- oauth2:
- issue:write
- basic: []
- api_key: []
deprecated: true
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- write:issue:bitbucket
x-atlassian-auth-types:
- api-token
/repositories/{workspace}/{repo_slug}/issues/{issue_id}/attachments/{path}:
parameters:
- name: issue_id
in: path
description: The issue id
required: true
type: string
- name: path
in: path
description: Path to the file.
required: true
type: string
- name: repo_slug
in: path
description: 'This can either be the repository slug or the UUID of the repository,
surrounded by curly-braces, for example: `{repository UUID}`.
'
required: true
type: string
- name: workspace
in: path
description: 'This can either be the workspace ID (slug) or the workspace UUID
surrounded by curly-braces, for example: `{workspace UUID}`.
'
required: true
type: string
delete:
tags:
- Issue tracker
description: Deletes an attachment.
summary: Delete an attachment for an issue
responses:
'204':
description: Indicates that the deletion was successful
'401':
description: If the issue tracker is private and the request was not authenticated.
'404':
description: The specified repository or issue does not exist or does not have the issue tracker enabled.
schema:
$ref: '#/definitions/error'
parameters: []
security:
- oauth2:
- issue:write
- basic: []
- api_key: []
deprecated: true
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- write:issue:bitbucket
x-atlassian-auth-types:
- api-token
get:
tags:
- Issue tracker
description: 'Returns the contents of the specified file attachment.
Note that this endpoint does not return a JSON response, but instead
returns a redirect pointing to the actual file that in turn will return
the raw contents.
The redirect URL contains a one-time token that has a limited lifetime.
As a result, the link should not be persisted, stored, or shared.'
summary: Get attachment for an issue
responses:
'302':
description: A redirect to the file's contents
headers:
Location:
type: string
'401':
description: If the issue tracker is private and the request was not authenticated.
'404':
description: The specified repository or issue does not exist or does not have the issue tracker enabled.
schema:
$ref: '#/definitions/error'
parameters: []
security:
- oauth2:
- issue
- basic: []
- api_key: []
deprecated: true
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- read:issue:bitbucket
x-atlassian-auth-types:
- api-token
/repositories/{workspace}/{repo_slug}/issues/{issue_id}/changes:
parameters:
- name: issue_id
in: path
description: The issue id
required: true
type: string
- name: repo_slug
in: path
description: 'This can either be the repository slug or the UUID of the repository,
surrounded by curly-braces, for example: `{repository UUID}`.
'
required: true
type: string
- name: workspace
in: path
description: 'This can either be the workspace ID (slug) or the workspace UUID
surrounded by curly-braces, for example: `{workspace UUID}`.
'
required: true
type: string
get:
tags:
- Issue tracker
description: "Returns the list of all changes that have been made to the specified\nissue. Changes are returned in chronological order with the oldest\nchange first.\n\nEach time an issue is edited in the UI or through the API, an immutable\nchange record is created under the `/issues/123/changes` endpoint. It\nalso has a comment associated with the change.\n\nNote that this operation is changing significantly, due to privacy changes.\nSee the [announcement](https://developer.atlassian.com/cloud/bitbucket/bitbucket-api-changes-gdpr/#changes-to-the-issue-changes-api)\nfor details.\n\nChanges support [filtering and sorting](/cloud/bitbucket/rest/intro/#filtering) that\ncan be used to search for specific changes. For instance, to see\nwhen an issue transitioned to \"resolved\":\n\n```\n$ curl -s https://api.bitbucket.org/2.0/repositories/site/master/issues/1/changes \\\n -G --data-urlencode='q=changes.state.new = \"resolved\"'\n```\n\nThis resource is only available on repositories that have the issue\ntracker enabled.\n\nN.B.\n\nThe `changes.assignee` and `changes.assignee_account_id` fields are not\na `user` object. Instead, they contain the raw `username` and\n`account_id` of the user. This is to protect the integrity of the audit\nlog even after a user account gets deleted.\n\nThe `changes.assignee` field is deprecated will disappear in the\nfuture. Use `changes.assignee_account_id` instead."
summary: List changes on an issue
responses:
'200':
description: Returns all the issue changes that were made on the specified issue.
schema:
$ref: '#/definitions/paginated_log_entries'
examples:
application/json:
pagelen: 20
values:
- changes:
priority:
new: trivial
old: major
assignee:
new: ''
old: evzijst
assignee_account_id:
new: ''
old: 557058:c0b72ad0-1cb5-4018-9cdc-0cde8492c443
kind:
new: enhancement
old: bug
links:
self:
href: https://api.bitbucket.org/2.0/repositories/evzijst/dogslow/issues/1/changes/2
html:
href: https://bitbucket.org/evzijst/dogslow/issues/1#comment-2
issue:
links:
self:
href: https://api.bitbucket.org/2.0/repositories/evzijst/dogslow/issues/1
type: issue
id: 1
repository:
links:
self:
href: https://api.bitbucket.org/2.0/repositories/evzijst/dogslow
html:
href: https://bitbucket.org/evzijst/dogslow
avatar:
href: https://bitbucket.org/evzijst/dogslow/avatar/32/
type: repository
name: dogslow
full_name: evzijst/dogslow
uuid: '{988b17c6-1a47-4e70-84ee-854d5f012bf6}'
title: Updated title
created_on: '2018-03-03T00:35:28.353630+00:00'
user:
username: evzijst
nickname: evzijst
display_name: evzijst
type: user
uuid: '{aaa7972b-38af-4fb1-802d-6e3854c95778}'
links:
self:
href: https://api.bitbucket.org/2.0/users/evzijst
html:
href: https://bitbucket.org/evzijst/
avatar:
href: https://bitbucket.org/account/evzijst/avatar/32/
message:
raw: Removed assignee, changed kind and priority.
markup: markdown
html: <p>Removed assignee, changed kind and priority.</p>
type: rendered
type: issue_change
id: 2
page: 1
'404':
description: The specified repository or issue does not exist or does not have the issue tracker enabled.
schema:
$ref: '#/definitions/error'
parameters:
- name: q
in: query
description: '
Query string to narrow down the response. See
[filtering and sorting](/cloud/bitbucket/rest/intro/#filtering) for details.'
required: false
type: string
- name: sort
in: query
description: '
Name of a response property to sort results. See
[filtering and sorting](/cloud/bitbucket/rest/intro/#sorting-query-results)
for details.
# --- truncated at 32 KB (211 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bitbucket-pipelines/refs/heads/main/openapi/bitbucket-pipelines-issue-tracker-api-openapi.yml