issues Resource

Overview

The issues resource provides 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 will only receive a subset of information, and you can't gain access to private repositories' issues. By authenticating, you will get a more detailed set of information, the ability to create issues, as well as access to updating data or deleting issues you have access to.

Field Description
count An integer representing the count of issues returned.
filter A string representing a filter applied to a search.
search A string containing a search term.
issues An array of issue structures.

An issue structure contains the following fields.

Field Description
status

A enumerator representing the issue status. Valid status values are:

  • new  
  • open
  • resolved
  • on hold
  • invalid
  • duplicate
  • wontfix
priority

A enumerator representing the issue priority. Valid priority values are:

  • trivial
  • minor
  • major
  • critical
  • blocker
title A string containing the issue title.
reported_by Contains the profile for the user that reported the issue.
utc_last_updated A Universal Timestamp Coordinate representing the last time the issue was updated.
comment_count An integer representing the number of comments on the issue.
metadata

A structure containing the following:

kind

This is equivalent to the Type value in the GUI. It can take any of the following values:

  • bug
  • enhancement
  • proposal
  • task
version A user defined enumerator value.
component A user defined enumerator value.
milestone A user defined enumerator value.
content A string containing the issue description.
created_on The timestamp from the Bitbucket server.
local_id An integer representing the id for this issue tracker.
follower_count An integer for the number of followers.
utc_created_on A Universal Timestamp Coordinate timestamp for the issue creation.
resource_uri A URI for the issue.
is_spam A boolean indicating if the issue is spam or not. The Bitbucket service uses Akismet to protect its users from spam. When Akismet indicates a comment may be spam, Bitbucket sets is_spam to true.

When getting a list of issues, you can apply a filter to the issues. The Bitbucket service supports the following filter operators:

Operator

Definition

~

contains
 !~

doesn't contain

 ^

begins with

 $

ends with

 !

is not

Not applicable

is

When constructing your parameter string, combine one of the issue fields as a parameter and the operator in the parameter value. The following table illustrates some examples of how to construct a parametized filter:

Parameter Value Notes What the filter will look like:
status open status is open
status=open&kind=!bug&title=~work
kind !bug kind is not bug
title ~work title contains work

A curl call using this filter looks like this:

curl https://api.bitbucket.org/1.0/repositories/jespern/django-piston/issues?status=open&kind=!bug&title=~work
  When the call returns, it lists the count of matching issues the filter found (in this case 1).

You can query for multiple instances of the same parameter. The system treats multiple instances of the same parameter as an OR for the overall filter query. For example, the following filter looks for open and resolved bugs with the word for in the title:

status=open&kind=!bug&status=resolved&title=~for 

The filter operators do not work with all of the possible issue fields. The following table lists the fields you can filter on and which operators work with them.

Issue Field

Supported Filter Operators

title

All

content

All

version

is and ! ( is not)

milestone

is and ! ( is not)

component

is and ! ( is not)

kind

is and ! ( is not)

status

is and ! ( is not)

responsible

is and ! ( is not)

reported_by

All

To simply search through the issues for a phrase, supply a simple search parameter with a string value:

curl https://api.bitbucket.org/1.0/repositories/jespern/django-piston/issues?search=each+thread

Use the + (plus sign) to indicate a space in the search phrase.

GET a list of issues in a repository's tracker

Gets the list of issues in the repository.  If you issue this call without filtering parameters, the count value contains the total number of issues in the repository's tracker.  If you filter this call, the count value contains the total number of issues that meet the filter criteria.

Authorization is not required for public repositories with a public issue tracker. Private repositories or private issue trackers require the caller to authenticate with an account that has appropriate authorisation. By default, this call returns 15 issues. If necessary you can specify the sort parameter to order the output. 

You can supply any of the following parameters to this call:

Parameter

Required?

Description

accountname Yes The team or individual account owning the repository.
repo_slug Yes The repository identifier.
limit No An integer specifying the number of issues to return. You can specify a value between 0 and 50. The default is 15.
start No Offset to start at. The default is 0 (zero).
search No A string to search for.
sort No

Sorts the output by any of the metadata fields. Enter a name value pair similar to the following:

