Returns an object for each repository the caller has explicit access
to and their effective permission — the highest level of permission the
caller has. This does not return public repositories that the user was
not granted any specific permission in, and does not distinguish between
explicit and implicit privileges.

Permissions can be:

• admin
• write
• read

Results may be further filtered or sorted by
repository or permission by adding the following query string
parameters:

• q=repository.name="geordi" or q=permission>"read"
• sort=repository.name

Note that the query parameter values need to be URL escaped so that =
would become %3D.

Search for code in the repositories of the specified team.

Note that searches can match in the file’s text (content_matches),
the path (path_matches), or both.

You can use the same syntax for the search query as in the UI.
E.g. to search for “foo” only within the repository “demo”,
use the query parameter search_query=foo+repo:demo.

Similar to other APIs, you can request more fields using a
fields query parameter. E.g. to get some more information about
the repository of matched files, use the query parameter
search_query=foo&fields=%2Bvalues.file.commit.repository
(the %2B is a URL-encoded +).

Try fields=%2Bvalues.*.*.*.* to get an idea what’s possible.

Search for code in the repositories of the specified user.

Note that searches can match in the file’s text (content_matches),
the path (path_matches), or both.

You can use the same syntax for the search query as in the UI.
E.g. to search for “foo” only within the repository “demo”,
use the query parameter search_query=foo+repo:demo.

Similar to other APIs, you can request more fields using a
fields query parameter. E.g. to get some more information about
the repository of matched files, use the query parameter
search_query=foo&fields=%2Bvalues.file.commit.repository
(the %2B is a URL-encoded +).

Search for code in the repositories of the specified workspace.

Note that searches can match in the file’s text (content_matches),
the path (path_matches), or both.

You can use the same syntax for the search query as in the UI.
E.g. to search for “foo” only within the repository “demo”,
use the query parameter search_query=foo+repo:demo.

Similar to other APIs, you can request more fields using a
fields query parameter. E.g. to get some more information about
the repository of matched files, use the query parameter
search_query=foo&fields=%2Bvalues.file.commit.repository
(the %2B is a URL-encoded +).

Try fields=%2Bvalues.*.*.*.* to get an idea what’s possible.

Returns all snippets. Like pull requests, repositories and workspaces, the
full set of snippets is defined by what the current user has access to.

This includes all snippets owned by any of the workspaces the user is a member of,
or snippets by other users that the current user is either watching or has collaborated
on (for instance by commenting on it).

To limit the set of returned snippets, apply the
?role=[owner|contributor|member] query parameter where the roles are
defined as follows:

• owner: all snippets owned by the current user
• contributor: all snippets owned by, or watched by the current user
• member: created in a workspaces or watched by the current user

When no role is specified, all public snippets are returned, as well as all
privately owned snippets watched or commented on.

The returned response is a normal paginated JSON list. This endpoint
only supports application/json responses and no
multipart/form-data or multipart/related. As a result, it is not
possible to include the file contents.

Creates a new snippet under the authenticated user’s account.

Snippets can contain multiple files. Both text and binary files are
supported.

The simplest way to create a new snippet from a local file:

$ curl -u username:password -X POST https://api.bitbucket.org/2.0/snippets               -F file=@image.png

Creating snippets through curl has a few limitations and so let’s look
at a more complicated scenario.

Snippets are created with a multipart POST. Both multipart/form-data
and multipart/related are supported. Both allow the creation of
snippets with both meta data (title, etc), as well as multiple text
and binary files.

The main difference is that multipart/related can use rich encoding
for the meta data (currently JSON).

multipart/related (RFC-2387)

This is the most advanced and efficient way to create a paste.

POST /2.0/snippets/evzijst HTTP/1.1
Content-Length: 1188
Content-Type: multipart/related; start="snippet"; boundary="===============1438169132528273974=="
MIME-Version: 1.0

--===============1438169132528273974==
Content-Type: application/json; charset="utf-8"
MIME-Version: 1.0
Content-ID: snippet

{
  "title": "My snippet",
  "is_private": true,
  "scm": "git",
  "files": {
      "foo.txt": {},
      "image.png": {}
    }
}

--===============1438169132528273974==
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-ID: "foo.txt"
Content-Disposition: attachment; filename="foo.txt"

foo

--===============1438169132528273974==
Content-Type: image/png
MIME-Version: 1.0
Content-Transfer-Encoding: base64
Content-ID: "image.png"
Content-Disposition: attachment; filename="image.png"

iVBORw0KGgoAAAANSUhEUgAAABQAAAAoCAYAAAD+MdrbAAABD0lEQVR4Ae3VMUoDQRTG8ccUaW2m
TKONFxArJYJamCvkCnZTaa+VnQdJSBFl2SMsLFrEWNjZBZs0JgiL/+KrhhVmJRbCLPx4O+/DT2TB
cbblJxf+UWFVVRNsEGAtgvJxnLm2H+A5RQ93uIl+3632PZyl/skjfOn9Gvdwmlcw5aPUwimG+NT5
EnNN036IaZePUuIcK533NVfal7/5yjWeot2z9ta1cAczHEf7I+3J0ws9Cgx0fsOFpmlfwKcWPuBQ
73Oc4FHzBaZ8llq4q1mr5B2mOUCt815qYR8eB1hG2VJ7j35q4RofaH7IG+Xrf/PfJhfmwtfFYoIN
AqxFUD6OMxcvkO+UfKfkOyXfKdsv/AYCHMLVkHAFWgAAAABJRU5ErkJggg==
--===============1438169132528273974==--

