---
title: "Update a snippet"
method: PUT
path: "/snippets/{workspace}/{encoded_id}"
tags: ["Snippets"]
---

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

## Response `200`

The updated snippet object.

- Snippet — A snippet object.
  - `type` string, required
  - `id` integer
  - `title` string
  - `scm` 'git' — The DVCS used to store the snippet.
  - `created_on` string, date-time
  - `updated_on` string, date-time
  - `owner` Account — An account object.
    - `type` string, required
    - `links` AccountLinks — Links related to an Account.
      - `avatar` Link — A link to a resource related to this object.
        - `href` string, uri
        - `name` string
    - `created_on` string, date-time
    - `display_name` string
    - `uuid` string
  - `creator` Account — An account object.
    - `type` string, required
    - `links` AccountLinks — Links related to an Account.
      - `avatar` Link — A link to a resource related to this object.
        - `href` string, uri
        - `name` string
    - `created_on` string, date-time
    - `display_name` string
    - `uuid` string
  - `is_private` boolean

## Other responses

- `401` — If the snippet is private and the request was not authenticated.
- `403` — If authenticated user does not have permission to update the private snippet.
- `404` — If the snippet does not exist.

---

[API](https://skmtc.net/bitbucket/apis/bitbucket-api.md) · [All operations](https://skmtc.net/bitbucket/apis/bitbucket-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/bitbucket/bitbucket-api/versions/7e9be973015d/schema)