sort=milestone

title

No

Contains a filter operation to restrict the list of issues.

content

No

Contains a filter operation to restrict the list of issues.

version

No

Contains an is or ! ( is not) filter to restrict the list of issues.

milestone

No

Contains an is or ! ( is not) filter to restrict the list of issues.

component

No

Contains an is or ! ( is not) filter   to restrict the list of issues.

kind

No

  Contains an is or ! ( is not) filter   to restrict the list of issues.

status

No

  Contains an is or ! ( is not) filter  to restrict the list of issues.

responsible

No

  Contains an is or ! ( is not) filter   to restrict the list of issues.

reported_by

No

Contains a filter operation to restrict the list of issues.

 GET https://api.bitbucket.org/1.0/repositories/{accountname}/{repo_slug}/issues?parameter=value&parameter=value&...
  Click here to expand...

GET an individual issue

Gets in individual issue from a repository. Authorisation is not required for public repositories with a public issue tracker. Private repositories or private issue trackers require the caller to authenticate  with an account that has appropriate access. This method has the following parameters:

Parameter

Required?

Description

accountname Yes The team or individual account owning the repository.
repo_slug Yes The repository identifier.

issue_id

Yes

The issue identifier.

 GET https://api.bitbucket.org/1.0/repositories/{accountname}/{repo_slug}/issues/{issue_id}
  Click here to expand...

GET a list of an issue's followers

Gets the followers for an individual issue from a repository. authorisation is not required for public repositories with a public issue tracker. Private repositories or private issue trackers require the caller to authenticate  with an account that has appropriate access. This method has the following parameters:

Parameter

Required?

Description

accountname Yes The team or individual account owning the repository.
repo_slug Yes The repository identifier.

issue_id

Yes

The issue identifier.

 GET https://api.bitbucket.org/1.0/repositories/{accountname}/{repo_slug}/issues/{issue_id}/followers
  Click here to expand...

POST a new issue

Creates a new issue in a repository. This call requires authentication. Private repositories or private issue trackers require the caller to authenticate with an account that has appropriate authorisation. The authenticated user is used for the issue's reported_by field.

Field Required Description
status no

A enumerator representing the issue status. Valid status values are:

  • new  
  • open
  • resolved
  • on hold
  • invalid
  • duplicate
  • wontfix
priority no

A enumerator representing the issue priority. Valid priority values are:

  • trivial
  • minor
  • major
  • critical
  • blocker
title yes A string containing the issue title.
responsible no The accountname of the person responsible for this issue.
content no A string containing the issue description. You'll need URL encode the content string.
kind no

This is equivalent to the Type value in the GUI. It can take any of the following values:

  • bug
  • enhancement
  • proposal
  • task
component no A string containing a component value. These values are defined by the repository administrators.
milestone no A string containing a milestone value. These values are defined by the repository administrators.
version no A string containing a version value. These values are defined by the repository administrators

 POST https://api.bitbucket.org/1.0/repositories/{accountname}/{repo_slug}/issues  --data "title=value&content=value"
  Click here to expand...

Update an existing issue

Updates an existing issue. Updating the title or content fields requires that the caller authenticate as a user with write access. For other fields, the caller must authenticate as a user with read access. Private repositories or private issue trackers require the caller to authenticate  with an account that has appropriate access. This method has the following parameters:

Field
Required?
Description
accountname Yes The team or individual account owning the repository.
repo_slug Yes The repository identifier.

issue_id

Yes

The issue identifier.

status No

A enumerator representing the issue status. Valid status values are:

  • new  
  • open
  • resolved
  • on hold
  • invalid
  • duplicate
  • wontfix
priority No

A enumerator representing the issue priority. Valid priority values are:

  • trivial
  • minor
  • major
  • critical
  • blocker
title No A string containing the issue title.
responsible No The accountname of the person responsible for this issue.
content No A string containing the issue description.
kind No

This is equivalent to the Type value in the GUI. It can take any of the following values:

  • bug
  • enhancement
  • proposal
  • task
component No A string containing a component value. These values are defined by the repository administrators.
milestone No A string containing a milestone value. These values are defined by the repository administrators.
version No A string containing a version value. These values are defined by the repository administrators