The request contains multiple parts and is structured as follows.

The first part is the JSON document that describes the snippet’s
properties or meta data. It either has to be the first part, or the
request’s Content-Type header must contain the start parameter to
point to it.

The remaining parts are the files of which there can be zero or more.
Each file part should contain the Content-ID MIME header through
which the JSON meta data’s files element addresses it. The value
should be the name of the file.

Content-Disposition is an optional MIME header. The header’s
optional filename parameter can be used to specify the file name
that Bitbucket should use when writing the file to disk. When present,
filename takes precedence over the value of Content-ID.

When the JSON body omits the files element, the remaining parts are
not ignored. Instead, each file is added to the new snippet as if its
name was explicitly linked (the use of the files elements is
mandatory for some operations like deleting or renaming files).

multipart/form-data

The use of JSON for the snippet’s meta data is optional. Meta data can
also be supplied as regular form fields in a more conventional
multipart/form-data request:

$ curl -X POST -u credentials https://api.bitbucket.org/2.0/snippets               -F title="My snippet"               -F file=@foo.txt -F file=@image.png

POST /2.0/snippets HTTP/1.1
Content-Length: 951
Content-Type: multipart/form-data; boundary=----------------------------63a4b224c59f

------------------------------63a4b224c59f
Content-Disposition: form-data; name="file"; filename="foo.txt"
Content-Type: text/plain

foo

------------------------------63a4b224c59f
Content-Disposition: form-data; name="file"; filename="image.png"
Content-Type: application/octet-stream

?PNG

IHDR?1??I.....
------------------------------63a4b224c59f
Content-Disposition: form-data; name="title"

My snippet
------------------------------63a4b224c59f--

Here the meta data properties are included as flat, top-level form
fields. The file attachments use the file field name. To attach
multiple files, simply repeat the field.

The advantage of multipart/form-data over multipart/related is
that it can be easier to build clients.

Essentially all properties are optional, title and files included.

Sharing and Visibility

Snippets can be either public (visible to anyone on Bitbucket, as well
as anonymous users), or private (visible only to members of the workspace).
This is controlled through the snippet’s is_private element:

• is_private=false – everyone, including anonymous users can view
  the snippet
• is_private=true – only workspace members can view the snippet

To create the snippet under a workspace, just append the workspace ID
to the URL. See /2.0/snippets/{workspace}.

Identical to /snippets, except that the result is further filtered
by the snippet owner and only those that are owned by {workspace} are
returned.

Identical to /snippets, except that the new snippet will be
created under the workspace specified in the path parameter
{workspace}.

Deletes a snippet and returns an empty response.

Retrieves a single snippet.

Snippets support multiple content types:

• application/json
• multipart/related
• multipart/form-data

application/json

The default content type of the response is application/json.
Since JSON is always utf-8, it cannot reliably contain file contents
for files that are not text. Therefore, JSON snippet documents only
contain the filename and links to the file contents.

This means that in order to retrieve all parts of a snippet, N+1
requests need to be made (where N is the number of files in the
snippet).

multipart/related

To retrieve an entire snippet in a single response, use the
Accept: multipart/related HTTP request header.

$ curl -H "Accept: multipart/related" https://api.bitbucket.org/2.0/snippets/evzijst/1

Response:

HTTP/1.1 200 OK
Content-Length: 2214
Content-Type: multipart/related; start="snippet"; boundary="===============1438169132528273974=="
MIME-Version: 1.0

--===============1438169132528273974==
Content-Type: application/json; charset="utf-8"
MIME-Version: 1.0
Content-ID: snippet

