changesets Resource

Overview

Use changesets resources to manage changesets resources on a repository. Unauthenticated calls for these resources only return values for public repositories. To see changeset resources on private repositories, the caller must authenticated and must have at least read permissions on the repository. Changesets are read-only resources, you can't add or modify a changeset structure. You can modify the secondary resources such as comments associated with an individual change set node.

An individual changeset structure has the following information:

Field Description
node Unique ID for the changeset – this is an abbreviated SHA code.
files An array of files included in the changeset.
raw_author The username defined locally and included in the commit passed to the Bitbucket service.
utctimestamp Universal time stamp applied to the change.
timestamp The time provided on the local machine where the commit occurred.
author The Bitbucket account associated with the changeset.
raw_node A forty-character changeset hash – this is the unabbreviated SHA value.
parents The commit that your local directory was at before the changeset was committed. When a user adds a file, that file does not have a parent as there was no preceding commit.
branch The name of the branch on which the change resides. The branch name can be null and is typically so for Git repositories.
message The commit message.
revision An integer assigned to a commit. This field is used for Mercurial repositories only. The value itself is an integer that is valid only within the specific local repository.
size This field is reserved and always contains -1.

GET a list of changesets

Gets a list of change sets associated with a repository. By default, this call returns the 15 most recent changesets. It also returns the count which is the total number of changesets on the repository. Private repositories require the caller to authenticate. This call takes the following parameters:

Parameter Required? Description
accountname Yes The team or individual account owning the repo.
repo_slug Yes The repo identifier.
limit Yes An integer representing how many changesets to return. You can specify a limit between 0 and 50. If you specify 0 (zero), the system returns the count but returns empty values for the remaining fields.
start Yes A hash value representing the earliest node to start with. The system starts with the specified node and includes the older requests that preceded it. The Bitbucket GUI lists the nodes on the Commit tab. The default start value is the tip.
GET https://bitbucket.org/api/1.0/repositories/{accountname}/{repo_slug}/changesets?limit=integer?start=node
  Click here to expand...

GET an individual changeset

Gets a specific changeset  nodePrivate repositories require the caller to authenticate. This call takes the following parameters:

Parameter Required? Description
accountname Yes The team or individual account owning the repo.
repo_slug Yes The repo identifier.
node
Yes The node changeset identifier.
GET https://bitbucket.org/api/1.0/repositories/{accountname}/{repo_slug}/changesets/{node}
  Click here to expand...

GET participants associated with an individual changeset

Changesets can be collaborated on by users through commenting and approvals. This list of people is embedded in the participants element in the commit object that is returned by Bitbucket's v2 API.

GET https://bitbucket.org/api/2.0/repositories/{accountname}/{repo_slug}/commit/{sha1}

GET statistics associated with an individual changeset

Returns an array containing statistics on changed file associated with a particular  node in a change set. Private repositories require the caller to authenticate. This call takes the following parameters:

Parameter Required? Description
accountname Yes The team or individual account owning the repo.
repo_slug Yes The repo identifier.
node Yes The node changeset identifier.

 The information returned by this call includes the following:

  • type of change
  • name of file
  • count of lines removed
  • count of lines added

Calculating the count of  lines added and removed (diffstat) can be expensive if the difference is very large. When the difference is large,  this call has the potential to time out and crash. To prevent crashes/timeouts, Bitbucket reports any large difference in the count of lines added or removed as a JSON null.  

GET https://bitbucket.org/api/1.0/repositories/{accountname}/{repo_slug}/changesets/{node}/diffstat 
  Click here to expand...

GET the diff associated with a changeset

Gets the actual diff associated with the changeset node. This call returns the output as a string containing JSON. Private repositories require the caller to authenticate. This call takes the following parameters:

Parameter Required? Description
accountname Yes The team or individual account owning the repo.
repo_slug Yes The repo identifier.
node Yes The node changeset identifier.
GET https://bitbucket.org/api/1.0/repositories/{accountname}/{repo_slug}/changesets/{node}/diff
  Click here to expand...

GET a list of comments on a changeset

Gets the comments associated with a particular changeset node. Users can create and edit comments on particular changesets. Private repositories require the caller to authenticate. This call takes the following parameters:

Parameter Required? Description
accountname Yes The team or individual account owning the repo.
repo_slug Yes The repo identifier.
node Yes The node changeset identifier.
GET https://bitbucket.org/api/1.0/repositories/{accountname}/{repo_slug}/changesets/{node}/comments
  Click here to expand...

This call also returns markers for deleted comments where deleted is true. The following displays returns that include a deleted comment:

DELETE a comment on a changeset

Deletes the specified  comment_id associated with a particular changeset  node . To delete a comment, you must have administrative rights on the repository, the account, or be authenticated as the username associated with the comment. Private repositories require the caller to authenticate. This call takes the following parameters:

Parameter Require Description
accountname Yes The team or individual account owning the repo.
repo_slug Yes The repo identifier.
node Yes The node changeset identifier.
comment_id Yes The comment identifier.
DELETE https://bitbucket.org/api/1.0/repositories/{accountname}/{repo_slug}/changesets/{node}/comments/{comment_id}
  Click here to expand...

POST a new comment on a changeset

Adds a new comment to a changeset node. This call requires authentication. The call can add a new comment or create a comment in reply to another specified by the parent_id parameter. The system creates a comment on behalf of the authenticated caller. The authenticated caller must have administrative or write rights on the repository to POST a new comment.

Private repositories require the caller to authenticate. This call takes the following parameters:

Parameter Required? Description
accountname Yes The team or individual account owning the repo.
repo_slug Yes The repo identifier.
node Yes The node changeset identifier.
content Yes A Striing containing the content of the comment.
line_from No An integer representing the starting line of the comment.
line_to No An integer representing the ending line of the comment.
parent_id No An integer representing the unique ID of comment to which this is a reply.
filename No A String representing a filename in the changeset to which this comment applies.

POST https://bitbucket.org/api/1.0/repositories/{accountname}/{repo_slug}/changesets/{node}/comments
  Click here to expand...

PUT an update to an existing changeset comment

Puts an update to an existing changeset comment identified by the comment_id. This call requires authentication. The system updates a comment on behalf of the authenticated caller. The caller must authenticate as a user with administrative privileges on the account, the repo, or as the user that created the comment. Private repositories require the caller to authenticate. This call takes the following parameters:

Parameter Required? Description
accountname Yes The team or individual account owning the repo.
repo_slug Yes The repo identifier.
node Yes The node changeset identifier.
comment_id Yes The comment identifier.
content Yes A Striing containing the content of the comment.
line_from No An integer representing the starting line of the comment.
line_to No An integer representing the ending line of the comment.
parent_id No An integer representing the unique ID of comment to which this is a reply.
filename No A String representing a filename in the changeset to which this comment applies.
PUT https://bitbucket.org/api/1.0/repositories/{accountname}/{repo_slug}/changesets/{node}/comments/{comment_id
  Click here to expand...

Toggle spam flag on an existing changeset comment

Toggles the spam flag on a changeset comment identified by the comment_id. This call requires authentication. This call takes the following parameters:

Parameter Required? Description
accountname Yes The team or individual account owning the repo.
repo_slug Yes The repo identifier.
node Yes The node changeset identifier.
comment_id Yes The comment identifier.
PUT  https://bitbucket.org/api/1.0/repositories/{accountname}/{repo_slug}/changesets/{node}/comments/spam/{comment_id
  Click here to expand...

Was this helpful?

Thanks for your feedback!