PUT https://api.bitbucket.org/1.0/repositories/{accountname}/{repo_slug}/issues/{issue_id}  --data "parameter=value&parameter=value"
  Click here to expand...

DELETE an issue

Deletes the specified issue_id. Private repositories or private issue trackers require the caller to authenticate  with an account that has appropriate access. This method has the following parameters:

Parameter

Required?

Description

accountname Yes The team or individual account owning the repository.
repo_slug Yes The repository identifier.

issue_id

Yes

The issue identifier.

DELETE https://api.bitbucket.org/1.0/repositories/{accountname}/{repo_slug}/issues/{issue_id}

This call returns 204 no content on a successful operation.

GET the comments for an issue

Gets the array of comments on the specified issue. An issue has the following fields:

Field Description
content The content of the comment.
author_info The account profile of the user that added the comment. Only Bitbucket account holders can comment on issues.
comment_id An integer representing an id for the comment. This is created by Bitbucket.
utc_updated_on A Universal Timestamp Coordinate timestamp for the last time the comment was updated.
utc_created_on A Universal Timestamp Coordinate timestamp for the comment creation.
is_spam A boolean indicating if the issue is spam or not. The Bitbucket service uses Akismet to protect its users from spam. When Akismet indicates a comment may be spam, Bitbucket sets is_spam to true.

 Private repositories or private issue trackers require the caller to authenticate  with an account that has appropriate access. This method has the following parameters:

Parameter

Required?

Description

accountname Yes The team or individual account owning the repository.
repo_slug Yes The repository identifier.

issue_id

Yes

The issue identifier.

GET https://api.bitbucket.org/1.0/repositories/{accountname}/{repo_slug}/issues/{issue_id}/comments
  Click here to expand...

GET an individual comment

Gets an individual comment on an issue. Private repositories or private issue trackers require the caller to authenticate  with an account that has appropriate access. This method has the following parameters:

Parameter

Required?

Description

accountname Yes The team or individual account owning the repository.
repo_slug Yes The repository identifier.

issue_id

Yes

The issue identifier.

comment_id Yes The comment identifier.
GET https://api.bitbucket.org/1.0/repositories/{accountname}/{repo_slug}/issues/{issue_id}/comments/{comment_id}
  Click here to expand...

POST a new comment on the issue

Creates a new comment on an issue using the specified contentdata. The caller must be authenticated and have access to the issue tracker to create an issue. This method has the following parameters:

Parameter

Required?

Description

accountname Yes The team or individual account owning the repository.
repo_slug Yes The repository identifier.

issue_id

Yes

The issue identifier.

content Yes The comment.

POST https://api.bitbucket.org/1.0/repositories/{accountname}/{repo_slug}/issues/{issue_id}/comments --data "content=string"
  Click here to expand...

Update a comment

Updates a comment on an issue using the specified content data. The caller must be authenticated as a user that created the comment or as a user with administrative rights on the repository. This method has the following parameters:

Parameter

Required?

Description

accountname Yes The team or individual account owning the repository.
repo_slug Yes The repository identifier.

issue_id

Yes

The issue identifier.

comment_id Yes The comment identifier.
content Yes The comment.

PUT https://api.bitbucket.org/1.0/repositories/{accountname}/{repo_slug}/issues/{issue_id}/comments/{comment_id} --data "content=string"
  Click here to expand...

GET the components defined on an issue tracker

Gets an array of the components associated with the issue tracker. Components have the following fields:

Field Description
object_id The component's absolute ID (the database ID—a repository's first component will not have an ID of 1).
name The component's name. A name cannot exceed 128 characters and must be unique. The issue tracker is case sensitive — it considers Release and release to be unique names.

To get the list of components, private issue trackers require the caller to authenticate with an account that has appropriate authorisation. This method has the following parameters:

Parameter

Required?

Description

accountname Yes The team or individual account owning the repository.
repo_slug Yes The repository identifier.
 GET https://api.bitbucket.org/1.0/repositories/{accountname}/{repo_slug}/issues/components
  Click here to expand...

GET an individual component