{
  "links": {
    "self": {
      "href": "https://api.bitbucket.org/2.0/snippets/evzijst/kypj"
    },
    "html": {
      "href": "https://bitbucket.org/snippets/evzijst/kypj"
    },
    "comments": {
      "href": "https://api.bitbucket.org/2.0/snippets/evzijst/kypj/comments"
    },
    "watchers": {
      "href": "https://api.bitbucket.org/2.0/snippets/evzijst/kypj/watchers"
    },
    "commits": {
      "href": "https://api.bitbucket.org/2.0/snippets/evzijst/kypj/commits"
    }
  },
  "id": kypj,
  "title": "My snippet",
  "created_on": "2014-12-29T22:22:04.790331+00:00",
  "updated_on": "2014-12-29T22:22:04.790331+00:00",
  "is_private": false,
  "files": {
    "foo.txt": {
      "links": {
        "self": {
          "href": "https://api.bitbucket.org/2.0/snippets/evzijst/kypj/files/367ab19/foo.txt"
        },
        "html": {
          "href": "https://bitbucket.org/snippets/evzijst/kypj#file-foo.txt"
        }
      }
    },
    "image.png": {
      "links": {
        "self": {
          "href": "https://api.bitbucket.org/2.0/snippets/evzijst/kypj/files/367ab19/image.png"
        },
        "html": {
          "href": "https://bitbucket.org/snippets/evzijst/kypj#file-image.png"
        }
      }
    }
  ],
  "owner": {
    "username": "evzijst",
    "nickname": "evzijst",
    "display_name": "Erik van Zijst",
    "uuid": "{d301aafa-d676-4ee0-88be-962be7417567}",
    "links": {
      "self": {
        "href": "https://api.bitbucket.org/2.0/users/evzijst"
      },
      "html": {
        "href": "https://bitbucket.org/evzijst"
      },
      "avatar": {
        "href": "https://bitbucket-staging-assetroot.s3.amazonaws.com/c/photos/2013/Jul/31/erik-avatar-725122544-0_avatar.png"
      }
    }
  },
  "creator": {
    "username": "evzijst",
    "nickname": "evzijst",
    "display_name": "Erik van Zijst",
    "uuid": "{d301aafa-d676-4ee0-88be-962be7417567}",
    "links": {
      "self": {
        "href": "https://api.bitbucket.org/2.0/users/evzijst"
      },
      "html": {
        "href": "https://bitbucket.org/evzijst"
      },
      "avatar": {
        "href": "https://bitbucket-staging-assetroot.s3.amazonaws.com/c/photos/2013/Jul/31/erik-avatar-725122544-0_avatar.png"
      }
    }
  }
}

--===============1438169132528273974==
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-ID: "foo.txt"
Content-Disposition: attachment; filename="foo.txt"

foo

--===============1438169132528273974==
Content-Type: image/png
MIME-Version: 1.0
Content-Transfer-Encoding: base64
Content-ID: "image.png"
Content-Disposition: attachment; filename="image.png"

iVBORw0KGgoAAAANSUhEUgAAABQAAAAoCAYAAAD+MdrbAAABD0lEQVR4Ae3VMUoDQRTG8ccUaW2m
TKONFxArJYJamCvkCnZTaa+VnQdJSBFl2SMsLFrEWNjZBZs0JgiL/+KrhhVmJRbCLPx4O+/DT2TB
cbblJxf+UWFVVRNsEGAtgvJxnLm2H+A5RQ93uIl+3632PZyl/skjfOn9Gvdwmlcw5aPUwimG+NT5
EnNN036IaZePUuIcK533NVfal7/5yjWeot2z9ta1cAczHEf7I+3J0ws9Cgx0fsOFpmlfwKcWPuBQ
73Oc4FHzBaZ8llq4q1mr5B2mOUCt815qYR8eB1hG2VJ7j35q4RofaH7IG+Xrf/PfJhfmwtfFYoIN
AqxFUD6OMxcvkO+UfKfkOyXfKdsv/AYCHMLVkHAFWgAAAABJRU5ErkJggg==
--===============1438169132528273974==--

multipart/form-data

As with creating new snippets, multipart/form-data can be used as an
alternative to multipart/related. However, the inherently flat
structure of form-data means that only basic, root-level properties
can be returned, while nested elements like links are omitted:

$ curl -H "Accept: multipart/form-data" https://api.bitbucket.org/2.0/snippets/evzijst/kypj

Response:

HTTP/1.1 200 OK
Content-Length: 951
Content-Type: multipart/form-data; boundary=----------------------------63a4b224c59f

------------------------------63a4b224c59f
Content-Disposition: form-data; name="title"
Content-Type: text/plain; charset="utf-8"

My snippet
------------------------------63a4b224c59f--
Content-Disposition: attachment; name="file"; filename="foo.txt"
Content-Type: text/plain

foo

------------------------------63a4b224c59f
Content-Disposition: attachment; name="file"; filename="image.png"
Content-Transfer-Encoding: base64
Content-Type: application/octet-stream

iVBORw0KGgoAAAANSUhEUgAAABQAAAAoCAYAAAD+MdrbAAABD0lEQVR4Ae3VMUoDQRTG8ccUaW2m
TKONFxArJYJamCvkCnZTaa+VnQdJSBFl2SMsLFrEWNjZBZs0JgiL/+KrhhVmJRbCLPx4O+/DT2TB
cbblJxf+UWFVVRNsEGAtgvJxnLm2H+A5RQ93uIl+3632PZyl/skjfOn9Gvdwmlcw5aPUwimG+NT5
EnNN036IaZePUuIcK533NVfal7/5yjWeot2z9ta1cAczHEf7I+3J0ws9Cgx0fsOFpmlfwKcWPuBQ
73Oc4FHzBaZ8llq4q1mr5B2mOUCt815qYR8eB1hG2VJ7j35q4RofaH7IG+Xrf/PfJhfmwtfFYoIN
AqxFUD6OMxcvkO+UfKfkOyXfKdsv/AYCHMLVkHAFWgAAAABJRU5ErkJggg==
------------------------------5957323a6b76--

Used to update a snippet. Use this to add and delete files and to
change a snippet’s title.

To update a snippet, one can either PUT a full snapshot, or only the
parts that need to be changed.

The contract for PUT on this API is that properties missing from the
request remain untouched so that snippets can be efficiently
manipulated with differential payloads.

To delete a property (e.g. the title, or a file), include its name in
the request, but omit its value (use null).

As in Git, explicit renaming of files is not supported. Instead, to
rename a file, delete it and add it again under another name. This can
be done atomically in a single request. Rename detection is left to
the SCM.

PUT supports three different content types for both request and
response bodies:

• application/json
• multipart/related
• multipart/form-data

The content type used for the request body can be different than that
used for the response. Content types are specified using standard HTTP
headers.

Use the Content-Type and Accept headers to select the desired
request and response format.

application/json

As with creation and retrieval, the content type determines what
properties can be manipulated. application/json does not support
file contents and is therefore limited to a snippet’s meta data.

To update the title, without changing any of its files:

$ curl -X POST -H "Content-Type: application/json" https://api.bitbucket.org/2.0/snippets/evzijst/kypj             -d '{"title": "Updated title"}'

To delete the title:

$ curl -X POST -H "Content-Type: application/json" https://api.bitbucket.org/2.0/snippets/evzijst/kypj             -d '{"title": null}'

Not all parts of a snippet can be manipulated. The owner and creator
for instance are immutable.

multipart/related

multipart/related can be used to manipulate all of a snippet’s
properties. The body is identical to a POST. properties omitted from
the request are left unchanged. Since the start part contains JSON,
the mechanism for manipulating the snippet’s meta data is identical
to application/json requests.

To update one of a snippet’s file contents, while also changing its
title:

PUT /2.0/snippets/evzijst/kypj HTTP/1.1
Content-Length: 288
Content-Type: multipart/related; start="snippet"; boundary="===============1438169132528273974=="
MIME-Version: 1.0

--===============1438169132528273974==
Content-Type: application/json; charset="utf-8"
MIME-Version: 1.0
Content-ID: snippet

{
  "title": "My updated snippet",
  "files": {
      "foo.txt": {}
    }
}

--===============1438169132528273974==
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-ID: "foo.txt"
Content-Disposition: attachment; filename="foo.txt"

Updated file contents.

--===============1438169132528273974==--

Here only the parts that are changed are included in the body. The
other files remain untouched.

Note the use of the files list in the JSON part. This list contains
the files that are being manipulated. This list should have
corresponding multiparts in the request that contain the new contents
of these files.

If a filename in the files list does not have a corresponding part,
it will be deleted from the snippet, as shown below:

PUT /2.0/snippets/evzijst/kypj HTTP/1.1
Content-Length: 188
Content-Type: multipart/related; start="snippet"; boundary="===============1438169132528273974=="
MIME-Version: 1.0

--===============1438169132528273974==
Content-Type: application/json; charset="utf-8"
MIME-Version: 1.0
Content-ID: snippet

{
  "files": {
    "image.png": {}
  }
}

--===============1438169132528273974==--

To simulate a rename, delete a file and add the same file under
another name:

PUT /2.0/snippets/evzijst/kypj HTTP/1.1
Content-Length: 212
Content-Type: multipart/related; start="snippet"; boundary="===============1438169132528273974=="
MIME-Version: 1.0

--===============1438169132528273974==
Content-Type: application/json; charset="utf-8"
MIME-Version: 1.0
Content-ID: snippet

{
    "files": {
      "foo.txt": {},
      "bar.txt": {}
    }
}

--===============1438169132528273974==
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-ID: "bar.txt"
Content-Disposition: attachment; filename="bar.txt"

foo

--===============1438169132528273974==--

multipart/form-data

Again, one can also use multipart/form-data to manipulate file
contents and meta data atomically.

$ curl -X PUT http://localhost:12345/2.0/snippets/evzijst/kypj             -F title="My updated snippet" -F file=@foo.txt

PUT /2.0/snippets/evzijst/kypj HTTP/1.1
Content-Length: 351
Content-Type: multipart/form-data; boundary=----------------------------63a4b224c59f

------------------------------63a4b224c59f
Content-Disposition: form-data; name="file"; filename="foo.txt"
Content-Type: text/plain

foo

------------------------------63a4b224c59f
Content-Disposition: form-data; name="title"

My updated snippet
------------------------------63a4b224c59f

To delete a file, omit its contents while including its name in the
files field:

$ curl -X PUT https://api.bitbucket.org/2.0/snippets/evzijst/kypj -F files=image.png

PUT /2.0/snippets/evzijst/kypj HTTP/1.1
Content-Length: 149
Content-Type: multipart/form-data; boundary=----------------------------ef8871065a86

------------------------------ef8871065a86
Content-Disposition: form-data; name="files"

image.png
------------------------------ef8871065a86--