32 Archived comments

  1. User avatar

    Anonymous

    "POST a new comment on a changeset" requires comment_id? Why? What should I put there?

    16 Feb 2013
    1. User avatar

      manthony

      Thank you for the note. You found an error in our doc; The comment_id is not required. The system will set this for you and provide it in the output.

      17 Feb 2013
  2. User avatar

    Cheryl J

    Hi Mary~

    Funny meeting you here. (wink)

    It seems there is a bug with the diffstats call results. I filed an issue for it, but maybe you could poke someone about it?

    ~Cheryl

    01 Mar 2013
    1. User avatar

      manthony

      Hey Cheryl, 

      Erik is faster than light. It is terrifying.

      Good to hear from you.  

      Mary

       

      02 Mar 2013
      1. User avatar

        Cheryl J

        Haha, it's true, he is. Hope you're well! BTW thanks for the nice docs here.

        02 Mar 2013
  3. User avatar

    Maneschi Romain

    Hi,

    Why "changesets" doesn't give a user object like "events" ? Because with an account name, it's difficult to obtain avatar url.

    Anyway, it will be great to add "html_url" in any of your response, to make easier link back to bitbucket.com.

    changesets : bitbucket.com/owner/slug/commits/raw_node

    events : bitbucket.com/owner/slug/... ??

    Thx

    02 Apr 2013
    1. User avatar

      manthony

      You are correct, a link to the user's profile URL would be more helpful. I'm bringing it up to the team.

      02 Apr 2013
      1. User avatar

        Maneschi Romain

        My english is so bad ! I'm sorry for that but i imagined something like this :

        { node: id,
          description: ...,
          user : {
            name : ...
            url_avatar : ...
            url_account : ...
            ... like events.user ...
          }
          url_commit:...
          ....

        }

        Have good day

        03 Apr 2013
  4. User avatar

    Anonymous

    I don't see a way to get a change set by commit hash. Am I right? If there is a call to return this information can you please show me how it is supposed to be requested?

     

    Thanks!

    01 Jul 2013
    1. User avatar

      manthony

      The raw_node ID is pretty an abbreviation of the Hash.  Did you try the get?

      01 Jul 2013
  5. User avatar

    Ville Saalo

    What are all the parts in the get diff response? "gutters", "unified_map", possible values of "type", etc?

    08 Jul 2013
  6. User avatar

    Dillon

    Is there a way to POST a like to a changeset?

    12 Aug 2013
    1. User avatar

      manthony

      Yes, our 2.0 API has that ability. I've updated the page with these APIs.

      12 Aug 2013
      1. User avatar

        Dillon

        Wow, I had no idea there was a 2.0 API. Are there many other 2.0 documented APIs?

        12 Aug 2013
  7. User avatar

    Dillon

    Mary, is there a "particpants" API? Through sluthing I have found this:

    https://bitbucket.org/api/1.0/repositories/{user}/{repo}/changesets/{hash}/participants

    But there's no documentation on it so I'm not sure whether to use it or not.

    12 Aug 2013
    1. User avatar

      manthony

      Dillion,

      Yes, there is.  My apologies, you found an error in the docs. It does appears in the restbrowser.bitbucket.org.  You can also see the list of "publicly available" 2.0 APIs by changing the service there.

      Some REST APIs that you can find by sleuthing our site are not meant for public consumption. That doesn't mean you can't use 'em it just means they change a lot and using them is really risky thing to do in an applciation. So, it is always better to ask as you did today if the method is something you sleuth.

      Cheers,

      Mary

      12 Aug 2013
  8. User avatar

    Richard Simko

    Is there any way to get all commits on a specific branch? Or do I have to traverse the entire history of the repo in order to find that?

    27 Jan 2015
    1. User avatar

      Erik van Zijst [Atlassian]

      Sure, but you'll want to use the 2.0 API. This old 1.0 API is deprecated:

      $ curl https://api.bitbucket.org/2.0/repositories/mirror/linux/commits/master

      The 2.0 commits API mimics most of git-log's DAG traversal operations, as per its documentation.

      27 Jan 2015
      1. User avatar

        Richard Simko

        I see, that wasn't obvious from looking at the API browser, it only said {commit} there for the variable name. Thanks for the info (smile)

        27 Jan 2015
        1. User avatar

          Erik van Zijst [Atlassian]

          In its current shape, the API browser is no substitute for the documentation.

          27 Jan 2015
          1. User avatar

            Richard Simko

            Hello again. This doesn't seem to do what I need. The thing I was looking for was an equivalent of iterating over all change sets using the 1.0 API and comparing the "branch" data. I.e. get all commits performed only on a specific branch, regardless of whether they have been merged or not. As an example, with the following series of commits:

            I need a way to get commits D, E, F and H. I tried ?exclude=master but that only returns H (Which makes sense since D, E and F are all in master as well). I also tried ?include=feature but that still returns older commits made on master. Is there any way to do this without having to traverse all commits individually?

            Also, the 2.0 API doesn't seem to have any way of finding to what branch a commit was made (Something like the branch field of a changeset in 1.0). 
            28 Jan 2015
            1. User avatar

              Erik van Zijst [Atlassian]

              I tried ?exclude=master but that only returns H (Which makes sense since D, E and F are all in master as well). 

              Indeed. What git command would you run locally to get that result?

              29 Jan 2015
              1. User avatar

                Richard Simko

                I would run 

                This gives the last 25 commits in the feature branch regardless of whether they have been merged or not.

                Here's an example from my experiments where the feature branch is called dev-1. dev-1 was merged into master after the second commit. I wrote "dev-1" as the commit message for all commits in order to keep track of where they came from.

                Seems to do about the same thing for Mercurial.

                29 Jan 2015
                1. User avatar

                  Erik van Zijst [Atlassian]

                  I don't think git show-branch --reflog="25" does what you're after.

                  The reflog tracks your local changes to a branch pointer. Typically you might update your local branches one commit at a time, in which case git show-branch --reflog="25" --list feature happens to be equivalent to git log's output, stopping at the original branch point D. However, if some of the commits were pulled in from a remote, your reflog can jump multiple commits at once and so you could for instance see: H, F, D.

                  An other issue with the reflog is that it only exists on your local clone. It's a log of what you have done locally and so it will be different for every developer on the team. The reflog we have on Bitbucket only captures pushes and changes made through the online editor. So it output of your command will be very inconsistent.

                  What you're trying to do is not really possible in Git (it *is* in Mercurial, but more on that later!).

                  Git simply does not know when a branch originally started (the reflog is the only hint but as explained, that's not perfect). It can only show you differences between refs. Everything below F is part of both branches and so there's no way Git can tell that D is special. The fact that it was the original branch point is not retained.

                  In Mercurial the situation is quite different. Branches in Mercurial are very different things. Each commit has a single hardcoded branch label embedded, which is there forever. Therefore D will forever be labeled as being on "feature", even if you later close the branch (contrary to Git, Mercurial branches can never be deleted).

                  Note that the 1.0 changeset API dates back to Bitbucket's Mercurial-only days. It exposes this branch label in the changeset objects. However, these are not reliable on Git. This is why they're no longer present in the current 2.0 commits API.

                  Hope this is helpful.

                  29 Jan 2015
                  1. User avatar

                    Richard Simko

                    Thanks for the reply. I did some additional testing and you're quite right,  show-branch didn't do what I wanted it too. I guess this is more of a VCS issue now, I'm gonna have to do a bit more research.

                    Thanks a lot for the help though! (smile)

                    02 Feb 2015
                    1. User avatar

                      Erik van Zijst [Atlassian]

                      You're welcome!

                      02 Feb 2015
  9. User avatar

    DJ Marcaida

    Toggle spam flag on an existing changeset comment  gives me and error of

    update() got an unexpected keyword argument 'node_or_pull_req_id'.

    What is this about?

    Here's my request if it helps:

    curl -u user:pass -X PUT https://bitbucket.org/api/1.0/repositories/devtoro/zero/changesets/18bc4e0/comments/spam/1718461
    
    {"error": {"message": "update() got an unexpected keyword argument 'node_or_pull_req_id'", "id": "0c24e1f65ee94061b511c7ab3820cf28"}}
    11 Mar 2015
    1. User avatar

      Erik van Zijst [Atlassian]

      That looks like a bug. I've rolled a patch that should go out in the next few days.

      P.S.
      I'm assuming that is not your real password (wink) 

      11 Mar 2015
      1. User avatar

        DJ Marcaida

        It was. (sad)

        12 Mar 2015
      1. User avatar

        DJ Marcaida

        I'd like to mention that the same case is true for the pull requests too.

        pullrequests Resource 1.0#Togglespamflagonanexistingpullrequestcomment

         

        17 Mar 2015
  10. User avatar

    Jesper Christensen

    The example JSON for GET a list of changesets and GET an individual change are not correct. The node property is repeated. The one with the longer SHA should be raw_node.

    07 May 2015
    1. User avatar

      Dan Stevens [Atlassian]

      Thanks for taking time to comment. I'll get a fix in for those examples.

      Happy coding,

      Dan

      07 May 2015
Powered by Confluence and Scroll Viewport