Gets an individual component in an issue tracker. To get a component, private issue trackers require the caller to authenticate with an account that has appropriate authorisation. This method has the following parameters:

Parameter

Required?

Description

accountname Yes The team or individual account owning the repository.
repo_slug Yes The repository identifier.
object_id Yes The component identifier.
 GET https://api.bitbucket.org/1.0/repositories/{accountname}/{repo_slug}/issues/components/{object_id}
  Click here to expand...
{
    "name": "api",
    "id": 37
}

POST a new component in an issue tracker

Creates a new component in an issue tracker. You must supply a namevalue in the form of a string. The server creates the id for you and it appears in the return value. Public and private issue trackers require the caller to authenticate with an account that has appropriate authorisation. This method has the following parameters:

Parameter

Required?

Description

accountname Yes The team or individual account owning the repository.
name Yes The component name to create.
repo_slug Yes The repository identifier.
POST https://api.bitbucket.org/1.0/repositories/{accountname}/{repo_slug}/issues/components --data "name=String"
  Click here to expand...
{
    "name": "gui",
    "id": 908
}

Update an existing component

Updates an existing component in an issue tracker. You must supply a name value in the form of a string. Public and private issue trackers require the caller to authenticate with an account that has appropriate authorisation. This method has the following parameters:

Parameter

Required?

Description

accountname Yes The team or individual account owning the repository.
repo_slug Yes The repository identifier.
name Yes The component name to create.
object_id Yes The component identifier.
PUT https://api.bitbucket.org/1.0/repositories/{accountname}/{repo_slug}/issues/components/{object_id} --data "name=String"
  Click here to expand...

DELETE a component from the issue tracker

Deletes a component in an issue tracker. Keep in mind that the component can be in use on existing issues. When you delete a component, the system updates the issues and does the following:

  • remove the component type
  • leaves the issue's component value empty
  • adds a comment to the issue explaining the change

To delete a component, public and private issue trackers require the caller to authenticate with an account that has appropriate authorisation. This method has the following parameters:

Parameter

Required?

Description

accountname Yes The team or individual account owning the repository.
repo_slug Yes The repository identifier.
object_id Yes The component to delete.
DELETE https://api.bitbucket.org/1.0/repositories/{accountname}/{repo_slug}/issues/components/{object_id}

This call returns the following on succes:

HTTP/1.1 204 NO CONTENT

GET a list of versions

Gets an array of the versions associated with the issue tracker. Versions have the following fields:

Field Description
object_id The version's absolute ID (the database ID—a repository's first component will not have an ID of 1).
name The version name. A name cannot exceed 128 characters and must be unique.

To get the list of versions, private issue trackers require the caller to authenticate with an account that has appropriate authorisation.   This method has the following parameters:

Parameter

Required?

Description

accountname Yes The team or individual account owning the repository.
repo_slug Yes The repository identifier.
GET https://api.bitbucket.org/1.0/repositories/{accountname}/{repo_slug}/issues/versions
  Click here to expand...

GET an individual version

Gets an individual version in an issue tracker. Public and private issue trackers require the caller to authenticate with an account that has appropriate authorisation. This method has the following parameters:

Parameter

Required?

Description

accountname Yes The team or individual account owning the repository.
repo_slug Yes The repository identifier.
object_id Yes The component identifier.
 GET https://api.bitbucket.org/1.0/repositories/{accountname}/{repo_slug}/issues/versions/{object_id}
  Click here to expand...

POST a new version

Creates a new version in an issue tracker. You must supply a name value in the form of a string. The server creates the id for you and it appears in the return value. Public and private issue trackers require the caller to authenticate with an account that has appropriate authorisation. This method has the following parameters:

Parameter

Required?

Description

accountname Yes The team or individual account owning the repository.
repo_slug Yes The repository identifier.
name Yes The version name to create.
POST https://api.bitbucket.org/1.0/repositories/{accountname}/{repo_slug}/issues/versions --data "name=String"
  Click here to expand...
{
    "name": "2.0",
    "id": 9108
}

PUT an update to a version

