Is there any API to make a commit? (BB-9954)

Issue #8672 resolved
created an issue

Is there any API to make a commit? I mean some way to send a repo a diff using rest api to apply it on the top of some branch.

Official response

Comments (149)

  1. Marcus Bertrand staff
    • changed status to open

    We've actually created one for online editing but it is undocumented. We'll keep this issue open for the day we will add this to the 2.0 API. You can discover how it works by watching the requests to the Online Editor. However, we will certainly change the behavior of this API and we wouldn't recommend using it at this time except for experimental purposes.

  2. Juha Kuitunen

    I'm speaking on behalf of Bitbeaker (open source Bitbucket client for Android). Every now and then users are requesting support for making a commit and it would be nice to someday be able to make that possible. So, big + to commit API! :)

  3. Marcus Zanona

    After some testing using the internal file editor as @Marcus Bertrand recommended, I got to this point which may help a few of you :)

    //JSON Request Payload:
        "branch": "master",
        "files": [
                "path": "",
                "content": "Instructions Here"
                "path": "",
                "content": "#New file here"
        "message": "Update README and File content",
        "parents": ["7b3f851d7864ba958656de64bbbc1e82ae1b49fd"],
        "repository": {"full_name": "user/repo"},
        "timestamp": "2014-11-19T09:20:05.338Z",
        "transient": false


    • branch field not declared creates a "None" branch
    • parents field requires only one commit_id
    • repository field doesn't seem to be necessary
    • timestamp field doesn't seem to be necessary
    • transient field omitted is the same as false, while true, creates a hidden branch (apparently with the name of the commit_id)

    I still missed a functionality where I can define the encoding type of a file like utf-8 or base64 so we can also add binaries or images. Hopefully this is something that is on their roadmap.

    The really great thing about this API which I think it should definitely stay when it is publicly released is possibility to add multiple files to a commit by having a files parameters as an array. On both Github or Gitlab, it is necessary through their API to do a lot of work before making this happen.

    So, awesome job there Bitbucket :D

  4. Chris Rose

    +1 for this, could use it in POEditor, would greatly simplify our workflow if we could have external tools update assets in a repository and use that to kick off a CI process

  5. Jakub Korál

    So you actually can use that online-editor endpoint - as mentioned in

    It works with a header Authorization: Bearer xyz_your_Oauth2_token retrieved previously.

    Please just remember that you'd need to use refresh_token after an hour, so be ready. If you receive 403 with message "Access token expired. Use your refresh token to obtain a new access token" - and then use the refresh_token to obtain new access_token, try to repeat your action and be happy.

    As long as I send heads (from last branch commit), creating a new-file / updating existing file works with oecommits (internal) endpoint.

    Acquiring latest heads is easy thanks to and iterating through {"branches":[]} Array.

    But still - there are options: Either make the endpoint available publicly, or make a new and fresh one. This 2 years old-issue should be a no-brainer to finish.

    Can't be a production dependency... :-(

  6. anentropic

    I don't think so, it's just that services like Apiary have asked users to vote on this issue because users are asking them for a feature which can't be implemented without BitBucket support

  7. Joshua Perry

    With this issue languishing and all the painful workarounds required in the wiki in conjunction with github's recent reasonable pricing restructure and the fantastic new features (including a GraphQL API), I no longer see a reason to postpone migrating our projects.

  8. Antonio Piraino

    +1 for Bitbucket support for PoEditor

    We need to use POeditor API to get the files, download them, create a branch on BB using git (no API), add files, commit, push. Nice :-)

    If I sell such a client I may end up up being able to pay for college tuition for my kids LOL

  9. Alastair Wilkes staff

    Hi everyone,

    We're working on this.

    To set expectations a bit: with this API we're trying to make the simple, common task (i.e. modify the contents of a repo) very straightforward, while still making some of the more complex things possible. In other words, we're not aiming to completely reproduce Git in a REST API.

    Stay tuned for more info!

    Bitbucket PM

  10. Amruta

    @Alastair Wilkes Can you please direct me to some links where I could find some examples to use this commit api?

    I read the documentation about commit on the API page, but when I tried, I couldn't get it to work.

    Any example would be helpful.

  11. Eric Henry staff

    Hi everyone,

    Please check out the documentation here:{username}/{repo_slug}/src#post

    If you have would like to report feedback or a bug with the new endpoint, please file a new issue with the component API to avoid spamming the many watchers on this issue. If you have any questions about how to use the commit API, feel free to post them on the Atlassian Community or in the Bitbucket Integrators HipChat room.



    Development Team Lead

  12. Erik van Zijst

    It looks like we forgot to document the branch parameter. @Gabriel Titerlea already discovered it and it is there. I've created PR that adds it. Until that time, here's the missing fragment:

    The name of the branch that the new commit should be created on. When
    omitted, the commit will be created on top of the main branch and will become
    the main branch's new HEAD/tip.
    When a branch name is provided that already exists in the repo, then the
    commit will be created on top of that branch. In this case, *if* a parent
    SHA1 was also provided, then it is asserted that the parent is the branch's
    tip/HEAD at the time the request is made. When this is not the case, a 409
    is returned.
    This API cannot be used to create new anonymous heads in Mercurial repos.
    When a new branch name is specified (that does not already exist in the
    repo), and no parent SHA1s are provided, then the new commit will inherit
    from the current main branch's tip/HEAD commit, but not advance the main
    branch. The new commit will be the new branch. When the request *also*
    specifies a parent SHA1, then the new commit and branch branch are created
    directly on top of the parent commit, regardless of the state of the main
    When a branch name is not specified, but a parent SHA1 is provided, then
    Bitbucket asserts that it represents the main branch's current HEAD/tip, or
    a 409 is returned.
    When a branch name is not specified and the repo is empty, the new commit
    will become the repo's root commit and will be on the main branch.
    When a branch name is specified and the repo is empty, the new commit will
    become the repo's root commit and also define the repo's main branch going
    This API cannot be used to create additional root commits in non-empty
    The branch field cannot be repeated.
    As a side effect, this API can be used to create a new branch without
    modifying any files, by specifying a new branch name in this field,
    together with `parents`, but omitting the `files` fields, while not sending
    any files. This will create a new commit and branch with the same contents as
    the first parent. The diff of this commit against its first parent will be
  13. Log in to comment