The explicit use of the files element in multipart/related and
multipart/form-data is only required when deleting files.
The default mode of operation is for file parts to be processed,
regardless of whether or not they are listed in files, as a
convenience to the client.

Used to retrieve a paginated list of all comments for a specific
snippet.

This resource works identical to commit and pull request comments.

The default sorting is oldest to newest and can be overridden with
the sort query parameter.

Creates a new comment.

The only required field in the body is content.raw.

To create a threaded reply to an existing comment, include parent.id.

Deletes a snippet comment.

Comments can only be removed by the comment author, snippet creator, or workspace admin.

Returns the specific snippet comment.

Updates a comment.

The only required field in the body is content.raw.

Comments can only be updated by their author.

Returns the changes (commits) made on this snippet.

Returns the changes made on this snippet in this commit.

Convenience resource for getting to a snippet’s raw files without the
need for first having to retrieve the snippet itself and having to pull
out the versioned file links.

Used to stop watching a specific snippet. Returns 204 (No Content)
to indicate success.

Used to check if the current user is watching a specific snippet.

Returns 204 (No Content) if the user is watching the snippet and 404 if
not.

Hitting this endpoint anonymously always returns a 404.

Used to start watching a specific snippet. Returns 204 (No Content).

Deletes the snippet.

Note that this only works for versioned URLs that point to the latest
commit of the snippet. Pointing to an older commit results in a 405
status code.

To delete a snippet, regardless of whether or not concurrent changes
are being made to it, use DELETE /snippets/{encoded_id} instead.

Identical to GET /snippets/encoded_id, except that this endpoint
can be used to retrieve the contents of the snippet as it was at an
older revision, while /snippets/encoded_id always returns the
snippet’s current revision.

Note that only the snippet’s file contents are versioned, not its
meta data properties like the title.

Other than that, the two endpoints are identical in behavior.

Identical to UPDATE /snippets/encoded_id, except that this endpoint
takes an explicit commit revision. Only the snippet’s “HEAD”/”tip”
(most recent) version can be updated and requests on all other,
older revisions fail by returning a 405 status.

Usage of this endpoint over the unrestricted /snippets/encoded_id
could be desired if the caller wants to be sure no concurrent
modifications have taken place between the moment of the UPDATE
request and the original GET.

This can be considered a so-called “Compare And Swap”, or CAS
operation.

Other than that, the two endpoints are identical in behavior.

Retrieves the raw contents of a specific file in the snippet. The
Content-Disposition header will be “attachment” to avoid issues with
malevolent executable files.

The file’s mime type is derived from its filename and returned in the
Content-Type header.

Note that for text files, no character encoding is included as part of
the content type.

Returns the diff of the specified commit against its first parent.

Note that this resource is different in functionality from the patch
resource.

The differences between a diff and a patch are:

• patches have a commit header with the username, message, etc
• diffs support the optional path=foo/bar.py query param to filter the
  diff to just that one file diff (not supported for patches)
• for a merge, the diff will show the diff between the merge commit and
  its first parent (identical to how PRs work), while patch returns a
  response containing separate patches for each commit on the second
  parent’s ancestry, up to the oldest common ancestor (identical to
  its reachability).

Note that the character encoding of the contents of the diff is
unspecified as Git does not track this, making it hard for
Bitbucket to reliably determine this.

Returns the patch of the specified commit against its first
parent.

Note that this resource is different in functionality from the diff
resource.

The differences between a diff and a patch are:

• patches have a commit header with the username, message, etc
• diffs support the optional path=foo/bar.py query param to filter the
  diff to just that one file diff (not supported for patches)
• for a merge, the diff will show the diff between the merge commit and
  its first parent (identical to how PRs work), while patch returns a
  response containing separate patches for each commit on the second
  parent’s ancestry, up to the oldest common ancestor (identical to
  its reachability).

Note that the character encoding of the contents of the patch is
unspecified as Git does not track this, making it hard for
Bitbucket to reliably determine this.

Returns a paginated list of commits that modified the specified file.

Commits are returned in reverse chronological order. This is roughly
equivalent to the following commands:

$ git log --follow --date-order <sha> <path>

By default, Bitbucket will follow renames and the path name in the
returned entries reflects that. This can be turned off using the
?renames=false query parameter.

Results are returned in descending chronological order by default, and
like most endpoints you can
filter and sort the response to
only provide exactly the data you want.

The example response returns commits made before 2011-05-18 against a file
named README.rst. The results are filtered to only return the path and
date. This request can be made using:

$ curl 'https://api.bitbucket.org/2.0/repositories/evzijst/dogslow/filehistory/master/README.rst'\
  '?fields=values.next,values.path,values.commit.date&q=commit.date<=2011-05-18'

In the response you can see that the file was renamed to README.rst
by the commit made on 2011-05-16, and was previously named README.txt.

This endpoint redirects the client to the directory listing of the
root directory on the main branch.

This is equivalent to directly hitting
/2.0/repositories/{username}/{repo_slug}/src/{commit}/{path}
without having to know the name or SHA1 of the repo’s main branch.