Updates an existing version in an issue tracker. You must supply a name value in the form of a string. Public and private issue trackers require the caller to authenticate with an account that has appropriate authorisation. This method has the following parameters:

Parameter

Required?

Description

accountname Yes The team or individual account owning the repository.
repo_slug Yes The repository identifier.
object_id Yes The component identifier.
name Yes The version name to create.
 PUT https://api.bitbucket.org/1.0/repositories/{accountname}/{repo_slug}/issues/versions/{object_id} --data "name=String"
  Click here to expand...

DELETE a version

Deletes a version in an issue tracker. Keep in mind that the version can be in use on existing issues. When you delete a version, the system updates the issues and does the following:

  • remove the version type
  • leaves the issue's version value empty
  • adds a comment to the issue explaining the change

To delete a version, public and private issue trackers require the caller to authenticate with an account that has appropriate authorisation. This method has the following parameters:

Parameter

Required?

Description

accountname Yes The team or individual account owning the repository.
repo_slug Yes The repository identifier.
object_id Yes The component identifier.
DELETE https://api.bitbucket.org/1.0/repositories/{accountname}/{repo_slug}/issues/versions/{object_id}

This call returns the following on success:

HTTP/1.1 204 NO CONTENT

GET the defined milestones

Gets an array of the milestones associated with the issue tracker. Milestones have the following fields:

Field Description
object_id The milestones absolute ID (the database ID—a repository's first milestone will not have an ID of 1).
name The version name. A name cannot exceed 128 characters and must be unique.

To get the list of milestones, private issue trackers require the caller to authenticate with an account that has appropriate authorisation. This method has the following parameters:

Parameter

Required?

Description

accountname Yes The team or individual account owning the repository.
repo_slug Yes The repository identifier.
GET https://api.bitbucket.org/1.0/repositories/{accountname}/{repo_slug}/issues/milestones
  Click here to expand...

GET an individual milestone

Gets an individual milestone in an issue tracker. Public and private issue trackers require the caller to authenticate with an account that has appropriate authorisation. This method has the following parameters:

Parameter

Required?

Description

accountname Yes The team or individual account owning the repository.
repo_slug Yes The repository identifier.
object_id Yes The component identifier.
 GET https://api.bitbucket.org/1.0/repositories/{accountname}/{repo_slug}/issues/milestones/{object_id}
  Click here to expand...

POST a new milestone

Creates a new milestone in an issue tracker. You must supply a name value in the form of a string. The server creates the id for you and it appears in the return value. Public and private issue trackers require the caller to authenticate with an account that has appropriate authorisation. This method has the following parameters:

Parameter

Required?

Description

accountname Yes The team or individual account owning the repository.
repo_slug Yes The repository identifier.
name Yes The version name to create.
POST https://api.bitbucket.org/1.0/repositories/{accountname}/{repo_slug}/issues/milestones --data "name=String"
  Click here to expand...

PUT an update to milestones

Updates an existing milestone in an issue tracker. You must supply a name value in the form of a string. Public and private issue trackers require the caller to authenticate with an account that has appropriate authorisation. This method has the following parameters:

Parameter

Required?

Description

accountname Yes The team or individual account owning the repository.
repo_slug Yes The repository identifier.
object_id Yes The component identifier.
name Yes The version name to create.
PUT https://api.bitbucket.org/1.0/repositories/{accountname}/{repo_slug}/issues/milestones/{object_id} --data "name=String"
  Click here to expand...

DELETE a milestone

Deletes a milestone in an issue tracker. Keep in mind that the milestone can be in use on existing issues. When you delete a milestone, the system updates the issues and does the following:

  • remove the milestone type
  • leaves the issue's milestone value empty
  • adds a comment to the issue explaining the change

To delete a milestone, public and private issue trackers require the caller to authenticate with an account that has appropriate authorisation. This method has the following parameters:

Parameter

Required?

Description

accountname Yes The team or individual account owning the repository.
repo_slug Yes The repository identifier.
object_id Yes The component identifier.
DELETE https://api.bitbucket.org/1.0/repositories/{accountname}/{repo_slug}/issues/milestones/{object_id}

This call returns the following on succes:

HTTP/1.1 204 NO CONTENT

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport