The Bitbucket Cloud REST API

Snippets

Snippets allow you share code segments or files with yourself, members of your workspace, or the world.

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

List snippets

GET /2.0/snippets

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.

OAuth 2.0 scopes required:

snippet

Request

Query parameters

role

string

Filter down the result based on the authenticated user's role (owner, contributor, or member).

Valid values: owner, contributor, member

Example

cURL

Node.js

Java

Python

PHP

curl --request GET \
  --url 'https://api.bitbucket.org/2.0/snippets' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

Responses

200

404

A paginated list of snippets.

Content type	Value
application/json	Paginated Snippets

Create a snippet

POST /2.0/snippets

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:

1
2
$ 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).

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

1
2
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:

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

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

OAuth 2.0 scopes required:

snippet:write

Request

Body parameters

Content type	Value
application/json	allOf [object, Snippet]

Example

cURL

Node.js

Java

Python

PHP

curl --request POST \
  --url 'https://api.bitbucket.org/2.0/snippets' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "<string>",
  "id": 2154,
  "title": "<string>",
  "scm": "git",
  "created_on": "<string>",
  "updated_on": "<string>",
  "owner": {
    "type": "<string>"
  },
  "creator": {
    "type": "<string>"
  },
  "is_private": true
}'

Responses

201

401

The newly created snippet object.

Content type	Value
application/json	allOf [object, Snippet]

Header Parameters

Location

string

The URL of the newly created snippet.

List snippets in a workspace

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

OAuth 2.0 scopes required:

snippet

Request

Path parameters

workspace Required

string

This can either be the workspace ID (slug) or the workspace UUID surrounded by curly-braces, for example: {workspace UUID}.

Query parameters

role

string

Filter down the result based on the authenticated user's role (owner, contributor, or member).

Valid values: owner, contributor, member

Example

cURL

Node.js

Java

Python

PHP

curl --request GET \
  --url 'https://api.bitbucket.org/2.0/snippets/{workspace}' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

Responses

200

404

A paginated list of snippets.

Content type	Value
application/json	Paginated Snippets

Create a snippet for a workspace

POST /2.0/snippets/{workspace}

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

OAuth 2.0 scopes required:

snippet:write

Request

Path parameters

workspace Required

string

This can either be the workspace ID (slug) or the workspace UUID surrounded by curly-braces, for example: {workspace UUID}.

Body parameters

Content type	Value
application/json	allOf [object, Snippet]

Example

cURL

Node.js

Java

Python

PHP

curl --request POST \
  --url 'https://api.bitbucket.org/2.0/snippets/{workspace}' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "<string>",
  "id": 2154,
  "title": "<string>",
  "scm": "git",
  "created_on": "<string>",
  "updated_on": "<string>",
  "owner": {
    "type": "<string>"
  },
  "creator": {
    "type": "<string>"
  },
  "is_private": true
}'

Responses

201

401

403

The newly created snippet object.

Content type	Value
application/json	allOf [object, Snippet]

Header Parameters

Location

string

The URL of the newly created snippet.

Get a snippet

GET /2.0/snippets/{workspace}/{encoded_id}

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

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

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

Response:

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