How do I PUT (update) a file using browse of REST api?

In the documentation for bitbucket server REST API,

It shows the ability to PUT or update a file in the repo. It also references a branch parameter, but how do specify that in the url or http query parameters ? I presume the update file goes in as a json data stream like what GET returns ?


1 Like

Apologies for the unclear REST documentation. We are working on making it more user friendly. This resource accepts PUT multipart form data, containing the file in a form-field named ‘content’. An example curl request to update ‘’ would be:

curl -X PUT -u username:password -F -F message=curl -F branch=master -F sourceCommitId=5636641a50b

  • branch: the branch on which the path should be modified or created
  • content: the full content of the file
  • message: the message associated with this change, to be used as the commit message
  • sourceCommitId: the commit ID of the file before it was edited or null if this is a new file

Justin Thomas
Bitbucket Server

1 Like

Thank you for the clarification. I was able to use the multipart content type to submit new files into the bitbucket repo. However, when I try to update an existing file, an error shows up:

curl -XPUT … -F sourceCommitId=xxxxx …
“message”:"‘definition/foo’ could not be created because it already exists. A previous commit ID must be provided when editing an existing file to prevent concurrent modifications.",

I provided the commit ID from the latest commit on the branch for sourceCommitId.

Is the parameter “sourceCommitId” incorrect labeled ?

The documentation says that if the commit ID is null, then it is expecting to store a new file, which is like the behavior I am seeing, ie the REST agent can’t find the commit ID from multiform content, and assigning it null, and then expects the file to be new.


Operator Error. I used “ID” vs “Id”.
I think I got it working now. The command format provided by Justin is correct.


Hi @jthomas,

I’m also trying to PUT some files to my repository but something wrong in my cURL request , I couldn’t find that. Please see the Raw file URL of the file I want to PUT{userName}/{repositoryName}/raw/36caf07a207f4793ca915447fcece3672f3b9c98/

And here is the cURL request I’m trying

curl -X PUT -u {username}:{password} -F -F message=curl -F branch=master -F sourceCommitId={lastCommitId}{userName}/repos/{repositoryName}/browse/src/

I’m not sure whether I’m using correct syntax , Please correct me if anything wrong.
I’m confused with the documentations.And I’m stuck on this.

Please help me as soon as possible.

Sanooj M

Hi @sanooj.m,

The documentation in this thread is for Bitbucket Server, not They have different APIs.{username}/{repo_slug}/src#post is probably the endpoint you want

1 Like

It’s still unclear how to add a brand new file.

“sourceCommitId: the commit ID of the file before it was edited, used to identify if content has changed. Or null if this is a new file”

Do you mean a text string of “null”, or “” or should the attribute be missing entirely?