How can I push a JSON to a branch as a new or updated file via an API call?
Asked by Cameron:

I've looked into the documentation a bit but I have had mixed results with no direct success.   

<https://developer.atlassian.com/bitbucket/api/2/reference/resource/repositories/%7Bworkspace%7D/%7Brepo_slug%7D/src#post>

I simply want to be able to do a POST call and update or add a file to a branch.  

The file will be a raw JSON example below.

<br />

<br />

{  
"TestFile": "Test"  
}

How do I name this file?   

How can I update an existing file like this.   

is there any better documentation for something like this?

Thanks in advance!


Answers:
author: Theodora Boudale
body: Hi Cameron and welcome to the community.

If you have a file named e.g. *File1.json* , and you want to create a commit and add it to the repo at the root directory of the repo, at a branch named e.g. *test-branch*, you can do it with a curl command like below:

```
curl -X POST -u username:app-password https://api.bitbucket.org/2.0/repositories/<workspace-id>/<repo-slug>/src -F File1.json=@File1.json -F branch=test-branch -F message="my commit message"
```

The command needs to be executed at the directory where File1.json exists.

You can name the file however you wish. If you want the file to have a different name in the repo than your local, e.g. File2.json, you can alter the above command as follows:

```
curl -X POST -u username:app-password https://api.bitbucket.org/2.0/repositories/<workspace-id>/<repo-slug>/src -F File2.json=@File1.json -F branch=test-branch -F message="my commit message"
```

You can update the file with the same command. If a file exists with the same name in the repo, its contents will get modified.

Are you able to do this with a command like above? If there are any issues, could you add the **-v** parameter in the command and paste both the command you use and the output here so we can take a look?

++**Please make sure**++ to remove the line that starts with **\> Authorization:** from the output before you share it, as it includes credential info, and also remove the actual password from the command before you post it here. You may also remove the workspace-id, repo name and username if you don't want them public.

Kind regards,  
Theodora

comments: author: Cameron
body: Hey Theodora - Thank you for your reply!

When I attempt to use the API you provide with UN/PW or a Bearer token I get 401's Errors.   

Either saying that my Token has expired or a 401 with no other context.  

The token is newly created so I don't think that's the issue with that or the credentials.   

I am using a Company Instance of Bitbucket... does anything change with that usage?

Here's a sample curl.

curl --location --request POST '[https://api.bitbucket.org/2.0/repositories/\<REPO\>/\<SLUG]()\>' \\--form 'File1.json=@File1.json' \\--form 'branch=\<testBranch\>' \\--form 'message=testCommit'

Here's another one using the API format that worked with our companies bitbucket instance.

curl --location --request POST 'https://bitbucket.es.ad.\<domain_Name\>.com/rest/api/1.0/projects/\<WORKSPACE_ID\>/repos/\<slug\>' \\--form 'File1.json={"test":"test}' \\--form 'branch=\<BRANCH\>' \\--form 'message=testCommit'


author: Cameron
body: Hey Theodora - Thank you for your reply!

When I attempt to use the API you provide with UN/PW or a Bearer token I get 401's Errors.   

Either saying that my Token has expired or a 401 with no other context.  

The token is newly created so I don't think that's the issue with that or the credentials.   

I am using a Company Instance of Bitbucket... does anything change with that usage?

Here's a sample curl.

curl --location --request POST '[https://api.bitbucket.org/2.0/repositories/\<REPO\>/\<SLUG]()\>' \\--form 'File1.json=@File1.json' \\--form 'branch=\<testBranch\>' \\--form 'message=testCommit'

Here's another one using the API format that worked with our companies bitbucket instance.

curl --location --request POST \<domain_Name\>.com/rest/api/1.0/projects/\<WORKSPACE_ID\>/repos/\<slug\>' \\--form 'File1.json={"test":"test}' \\--form 'branch=\<BRANCH\>' \\--form 'message=testCommit'


author: Theodora Boudale
body: Hi [@Cameron](/t5/user/viewprofilepage/user-id/4233166) ,

Thank you for the info.

A 401 error indicates an issue with authentication. A few things I suggest that you check (I believe we show a 403 error in these cases instead of 401, but it's worth checking anyway):

* Are there any branch permissions in this repo, preventing you from pushing to this branch?
* Is your company using "Require two-step verification" in the workspace, and is 2FA perhaps disabled for your account?
* Does your company use IP white-listing for this workspace, and are you executing the API call from a machine with an IP that is not whitelisted?  

> I am using a Company Instance of Bitbucket... does anything change with that usage?

Does your company use SAML? Do you get redirected to your company's SSO when you log in to Bitbucket website?

If so, this explains the issue with the password. In this case, the account's password won't work for authentication, and you'll need to use an app-password instead:

* <https://support.atlassian.com/bitbucket-cloud/docs/app-passwords/>

When you generate it, make sure that the app-password has at least write access to repositories.

If you don't use SSO for login, I would suggest

* double checking that you can log in to Bitbucket website with the password you're using in the API call
* double check if you can push to the same repo with the same credentials from command line
* try requesting a password reset email via <https://id.atlassian.com/login/resetpassword> and see if you can authenticate with the new password
* try for testing purposes also an app-password and see if this works

For OAuth, can you check if the OAuth consumer has at least write access to repositories?

One additional note, the URL in the curl call should be:

```
https://api.bitbucket.org/2.0/repositories/<workspace-id>/<repo-slug>/src
```

The example one you posted has \<REPO\> instead of \<workspace-id\> and is missing the /src part in the end, not sure if you accidentally removed it from the URL after copy-pasting it here?

Kind regards,  
Theodora


author: Cameron
body: Thanks for your quick reply Theodora!  

I think the SSO issue may be the overall issue here.   

I've read the instructions for creating an app password but i don't see the options in my account settings.   

"see the screenshot below "  

...![Screen Shot 2021-02-03 at 4.28.58 PM.png](https://community.atlassian.com/t5/image/serverpage/image-id/128720i298B3F43AA5976B0/image-size/large?v=v2&px=999 "Screen Shot 2021-02-03 at 4.28.58 PM.png")  

Also a quick side note.   

The one time I got the Pull-request API to work, the API path had 1.0 instead of 2.0  

Is this a versioning issue?

Best Regards :)   

- Cameron


author: Theodora Boudale
body: Hi Cameron,

Thank you for the info.

Your screenshot looks like it's from a Bitbucket Server account (in a self-hosted instance). I think I misunderstood your previous comment ("I am using a Company Instance of Bitbucket..."), I thought you meant it was a Cloud instance with a domain claimed by your company.

Just to make things clear, your company is using Bitbucket Server (self-hosted instance, on your own servers) instead of Bitbucket Cloud (hosted in <https://bitbucket.org/>), is that correct?

If so, then this is indeed the culprit. The two products have differences and they also have a different API. The API endpoint we've been talking about concerns Bitbucket Cloud only.

The documentation for Bitbucket Server API can be found here:

* <https://docs.atlassian.com/bitbucket-server/rest/7.10.0/bitbucket-rest.html>

The endpoint that can be used for creating a new commit (either for updating or creating a new file) can be found here and also includes an example:

* <https://docs.atlassian.com/bitbucket-server/rest/7.10.0/bitbucket-rest.html#idp218>

Could you give this a try and let me know if it works for you?

Apologies for the misunderstanding and the confusion on this.

Kind regards,  
Theodora


author: Cameron
body: Thank you so much for this!

This was the actual issue was with the service.   

I really appreciate the consistent help you provided.


author: Theodora Boudale
body: You are very welcome! I'm glad we figured this out!


Tags: bitbucket-server