To create new commits, POST to this endpoint

This endpoint is used to create new commits in the repository by
uploading files.

To add a new file to a repository:

$ curl https://api.bitbucket.org/2.0/repositories/username/slug/src \
  -F /repo/path/to/image.png=@image.png

This will create a new commit on top of the main branch, inheriting the
contents of the main branch, but adding (or overwriting) the
image.png file to the repository in the /repo/path/to directory.

To create a commit that deletes files, use the files parameter:

$ curl https://api.bitbucket.org/2.0/repositories/username/slug/src \
  -F files=/file/to/delete/1.txt \
  -F files=/file/to/delete/2.txt

You can add/modify/delete multiple files in a request. Rename/move a
file by deleting the old path and adding the content at the new path.

This endpoint accepts multipart/form-data (as in the examples above),
as well as application/x-www-form-urlencoded.

Note: multipart/form-data is currently not supported by Forge apps
for this API.

multipart/form-data

A multipart/form-data post contains a series of “form fields” that
identify both the individual files that are being uploaded, as well as
additional, optional meta data.

Files are uploaded in file form fields (those that have a
Content-Disposition parameter) whose field names point to the remote
path in the repository where the file should be stored. Path field
names are always interpreted to be absolute from the root of the
repository, regardless whether the client uses a leading slash (as the
above curl example did).

File contents are treated as bytes and are not decoded as text.

The commit message, as well as other non-file meta data for the
request, is sent along as normal form field elements. Meta data fields
share the same namespace as the file objects. For multipart/form-data
bodies that should not lead to any ambiguity, as the
Content-Disposition header will contain the filename parameter to
distinguish between a file named “message” and the commit message field.

application/x-www-form-urlencoded

It is also possible to upload new files using a simple
application/x-www-form-urlencoded POST. This can be convenient when
uploading pure text files:

$ curl https://api.bitbucket.org/2.0/repositories/atlassian/bbql/src \
  --data-urlencode "/path/to/me.txt=Lorem ipsum." \
  --data-urlencode "message=Initial commit" \
  --data-urlencode "author=Erik van Zijst <erik.van.zijst@gmail.com>"

There could be a field name clash if a client were to upload a file
named “message”, as this filename clashes with the meta data property
for the commit message. To avoid this and to upload files whose names
clash with the meta data properties, use a leading slash for the files,
e.g. curl --data-urlencode "/message=file contents".

When an explicit slash is omitted for a file whose path matches that of
a meta data parameter, then it is interpreted as meta data, not as a
file.

Executables and links

While this API aims to facilitate the most common use cases, it is
possible to perform some more advanced operations like creating a new
symlink in the repository, or creating an executable file.

Files can be supplied with a x-attributes value in the
Content-Disposition header. For example, to upload an executable
file, as well as create a symlink from README.txt to README:

--===============1438169132528273974==
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-ID: "bin/shutdown.sh"
Content-Disposition: attachment; filename="shutdown.sh"; x-attributes:"executable"

#!/bin/sh
halt

--===============1438169132528273974==
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-ID: "/README.txt"
Content-Disposition: attachment; filename="README.txt"; x-attributes:"link"

README
--===============1438169132528273974==--

Links are files that contain the target path and have
x-attributes:"link" set.

When overwriting links with files, or vice versa, the newly uploaded
file determines both the new contents, as well as the attributes. That
means uploading a file without specifying x-attributes="link" will
create a regular file, even if the parent commit hosted a symlink at
the same path.

The same applies to executables. When modifying an existing executable
file, the form-data file element must include
x-attributes="executable" in order to preserve the executable status
of the file.

Note that this API does not support the creation or manipulation of
subrepos / submodules.

This endpoints is used to retrieve the contents of a single file,
or the contents of a directory at a specified revision.

Raw file contents

When path points to a file, this endpoint returns the raw contents.
The response’s Content-Type is derived from the filename
extension (not from the contents). The file contents are not processed
and no character encoding/recoding is performed and as a result no
character encoding is included as part of the Content-Type.

The Content-Disposition header will be “attachment” to prevent
browsers from running executable files.

If the file is managed by LFS, then a 301 redirect pointing to
Atlassian’s media services platform is returned.

The response includes an ETag that is based on the contents of the file
and its attributes. This means that an empty __init__.py always
returns the same ETag, regardless on the directory it lives in, or the
commit it is on.

File meta data

When the request for a file path includes the query parameter
?format=meta, instead of returning the file’s raw contents, Bitbucket
instead returns the JSON object describing the file’s properties:

