Skip to content
forgit api docs

Update a snippet

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

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.

Authorizations

Section titled “ Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “ Path Parameters ”
encoded_id
required
string

The snippet id.

workspace
required
string

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

Responses

Section titled “ Responses ”

200

Section titled “ 200 ”

The updated snippet object.

object
type
required
string
id
integer
title
string
scm

The DVCS used to store the snippet.

string
Allowed values: git
created_on
string format: date-time
updated_on
string format: date-time
owner
object
type
required
string
links
Account Links

Links related to an Account.

object
avatar
Link

A link to a resource related to this object.

object
href
string format: uri
name
string
key
additional properties
any
created_on
string format: date-time
display_name
string
uuid
string
creator
object
type
required
string
links
Account Links

Links related to an Account.

object
avatar
Link

A link to a resource related to this object.

object
href
string format: uri
name
string
key
additional properties
any
created_on
string format: date-time
display_name
string
uuid
string
is_private
boolean
Example 
{
  "scm": "git"
}

401

Section titled “ 401 ”

If the snippet is private and the request was not authenticated.

Error

Base type for most resource objects. It defines the common type element that identifies an object’s type. It also identifies the element as Swagger’s discriminator.

object
type
required
string
error
object
message
required
string
detail
string
data

Optional structured data that is endpoint-specific.

object
key
additional properties
any
key
additional properties
any
Example generated 
{
  "type": "example",
  "error": {
    "message": "example",
    "detail": "example",
    "data": {}
  }
}

403

Section titled “ 403 ”

If authenticated user does not have permission to update the private snippet.

Error

Base type for most resource objects. It defines the common type element that identifies an object’s type. It also identifies the element as Swagger’s discriminator.

object
type
required
string
error
object
message
required
string
detail
string
data

Optional structured data that is endpoint-specific.

object
key
additional properties
any
key
additional properties
any
Example generated 
{
  "type": "example",
  "error": {
    "message": "example",
    "detail": "example",
    "data": {}
  }
}

404

Section titled “ 404 ”

If the snippet does not exist.

Error

Base type for most resource objects. It defines the common type element that identifies an object’s type. It also identifies the element as Swagger’s discriminator.

object
type
required
string
error
object
message
required
string
detail
string
data

Optional structured data that is endpoint-specific.

object
key
additional properties
any
key
additional properties
any
Example generated 
{
  "type": "example",
  "error": {
    "message": "example",
    "detail": "example",
    "data": {}
  }
}