Skip to end of metadata
Go to start of metadata

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:

FieldDescription
nodeUnique ID for the changeset – this is an abbreviated SHA code.
filesAn array of files included in the changeset.
raw_authorThe username defined locally and included in the commit passed to the Bitbucket service.
utctimestampUniversal time stamp applied to the change.
timestampThe time provided on the local machine where the commit occurred.
authorThe Bitbucket account associated with the changeset.
raw_nodeA forty-character changeset hash – this is the unabbreviated SHA value.
parentsThe 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.
branchThe name of the branch on which the change resides. The branch name can be null and is typically so for Git repositories.
messageThe commit message.
revisionAn 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.
sizeThis 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:

ParameterRequired?Description
accountnameYesThe team or individual account owning the repo.
repo_slugYesThe repo identifier.
limitYesAn 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.
startYesA 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:

ParameterRequired?Description
accountnameYesThe team or individual account owning the repo.
repo_slugYesThe repo identifier.
node
YesThe 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:

ParameterRequired?Description
accountnameYesThe team or individual account owning the repo.
repo_slugYesThe repo identifier.
node YesThe 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:

ParameterRequired?Description
accountnameYesThe team or individual account owning the repo.
repo_slugYesThe repo identifier.
node YesThe 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:

ParameterRequired?Description
accountnameYesThe team or individual account owning the repo.
repo_slugYesThe repo identifier.
node YesThe 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:

ParameterRequireDescription
accountnameYesThe team or individual account owning the repo.
repo_slugYesThe repo identifier.
node YesThe node changeset identifier.
comment_idYesThe 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:

ParameterRequired?Description
accountnameYesThe team or individual account owning the repo.
repo_slugYesThe repo identifier.
node YesThe node changeset identifier.
contentYesA Striing containing the content of the comment.
line_fromNoAn integer representing the starting line of the comment.
line_toNoAn integer representing the ending line of the comment.
parent_idNoAn integer representing the unique ID of comment to which this is a reply.
filenameNoA 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:

ParameterRequired?Description
accountnameYesThe team or individual account owning the repo.
repo_slugYesThe repo identifier.
node YesThe node changeset identifier.
comment_idYesThe comment identifier.
contentYesA Striing containing the content of the comment.
line_fromNoAn integer representing the starting line of the comment.
line_toNoAn integer representing the ending line of the comment.
parent_idNoAn integer representing the unique ID of comment to which this is a reply.
filenameNoA 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:

ParameterRequired?Description
accountnameYesThe team or individual account owning the repo.
repo_slugYesThe repo identifier.
nodeYesThe node changeset identifier.
comment_idYesThe comment identifier.
PUT  https://bitbucket.org/api/1.0/repositories/{accountname}/{repo_slug}/changesets/{node}/comments/spam/{comment_id
 Click here to expand...

16 Comments

  1. Anonymous

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

    1. 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.

  2. 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

    1. Hey Cheryl, 

      Erik is faster than light. It is terrifying.

      Good to hear from you.  

      Mary

       

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

  3. 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

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

      1. 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

  4. 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!

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

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

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

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

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

  7. 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.

    1. 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