The bitbucket 'issues' REST resource provides functionality for getting information on issues in the bitbucket issue tracker, creating new issues, updating them and deleting them.
Overview
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.
Example:
$ curl https://api.bitbucket.org/1.0/repositories/site/master/issues/
{
"count": 2131,
"filter": {},
"search": null,
"issues": [
{
"status": "resolved",
"title": "No Fantom programming language",
"reported_by": {
"username": "ystrot",
"first_name": "Yuri",
"last_name": "Strot",
"avatar": "https://bitbucket-assetroot.s3.amazonaws.com:443/c/photos/2011/Jan/18/ystrot-avatar-3606457333-0_avatar.jpg",
"resource_uri": "/1.0/users/ystrot"
},
"responsible": {
"username": "evzijst",
"first_name": "Erik",
"last_name": "van Zijst",
"avatar": "https://secure.gravatar.com/avatar/3d3f7d1bc4c6386815e2c1e16c2d1c46?d=identicon&s=32",
"resource_uri": "/1.0/users/evzijst"
},
"comment_count": 3,
"content": "There are more than 30 projects written in Fantom programming language (http://fantom.org/): https://bitbucket.org/repo/all?name=fantom\r\n\r\nHowever Fantom is not available in the language list. Could you please add it?",
"created_on": "2011-05-31 13:30:42",
"local_id": 2776,
"follower_count": 1,
"metadata": {
"kind": "enhancement",
"version": null,
"component": "repository",
"milestone": null
},
"resource_uri": "/1.0/repositories/site/master/issues/2776",
"is_spam": false
},
# more...
]
}
Getting an Individual Issue
If you specify the issue ID, you can get information on a single issue:
$ curl https://api.bitbucket.org/1.0/repositories/jespern/bitbucket/issues/64/
{
"status": "invalid",
"title": "easy_install functionality",
"reported_by": {
"username": "jespern",
"first_name": "Jesper",
"last_name": "Noehr",
"avatar": "https://secure.gravatar.com/avatar/b658715b9635ef057daf2a22d4a8f36e?d=identicon&s=32",
"resource_uri": "/1.0/users/jespern"
},
"responsible": {
"username": "jespern",
"first_name": "Jesper",
"last_name": "Noehr",
"avatar": "https://secure.gravatar.com/avatar/b658715b9635ef057daf2a22d4a8f36e?d=identicon&s=32",
"resource_uri": "/1.0/users/jespern"
},
"comment_count": 1,
"content": "Or something like it..?",
"created_on": "2008-07-21 16:04:35",
"local_id": 64,
"follower_count": 3,
"metadata": {
"kind": "bug",
"version": null,
"component": null,
"milestone": null
},
"resource_uri": "/1.0/repositories/site/master/issues/64",
"is_spam": false
}
Searching
If you do not specify an issue ID, and add the 'search' query string parameter, you can search through issues.
For example, searching for easy_install:
$ curl "https://api.bitbucket.org/1.0/repositories/site/master/issues/?search=easy_install"
{
"count": 3,
"filter": {},
"search": "easy_install",
"issues": [
{
"status": "new",
"title": "Getting an Individual Issue via API (BB-1085)",
"reported_by": {
"username": "mennanov",
"first_name": "Renat",
"last_name": "Mennanov",
"avatar": "https://bitbucket-assetroot.s3.amazonaws.com:443/c/photos/2010/Nov/09/1289284926_user_avatar.png",
"resource_uri": "/1.0/users/mennanov"
},
"comment_count": 1,
"content": "Getting an Individual Issue is useless since it does not provide enough information about the issue.\r\n\r\n{{{\r\n#!bash\r\n\r\n$ curl https://api.bitbucket.org/1.0/repositories/jespern/bitbucket/issues/64/\r\n\r\n{\r\n \"title\": \"easy_install functionality\", \r\n \"comment_count\": 1, \r\n \"content\": \"Or something like it..?\", \r\n \"created_on\": \"2008-07-21 16:04:35\", \r\n \"reported_by\": {\r\n \"username:\" \"madssj\",\r\n \"resource_uri\": \"/1.0/users/madssj/\"\r\n },\r\n \"local_id\": 64, \r\n \"follower_count\": 2, \r\n \"metadata\": {\r\n \"kind\": \"bug\"\r\n }, \r\n \"resource_uri\": \"/1.0/repositories/jespern/bitbucket/issues/64/\", \r\n \"is_spam\": false\r\n}\r\n\r\n}}}\r\n\r\nIt would be great to get issue's comments, to whom it is assigned, links to attached files etc..",
"created_on": "2010-12-04 09:14:25",
"local_id": 2317,
"follower_count": 2,
"metadata": {
"kind": "enhancement",
"version": null,
"component": null,
"milestone": null
},
"resource_uri": "/1.0/repositories/site/master/issues/2317",
"is_spam": false
},
# more...
]
}
Filtering
You can also apply filter criteria as parameters to narrow the return.
|
|
When constructing your parameter string, use one of the operators above in combination with the filter as your value. The end result should look like the below example. The parameter (key) and value pair with the desired filter operator preceding the value.
Multiple instances of the same parameter will be treated as OR for the overall filter query.
Example
$ curl https://api.bitbucket.org/1.0/repositories/jespern/bitbucket/issues/?title=~easy_install&title=~renaming+repositories+should
{
"count": 2,
"filter": {
"title": [
[
"~",
"easy_install"
],
[
"~",
"renaming repositories should"
]
]
},
"search": null,
"issues": [
{
"status": "invalid",
"title": "easy_install functionality",
"reported_by": {
"username": "jespern",
"first_name": "Jesper",
"last_name": "Noehr",
"avatar": "https://secure.gravatar.com/avatar/b658715b9635ef057daf2a22d4a8f36e?d=identicon&s=32",
"resource_uri": "/1.0/users/jespern"
},
"responsible": {
"username": "jespern",
"first_name": "Jesper",
"last_name": "Noehr",
"avatar": "https://secure.gravatar.com/avatar/b658715b9635ef057daf2a22d4a8f36e?d=identicon&s=32",
"resource_uri": "/1.0/users/jespern"
},
"comment_count": 1,
"content": "Or something like it..?",
"created_on": "2008-07-21 16:04:35",
"local_id": 64,
"follower_count": 3,
"metadata": {
"kind": "bug",
"version": null,
"component": null,
"milestone": null
},
"resource_uri": "/1.0/repositories/site/master/issues/64",
"is_spam": false
},
# more...
]
}
Specifying an Offset
GET /repositories/USERNAME/REPO_SLUG/issues/
Path components:
USERNAME: The owner username.REPO_SLUG: The slug of the repository.
Optional query string parameters:
start: Offset to start at. The default is 0.limit: Maximum number of issues returned. The default is 15.
Example with a query string parameter:
$ curl https://api.bitbucket.org/1.0/repositories/sarahmaddox/sarahmaddox/issues/?start=15
Creating an Issue
POST /repositories/USERNAME/REPO_SLUG/issues/
Parameters:
USERNAME: The owner username.REPO_SLUG: The slug of the repository.
The following POST data values specify the attributes of the issue:
title: The title of the new issue.content: The content of the new issue.component: The component associated with the issue.milestone: The milestone associated with the issue.version: The version associated with the issue.responsible: The username of the person responsible for the issue.status: The status of the issue (new,open,resolved,on hold,invalid,duplicate, orwontfix).kind: The kind of issue (bug,enhancement, orproposal).
Returns the newly created issue.
Example:
$ curl https://api.bitbucket.org/1.0/repositories/sarahmaddox/sarahmaddox/issues/ --data "title=Issue%20Title&content=Issue%20Content"
Updating an issue
PUT /repositories/USERNAME/REPO_SLUG/issues/ISSUE_ID/
Parameters:
USERNAME: The owner username.REPO_SLUG: The slug of the repository.ISSUE_ID: The ID of the issue.
Example:
$ curl --request PUT https://api.bitbucket.org/1.0/repositories/sarahmaddox/sarahmaddox/issues/1/ --data "content=Updated%20Content"
Deleting an Issue
DELETE /repositories/USERNAME/REPO_SLUG/issues/ISSUE_ID/
Parameters:
USERNAME: The owner username.REPO_SLUG: The slug of the repository.ISSUE_ID: The ID of the issue.
Getting Information about Followers of an Issue
See Followers.
RELATED TOPICS
Labels
56 Comments
Hide/Show CommentsNov 22, 2010
Anonymous
Note that though the URLs for creating, updating, and deleting are given here simply as "/",
they should in fact follow the model of the earlier URLs.
Also, POST parameters are provided to curl via the -d arg, in URL-encoded form, eg. 'foo=1&bar=2'
Feb 01, 2011
Anthony Hiscox
Can we please get this updated? I wasted about 20 minutes on this before I noticed the comments (At least 50% of that is my own fault for not scrolling down, but still...)
May 04, 2011
Justen Stepka
This has been fixed.
Dec 04, 2010
Anonymous
Dear authors, add more information when getting one particular issue, such as comments and to whom this issue is assigned.
Current information is almost useless.
Dec 11, 2010
Anonymous
Under "Creating an Issue" I believe that instead of a URL parameter "TITLE" there should be a query string parameter "title".
Dec 16, 2010
Anonymous
Has anyone successfully been able to update an issue? We seem to be getting returned the same data as the original, and the issue is not getting updated. However no error message is being returned or any indication of a problem...
Jan 28, 2011
Paul Bissex
Here's a simple script I wrote that creates issues.
Feb 20, 2011
Anonymous
When creating an issue you will also want to pass status=1, otherwise the state of the bug isn't set and it won't show up in the count on the issues tab (or in the new issues list).
Mar 01, 2011
Ken Ingle
Is there a way to get the issue assignee? The reporter is nice, but it would be very helpful to have who the issue is assigned to available through the api.
Mar 01, 2011
Erik van Zijst [Atlassian]
Hi Ken,
Not having the assignee in the rest response is an omission on our side, which we plan on fixing soon. Thanks for reporting though!
Cheers,
Erik
Apr 28, 2011
Aryeh Leib Taurog
I would like to know if/how I can change part of the issue metadata via the api. I tried the following but it doesn't work:
Apr 28, 2011
Stephen Harrison
Hi there,
I'm trying to export BitBucket issues. I got the API access kind-of working with only some of the fields I need. But how do I include the "Status" and "Responsible" metadata in the output.
What about comments and attachments on the issues?
Thanks,
/Stephen
May 03, 2011
Stephen Harrison
Well ... I got some of the way there with a hack.
So I did
(Sorry about the wide formatting.)
This gives you a bunch of files called
Then I threw the JSON files into a handy MongoDB instance to do the queries to yield CSV. I made sure the status was one of the columns.
Let me know whether this works for you or not.
Cheers,
/Stephen
May 02, 2011
Anthony Steiner
I agree with the addition of status and responsible being added to metadata.
As for the comments and attachments, I don't believe they should be included under the premise the API is only supposed to aid in getting information from the service to your end-use; not replace the service altogether.
May 03, 2011
Stephen Harrison
Hi Anthony,
I understand your point. But dude ... deliberately hobbling the API to make it harder for people to leave BitBucket is SO un-Atlassian!
I'm migrating to Mingle as it happens. But what would your story be if I wanted to migrate to Jira? That's a viable alternative for us. Does Atlassian have an upgrade path?
I've since written some HTML screen scraping and Scala parsing to get the following the API does not provide:
Anyone else had success migrating BitBucket issues to Mingle or Jira?
Cheers,
/Stephen
May 03, 2011
Anthony Steiner
A part of me agrees with you, but another thinks that's it's not up to Atlassian/BitBucket or it's users to create migration tools, it's up to the tool you're migrating to.
As it stands, BitBucket itself has SVN, CodePlex, Google Code, SourceForge and Hg repository migratory abilities; Mind you they probably won't include the issues or wiki on transfers, however, it again is hardly in a company's scope to provide an easy way to move its end-users away from their services, lol.
May 27, 2011
Jonathan Langevin
There's an initiative that non-insecure services offer, to open up customer's information for the customer to move in/out of the service at will.
You can actually lose customers if you attempt to lock in. In the industry that I work (e-learning), universities often refuse to lease a hosted LMS service if they do not have a valid exit path in case things go poorly.
I personally like Bitbucket, esp the changes that are improving the service lately, but if the service turns crappy (ala Assembla), or if my employer prefers to use the ticketing interface of some other application (which is the case for me today), we need our information to be free...
Not having the ability to fully access our data via APIs, greatly reduces the value of Bitbucket in an enterprise environment.
Jun 01, 2011
Kevin Arthur
I noticed the API was updated to allow specifying the component, milestone, etc. when creating issues. Is there a way to query the repository for valid options for these fields? If not, would happen if an invalid value were specified (i.e. a component not defined by the repository admin)?
Thanks,
Kevin
Jun 01, 2011
Justen Stepka
If you could follow this issue you'll be able to track the addition of fields you're after.
Right now we're heads down with a new feature we're developing, and will address what changes to make to the issue tracker mid-Summer.
Jun 01, 2011
Kevin Arthur
Awesome, thanks for getting back so fast.
Jun 01, 2011
Aryeh Leib Taurog
Oho! It seems that the API allows updating the milestone with PUT as well, but it seems to be taking something other than the text of the milestone. Here's the response I get now:
(looks mighty useful for an ajax-enabled issues tracker.)
Jun 01, 2011
Brodie Rao [Atlassian]
Thanks for catching that. I've put out a fix for this – you should be able to set it by the name of the milestone now.
Jun 01, 2011
Aryeh Leib Taurog
Thanks very much. It works!
Jun 01, 2011
Kevin Arthur
Also, the descriptions for the "status" and "kind" attributes seem to have been swapped in "Creating an Issue."
Jun 01, 2011
Brodie Rao [Atlassian]
Good catch! Should be fixed now.
Jul 30, 2011
Sebastian Valle Herrera
Is there a way so we can get all the issues in a single query? it seem to be limited to 50 issues in my c# application, and when i try with limit > 50 it returns error 400
Aug 01, 2011
Justen Stepka
Unfortunately not and right now we do not have a scheduled fix for this.
https://bitbucket.org/site/master/issue/2913/issue-rest-api-is-limited-to-50-issues
For now you'll need to use the start attribute to iterate over the issues.
Aug 01, 2011
Anthony Steiner
Hey Justen; Some food for thought (and possibly a recipe worth bringing to the brass)... It would be a neat idea to open up a Mb/Gb usage quota to those who've applied for OpenAuth. This way flooding can be pinpointed to a singular location.
Aug 01, 2011
Jonathan Langevin
That's acceptable, imho, as then you're just dealing with forced pagination, and someone enterprising could just issue a curl multi request to get multiple pages at once if more than 50 results are required. If we were limited to 50 results as a hard stop, that would definitely have sucked.
Aug 05, 2011
Anonymous
Is there any easy way to obtain a list of all milestones through the API?
Aug 08, 2011
Justen Stepka
You can filter by a variety of attributs. Check out the 'Filtering' section of this document.
Aug 18, 2011
Anonymous
Thanks for making quite a simple API.
Creating comments and attachments would be great. So would some sort of author map, so we can migrate users easily enough.
Also, it's really concerning that people need to result to scraping data from the website rather than being able to get a data dump from the service.
Sep 04, 2011
Anonymous
What about comments and Attachments ?
I'm using bitbucket for several projects, but I would like to integrate the issue tracker in My Eclipse Env as a plugin.
I'm blocked now because of comments and attachments !!!
Nov 11, 2011
Anonymous
I really need comments and attachments API too.
Nov 25, 2011
Anonymous
I agree that the API needs to be able to access comments. Any significant issue will probably have more interesting info in the comments.
Nov 11, 2011
Anonymous
Can you add some sort of alternative, more simple to parse the format?
For example, XML
Nov 15, 2011
Jesper Noehr [Atlassian]
By specifying ?format=xml on the end, you should be getting XML back.
Nov 15, 2011
Anonymous
Great!
It's work. Thank you!
Another question - how i can upload attachment to server?
Dec 27, 2011
Anonymous
FWIW if you consider XML easier to parse than JSON, you probably want to read more into what JSON is like. It's absolutely trivial to parse.
If what you're coding with doesn't have a parser implementation for it, my sympathies. :/
Nov 28, 2011
Yevgeniy Viktorov
Is there a way to get my issues(i.e. assigned, reported, etc.) across all repositories?
Nov 28, 2011
David Chambers [Atlassian]
No, not currently. This would be bloody useful, though, so it's something we may add at some point.
Nov 28, 2011
Anthony Steiner
Oh, it can be done! There just isn't an API call to do it. lol
It would take a solid understanding of bash and cURL placeholders, and a MongoDB to load all of the received JSON files into... but it is quite possible.
Nov 30, 2011
Grace Batumbya
I got an error when creating an issue:
user_name can't be assigned issues in this repository
Is there a way to figure out who can be assigned issues?
Jan 09, 2012
Anonymous
I am trying to build this project with Visual Studio 2010, but i cannot because i have problem C2027 with JsonBox::Value. The error is:
>c:\program files (x86)\microsoft visual studio 10.0\vc\include\deque(795): error C2027: use of undefined type 'JsonBox::Value'
1> c:\usersxxx\documents\codeprojects\testjsonbox\testjsonbox\array.h(8) : see declaration of 'JsonBox::Value'
1> c:\users\xxx\documents\codeprojects\testjsonbox\testjsonbox\array.h(15) : see reference to class template instantiation 'std::deque<_Ty>' being compiled
Jan 09, 2012
Anthony Steiner
I'm not entirely familiar with C++, I'm more of a C#/PHP programmer myself; but if I understand the C2027 compile error properly... I do believe you're attempting to use JsonBox::Value as type, it's actually a method. JsonBox::Value(). Something to that effect.
Sadly this is hardly the place to post such a inquiry, since the issue is within your build of JsonBox. You should put further requests there. One thing you should keep in mind with dotnet, is that Json decoding/deserialization almost always requires a strong-typed class to build it into... and since most RESTful webservice in-fact to not come equipped with and Discovery or Schema pages (to my knowledge)... it might be slightly more difficult that you'd hoped for. Good luck!
Jan 09, 2012
Anonymous
In this part of code there is the problem
namespace JsonBox {
class Value;
/**
* Represents an array of values in JSON. It's a deque with added methods.
* So it can be used the same way as a standard STL deque, but can be more
* easily output in a stream.
* @see JsonBox::Value
*/
class Array : public std::deque<Value> {
friend class Value;
Also in the Value class there is sth like
#include "Type.h"
#include "Array.h"
#include "Object.h"
namespace JsonBox {
class Value;
/**
* Represents a json value. Can be a string, an integer, a floating point
* number, an object, an array, a boolean value or a null value. To put it
* simply, it acts a lot like a variant. Objects and arrays are classes that
* inherit from a map and a deque.
* The user doesn't have to worry about character escaping in strings,
* the i/o algorithms take care of that for the user.
* @see JsonBox::Array
* @see JsonBox::Object
*/
class Value {
friend class Array;
friend class Object;
and maybe there is a confict about Value class...
Jan 09, 2012
Anonymous
In which IDE it is tested?
Thanks in advanced!
Feb 02, 2012
Brian Forst
The "offset" parameter should be changed to "start" like so:
Feb 02, 2012
Mary Anthony [Atlassian]
Thanks for the catch Brian. I've updated the doc.
Mar 07, 2012
Mauro Asprea
Created a Gist here https://gist.github.com/18fadee85dd6012e3f3d. It's bitbucket api for Rail's ActiveResource. I'm using it in my Rails setup
for the Issues resource, but it should work for the others resources if you've been consistent in the implementation of your kind of "Restful" API
Mar 07, 2012
David Chambers [Atlassian]
Thanks for sharing this code, Mauro. I'm sure others will find it useful.
Mar 14, 2012
Nick Karasev
Is it possible to add attachments to RESTful call that creates an issue?
The most obvious use case is if I'm automatically reporting a bug, I might want to attach additional information such as log files, configuration, etc. needed to replicate it.
The web based interface allows for specifying attachments, and it would be great to have this ability here as well. Otherwise, any serious error reporting will have to leverage some other storage which makes things more complicated than they should be.
Mar 16, 2012
Grace Batumbya
Hi Nick,
You are not the only one interested in this.
There already exists an issue, #3200 Allow attachments via the REST API (BB-2913), on the issue tracker from October 2011. The comments on the issue show that Atlassian is aware of the request for this feature.
May be you can "bump" the issue.
Mar 16, 2012
Nick Karasev
I got a response on the forum. Looks there is another item opened now. What can I say? The more, the better! Perhaps, if enough people ask for the feature, it will indeed make an appearance soon.
Apr 16, 2012
Anonymous
A man is called selfish, not pursuing his own good, but neglecting his neighbour’s. prosperity editfrv66 makes friends, adversity tries them. Cheap New Era Hats Wholesale New Era Hats New Era Hats Cheap New Era Hats Wholesale
May 04, 2012
Russell West
For those like me who struggled a bit working out how to send a POST request (i'm fairly new to using this!) I have uploaded a basic PHP script that works and creates a new issue.
http://dpaste.com/hold/742732/
Add Comment