$ curl https://api.bitbucket.org/2.0/repositories/atlassian/bbql/src/eefd5ef/tests/__init__.py?format=meta
{
  "links": {
    "self": {
      "href": "https://api.bitbucket.org/2.0/repositories/atlassian/bbql/src/eefd5ef5d3df01aed629f650959d6706d54cd335/tests/__init__.py"
    },
    "meta": {
      "href": "https://api.bitbucket.org/2.0/repositories/atlassian/bbql/src/eefd5ef5d3df01aed629f650959d6706d54cd335/tests/__init__.py?format=meta"
    }
  },
  "path": "tests/__init__.py",
  "commit": {
    "type": "commit",
    "hash": "eefd5ef5d3df01aed629f650959d6706d54cd335",
    "links": {
      "self": {
        "href": "https://api.bitbucket.org/2.0/repositories/atlassian/bbql/commit/eefd5ef5d3df01aed629f650959d6706d54cd335"
      },
      "html": {
        "href": "https://bitbucket.org/atlassian/bbql/commits/eefd5ef5d3df01aed629f650959d6706d54cd335"
      }
    }
  },
  "attributes": [],
  "type": "commit_file",
  "size": 0
}

File objects contain an attributes element that contains a list of
possible modifiers. Currently defined values are:

• link – indicates that the entry is a symbolic link. The contents
  of the file represent the path the link points to.
• executable – indicates that the file has the executable bit set.
• subrepository – indicates that the entry points to a submodule or
  subrepo. The contents of the file is the SHA1 of the repository
  pointed to.
• binary – indicates whether Bitbucket thinks the file is binary.

This endpoint can provide an alternative to how a HEAD request can be
used to check for the existence of a file, or a file’s size without
incurring the overhead of receiving its full contents.

Directory listings

When path points to a directory instead of a file, the response is a
paginated list of directory and file objects in the same order as the
underlying SCM system would return them.

For example:

$ curl https://api.bitbucket.org/2.0/repositories/atlassian/bbql/src/eefd5ef/tests
{
  "pagelen": 10,
  "values": [
    {
      "path": "tests/test_project",
      "type": "commit_directory",
      "links": {
        "self": {
          "href": "https://api.bitbucket.org/2.0/repositories/atlassian/bbql/src/eefd5ef5d3df01aed629f650959d6706d54cd335/tests/test_project/"
        },
        "meta": {
          "href": "https://api.bitbucket.org/2.0/repositories/atlassian/bbql/src/eefd5ef5d3df01aed629f650959d6706d54cd335/tests/test_project/?format=meta"
        }
      },
      "commit": {
        "type": "commit",
        "hash": "eefd5ef5d3df01aed629f650959d6706d54cd335",
        "links": {
          "self": {
            "href": "https://api.bitbucket.org/2.0/repositories/atlassian/bbql/commit/eefd5ef5d3df01aed629f650959d6706d54cd335"
          },
          "html": {
            "href": "https://bitbucket.org/atlassian/bbql/commits/eefd5ef5d3df01aed629f650959d6706d54cd335"
          }
        }
      }
    },
    {
      "links": {
        "self": {
          "href": "https://api.bitbucket.org/2.0/repositories/atlassian/bbql/src/eefd5ef5d3df01aed629f650959d6706d54cd335/tests/__init__.py"
        },
        "meta": {
          "href": "https://api.bitbucket.org/2.0/repositories/atlassian/bbql/src/eefd5ef5d3df01aed629f650959d6706d54cd335/tests/__init__.py?format=meta"
        }
      },
      "path": "tests/__init__.py",
      "commit": {
        "type": "commit",
        "hash": "eefd5ef5d3df01aed629f650959d6706d54cd335",
        "links": {
          "self": {
            "href": "https://api.bitbucket.org/2.0/repositories/atlassian/bbql/commit/eefd5ef5d3df01aed629f650959d6706d54cd335"
          },
          "html": {
            "href": "https://bitbucket.org/atlassian/bbql/commits/eefd5ef5d3df01aed629f650959d6706d54cd335"
          }
        }
      },
      "attributes": [],
      "type": "commit_file",
      "size": 0
    }
  ],
  "page": 1,
  "size": 2
}

When listing the contents of the repo’s root directory, the use of a
trailing slash at the end of the URL is required.

The response by default is not recursive, meaning that only the direct contents of
a path are returned. The response does not recurse down into
subdirectories. In order to “walk” the entire directory tree, the
client can either parse each response and follow the self links of each
commit_directory object, or can specify a max_depth to recurse to.

The max_depth parameter will do a breadth-first search to return the contents of the subdirectories
up to the depth specified. Breadth-first search was chosen as it leads to the least amount of
file system operations for git. If the max_depth parameter is specified to be too
large, the call will time out and return a 555.

Each returned object is either a commit_file, or a commit_directory,
both of which contain a path element. This path is the absolute path
from the root of the repository. Each object also contains a commit
object which embeds the commit the file is on. Note that this is merely
the commit that was used in the URL. It is not the commit that last
modified the file.

Directory objects have 2 representations. Their self link returns the
paginated contents of the directory. The meta link on the other hand
returns the actual directory object itself, e.g.:

{
  "path": "tests/test_project",
  "type": "commit_directory",
  "links": {
    "self": {
      "href": "https://api.bitbucket.org/2.0/repositories/atlassian/bbql/src/eefd5ef5d3df01aed629f650959d6706d54cd335/tests/test_project/"
    },
    "meta": {
      "href": "https://api.bitbucket.org/2.0/repositories/atlassian/bbql/src/eefd5ef5d3df01aed629f650959d6706d54cd335/tests/test_project/?format=meta"
    }
  },
  "commit": { ... }
}

