Rate this page:
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).
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 usercontributor
: all snippets owned by, or watched by the current usermember
: created in a workspaces or watched by the current userWhen 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.
snippet
string
Filter down the result based on the authenticated user's role (owner
, contributor
, or member
).
Valid values: owner
, contributor
, member
1 2 3 4
curl --request GET \
--url 'https://api.bitbucket.org/2.0/snippets' \
--header 'Authorization: Bearer <access_token>' \
--header 'Accept: application/json'
A paginated list of snippets.
Content type | Value |
---|---|
application/json |
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 2POST /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).
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:
To create the snippet under a workspace, just append the workspace ID
to the URL. See /2.0/snippets/{workspace}
.
snippet:write
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
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
}'
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.
snippet
string
This can either be the workspace ID (slug) or the workspace UUID
surrounded by curly-braces, for example: {workspace UUID}
.
string
Filter down the result based on the authenticated user's role (owner
, contributor
, or member
).
Valid values: owner
, contributor
, member
1 2 3 4
curl --request GET \
--url 'https://api.bitbucket.org/2.0/snippets/{workspace}' \
--header 'Authorization: Bearer <access_token>' \
--header 'Accept: application/json'
A paginated list of snippets.
Content type | Value |
---|---|
application/json |
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}
.
snippet:write
string
This can either be the workspace ID (slug) or the workspace UUID
surrounded by curly-braces, for example: {workspace UUID}
.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
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
}'
GET /2.0/snippets/{workspace}/{encoded_id}
Retrieves a single snippet.
Snippets support multiple content types:
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 2HTTP/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==--
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:
1 2$ curl -H "Accept: multipart/form-data" https://api.bitbucket.org/2.0/snippets/evzijst/kypj
Response:
1 2HTTP/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--
snippet
string
The snippet id.
string
This can either be the workspace ID (slug) or the workspace UUID
surrounded by curly-braces, for example: {workspace UUID}
.
1 2 3 4
curl --request GET \
--url 'https://api.bitbucket.org/2.0/snippets/{workspace}/{encoded_id}' \
--header 'Authorization: Bearer <access_token>' \
--header 'Accept: application/json'
PUT /2.0/snippets/{workspace}/{encoded_id}
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.
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:
1 2$ 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:
1 2$ 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
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:
1 2PUT /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:
1 2PUT /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:
1 2PUT /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==--