Querying, filtering and sorting

Like most API endpoints, this API supports the Bitbucket
querying/filtering syntax and so you could filter a directory listing
to only include entries that match certain criteria. For instance, to
list all binary files over 1kb use the expression:

size > 1024 and attributes = "binary"

which after urlencoding yields the query string:

?q=size%3E1024+and+attributes%3D%22binary%22

To change the ordering of the response, use the ?sort parameter:

.../src/eefd5ef/?sort=-size

See filtering and sorting for more
details.

Returns a paginated list of the user’s SSH public keys.

Adds a new SSH public key to the specified user account and returns the resulting key.

Example:

$ curl -X POST -H "Content-Type: application/json" -d '{"key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIKqP3Cr632C2dNhhgKVcon4ldUSAeKiku2yP9O9/bDtY user@myhost"}' https://api.bitbucket.org/2.0/users/{ed08f5e1-605b-4f4a-aee4-6c97628a673e}/ssh-keys

Deletes a specific SSH public key from a user’s account.

Returns a specific SSH public key belonging to a user.

Updates a specific SSH public key on a user’s account

Note: Only the ‘comment’ field can be updated using this API. To modify the key or comment values, you must delete and add the key again.

Example:

$ curl -X PUT -H "Content-Type: application/json" -d '{"label": "Work key"}' https://api.bitbucket.org/2.0/users/{ed08f5e1-605b-4f4a-aee4-6c97628a673e}/ssh-keys/{b15b6026-9c02-4626-b4ad-b905f99f763a}

Returns the currently logged in user.

Returns all the authenticated user’s email addresses. Both
confirmed and unconfirmed.

Returns details about a specific one of the authenticated user’s
email addresses.

Details describe whether the address has been confirmed by the user and
whether it is the user’s primary address or not.

Gets the public information associated with a user account.

If the user’s profile is private, location, website and
created_on elements are omitted.

Note that the user object returned by this operation is changing significantly, due to privacy changes.
See the announcement for details.

Returns the webhook resource or subject types on which webhooks can
be registered.

Each resource/subject type contains an events link that returns the
paginated list of specific events each individual subject type can
emit.

This endpoint is publicly accessible and does not require
authentication or scopes.

Returns a paginated list of all valid webhook events for the
specified entity.
The team and user webhooks are deprecated, and you should use workspace instead.
For more information, see the announcement.

This is public data that does not require any scopes or authentication.

NOTE: The example response is a truncated response object for the workspace subject_type.
We return the same structure for the other subject_type objects.

Returns an object for each workspace the caller is a member of, and
their effective role - the highest level of privilege the caller has.
If a user is a member of multiple groups with distinct roles, only the
highest level is returned.

Permissions can be:

• owner
• collaborator
• member

The collaborator role is being removed from the Bitbucket Cloud API. For more information,
see the deprecation announcement.

When you move your administration from Bitbucket Cloud to admin.atlassian.com, the following fields on
workspace_membership will no longer be present: last_accessed and added_on. See the
deprecation announcement.

Results may be further filtered or sorted by
workspace or permission by adding the following query string parameters:

• q=workspace.slug="bbworkspace1" or q=permission="owner"
• sort=workspace.slug

Note that the query parameter values need to be URL escaped so that =
would become %3D.

Returns a list of workspaces accessible by the authenticated user.

Results may be further filtered or sorted by
workspace or permission by adding the following query string parameters:

• q=slug="bbworkspace1" or q=is_private=true
• sort=created_on

Note that the query parameter values need to be URL escaped so that =
would become %3D.

The collaborator role is being removed from the Bitbucket Cloud API. For more information,
see the deprecation announcement.

Returns the requested workspace.

Returns a paginated list of webhooks installed on this workspace.

Creates a new webhook on the specified workspace.

Workspace webhooks are fired for events from all repositories contained
by that workspace.

Example:

$ curl -X POST -u credentials -H 'Content-Type: application/json'
  https://api.bitbucket.org/2.0/workspaces/my-workspace/hooks
  -d '
    {
      "description": "Webhook Description",
      "url": "https://example.com/",
      "active": true,
      "secret": "this is a really bad secret",
      "events": [
        "repo:push",
        "issue:created",
        "issue:updated"
      ]
    }'

When the secret is provided it will be used as the key to generate a HMAC
digest value sent in the X-Hub-Signature header at delivery time. Passing
a null or empty secret or not passing a secret will leave the webhook’s
secret unset. Bitbucket only generates the X-Hub-Signature when the webhook’s
secret is set.

This call requires the webhook scope, as well as any scope
that applies to the events that the webhook subscribes to. In the
example above that means: webhook, repository and issue.

The url must properly resolve and cannot be an internal, non-routed address.

Only workspace owners can install webhooks on workspaces.

Deletes the specified webhook subscription from the given workspace.

Returns the webhook with the specified id installed on the given
workspace.