Snippets for Bitbucket Server Overview

If you're looking for the Snippets for Confluence documentation, it can be found here.

Snippets

The Snippets plugin provides a simple way to create and share code snippets in Bitbucket Server. The plugin allows you to create code snippets and optionally make them available to other users. You can also discover snippets created by other users and add them to your starred snippets collection.

Feature Highlights

Store your code snippets in Bitbucket Server
Share your code snippets with other users
Discover snippets created by other users
Star snippets to add them to your own starred snippets collection
Simply embed snippets on any website or in Confluence by using our free Snippets for Confluence add-on

Screenshots

How it works

Access your snippets by using the snippets menu in the header of Bitbucket. You can create new snippets directly from the menu or by clicking the create button in the snippets overview. Specify a name and an optional description, which supports Markdown syntax. You can categorize your snippet by assigning one or more categories. Enter new categories separated by commas. You can also control the visibility and accessibility of your snippet:

Visibility	Choose whether your snippet should be visible to all Bitbucket users in the browse section of the snippets overview.
Accessibility	Choose whether your snippet should be accessible for external users you share the snippet URL with.
Permissions	Choose whether certain groups or users have permissions to view your snippets.

Note: If you want to prevent users from making their snippets accessible for external users they share the URL with, Bitbucket administrators can globally disable the option to make individual snippets public in the plugin configuration located under:

Bitbucket Administration > Add-ons > Snippets configuration

A snippet consists of one or more files. Add as many files as you want by clicking the add file button at the bottom of the form or by simply using drag & drop in modern browsers. The syntax highlighting of your snippet code is automatically detected by the ending of the file name.

Markdown files are being rendered directly when viewing a snippet, if the file name has one of the following extensions: .md, .markdown, .mdown, .mkdn or .mkd. Learn more about the supported syntax in the Markdown Syntax Guide.

After you have created your snippet, you can share it with other users by copying the snippet link displayed in the right sidebar of the snippet. Once other users know the URL of your snippet, they can share it as well, add a comment or star it for later use. By starring a snippet, the snippet will be available in your own starred snippets collection. You can also download a snippet with all files as a zip file or view the raw file directly in your browser.

It's even possible to embed a snippet on an external website, on Confluence pages and blogposts by using our free Snippets add-on for Confluence or on a page published in Bitbucket with our Pages add-on by simply using the embed code displayed in the right sidebar of the snippet. And if you only want to embed a single file of the snippet, just add the filename with the file parameter ?file={filename} to the url used in the embed code. Permissions are always inherited from the snippet itself. If you want to embed a snippet on a public website, you need to make the snippet accessible for external users first. Otherwise only logged-in Bitbucket Server users will be able to view the embedded snippet.

Finally you can discover more snippets of other users in the browse snippets section or on the user's profile page.

Get snippets of current user

GET http://{host}:{port}/{context}/rest/snippets/1.0/snippets

Example Request

curl -u username:password -H "Content-Type:application/json" http://bitbucket.example.com/rest/snippets/1.0/snippets

Example Response

{
  "size": 1,
  "limit": 25,
  "isLastPage": true,
  "values": [{
    "guid": "87dec410f4404d4ca43dc4772a8bd0f0",
    "name": "Example Snippet",
    "description": "Example description...",
    "categories": [{
      "guid": "2f7c939e273f4d29b60f08f9a508298a",
      "name": "Example Category"
    }],
    "isVisible": true,
    "isPublic": false,
    "userId": 1,
    "createdAt": 1379175213548,
    "updatedAt": 1379175745710,
    "files": [{
      "guid": "bda2ce737fce4cc19ba00cafc5c9f33d",
      "name": "example.sql",
      "content": "SELECT * FROM examples"
    }],
    "comments": [{
        "guid": "6b90147977bb42f782610f0211a94cfc",
        "text": "This is a comment...",
        "userId": 1,
        "createdAt": 1431174442000,
        "updatedAt": 1431174442000
    }]
  }],
  "start": 0
}

Get starred snippets of current user

GET http://{host}:{port}/{context}/rest/snippets/1.0/snippets/starred

Example Request

curl -u username:password -H "Content-Type:application/json" http://bitbucket.example.com/rest/snippets/1.0/snippets/starred

Example Response

{
  "size": 1,
  "limit": 25,
  "isLastPage": true,
  "values": [{
    "snippet": {
      "guid": "87dec410f4404d4ca43dc4772a8bd0f0",
      "name": "Example Snippet",
      "description": "Example description...",
      "categories": [{
        "guid": "2f7c939e273f4d29b60f08f9a508298a",
        "name": "Example Category"
      }],
      "isVisible": true,
      "isPublic": false,
      "userId": 1,
      "createdAt": 1379175213548,
      "updatedAt": 1379175745710,
      "files": [{
        "guid": "bda2ce737fce4cc19ba00cafc5c9f33d",
        "name": "example.sql",
        "content": "SELECT * FROM examples"
      }],
      "comments": [{
          "guid": "6b90147977bb42f782610f0211a94cfc",
          "text": "This is a comment...",
          "userId": 1,
          "createdAt": 1431174442000,
          "updatedAt": 1431174442000
      }]
    },
    "userId": 1,
    "starredAt": 1379177521715
  }],
  "start": 0
}

Browse snippets

GET http://{host}:{port}/{context}/rest/snippets/1.0/snippets/browse

Example Request

curl -u username:password -H "Content-Type:application/json" http://bitbucket.example.com/rest/snippets/1.0/snippets/browse

Example Response

{
  "size": 1,
  "limit": 25,
  "isLastPage": true,
  "values": [{
    "guid": "87dec410f4404d4ca43dc4772a8bd0f0",
    "name": "Example Snippet",
    "description": "Example description...",
    "categories": [{
      "guid": "2f7c939e273f4d29b60f08f9a508298a",
      "name": "Example Category"
    }],
    "isVisible": true,
    "isPublic": false,
    "userId": 1,
    "createdAt": 1379175213548,
    "updatedAt": 1379175745710,
    "files":[{
      "guid": "bda2ce737fce4cc19ba00cafc5c9f33d",
      "name": "example.sql",
      "content": "SELECT * FROM examples"
    }],
    "comments": [{
        "guid": "6b90147977bb42f782610f0211a94cfc",
        "text": "This is a comment...",
        "userId": 1,
        "createdAt": 1431174442000,
        "updatedAt": 1431174442000
    }]
  }],
  "start": 0
}

Browse snippets of user

GET http://{host}:{port}/{context}/rest/snippets/1.0/snippets/browse?username={username}

Example Request

curl -u username:password -H "Content-Type:application/json" http://bitbucket.example.com/rest/snippets/1.0/snippets/browse?username=johndoe

Example Response

{
  "size": 1,
  "limit": 25,
  "isLastPage": true,
  "values": [{
    "guid": "87dec410f4404d4ca43dc4772a8bd0f0",
    "name": "Example Snippet",
    "description": "Example description...",
    "categories": [{
      "guid": "2f7c939e273f4d29b60f08f9a508298a",
      "name": "Example Category"
    }],
    "isVisible": true,
    "isPublic": false,
    "userId": 1,
    "createdAt": 1379175213548,
    "updatedAt": 1379175745710,
    "files":[{
      "guid": "bda2ce737fce4cc19ba00cafc5c9f33d",
      "name": "example.sql",
      "content": "SELECT * FROM examples"
    }],
    "comments": [{
        "guid": "6b90147977bb42f782610f0211a94cfc",
        "text": "This is a comment...",
        "userId": 1,
        "createdAt": 1431174442000,
        "updatedAt": 1431174442000
    }]
  }],
  "start": 0
}

Get snippets of category

GET http://{host}:{port}/{context}/rest/snippets/1.0/snippets/categories/{guid}

Example Request

curl -u username:password -H "Content-Type:application/json" http://bitbucket.example.com/rest/snippets/1.0/snippets/categories/2f7c939e273f4d29b60f08f9a508298a

Example Response

{
  "size": 1,
  "limit": 25,
  "isLastPage": true,
  "values": [{
    "snippet": {
      "guid": "87dec410f4404d4ca43dc4772a8bd0f0",
      "name": "Example Snippet",
      "description": "Example description...",
      "categories": [{
        "guid": "2f7c939e273f4d29b60f08f9a508298a",
        "name": "Example Category"
      }],
      "isVisible": true,
      "isPublic": false,
      "userId": 1,
      "createdAt": 1379175213548,
      "updatedAt": 1379175745710,
      "files": [{
        "guid": "bda2ce737fce4cc19ba00cafc5c9f33d",
        "name": "example.sql",
        "content": "SELECT * FROM examples"
      }],
      "comments": [{
          "guid": "6b90147977bb42f782610f0211a94cfc",
          "text": "This is a comment...",
          "userId": 1,
          "createdAt": 1431174442000,
          "updatedAt": 1431174442000
      }]
    },
    "userId": 1,
    "starredAt": 1379177521715
  }],
  "start": 0
}

Get snippet by GUID

GET http://{host}:{port}/{context}/rest/snippets/1.0/snippets/{guid}

Example Request

curl -u username:password -H "Content-Type:application/json" http://bitbucket.example.com/rest/snippets/1.0/snippets/87dec410f4404d4ca43dc4772a8bd0f0

Example Response

{
  "guid": "87dec410f4404d4ca43dc4772a8bd0f0",
  "name": "Example Snippet",
  "description": "Example description...",
  "categories": [{
    "guid": "2f7c939e273f4d29b60f08f9a508298a",
    "name": "Example Category"
  }],
  "isVisible": true,
  "isPublic": false,
  "userId": 1,
  "createdAt": 1379175213548,
  "updatedAt": 1379175745710,
  "files": [{
    "guid": "bda2ce737fce4cc19ba00cafc5c9f33d",
    "name": "example.sql",
    "content": "SELECT * FROM examples"
  }],
  "comments": [{
      "guid": "6b90147977bb42f782610f0211a94cfc",
      "text": "This is a comment...",
      "userId": 1,
      "createdAt": 1431174442000,
      "updatedAt": 1431174442000
  }]
}

Get comment by GUID

GET http://{host}:{port}/{context}/rest/snippets/1.0/snippets/{snippetGuid}/comments/{commentGuid}

Example Request

curl -u username:password -H "Content-Type:application/json" http://bitbucket.example.com/rest/snippets/1.0/snippets/87dec410f4404d4ca43dc4772a8bd0f0/comments/6b90147977bb42f782610f0211a94cfc

Example Response

{
  "guid": "6b90147977bb42f782610f0211a94cfc",
  "text": "This is a comment...",
  "userId": 1,
  "createdAt": 1431174442000,
  "updatedAt": 1431174442000
}

Create snippet

POST http://{host}:{port}/{context}/rest/snippets/1.0/snippets

Example Request

curl -X POST -u username:password -H "Content-Type:application/json" -d '{ "name" : "Example Snippet", "files" : [{ "name" : "example.sql", "content" : "SELECT * FROM examples" }] }' http://bitbucket.example.com/rest/snippets/1.0/snippets

Example Response

{
  "guid": "87dec410f4404d4ca43dc4772a8bd0f0",
  "name": "Example Snippet",
  "categories": [],
  "isVisible": true,
  "isPublic": false,
  "userId": 1,
  "createdAt": 1379175213548,
  "updatedAt": 1379175745710,
  "files": [{
    "guid": "bda2ce737fce4cc19ba00cafc5c9f33d",
    "name": "example.sql",
    "content": "SELECT * FROM examples"
  }],
  "comments": []
}

Create comment

POST http://{host}:{port}/{context}/rest/snippets/1.0/snippets/{guid}/comments

Example Request

curl -X POST -u username:password -H "Content-Type:application/json" -d '{ "text" : "This is a comment..." }' http://bitbucket.example.com/rest/snippets/1.0/snippets/87dec410f4404d4ca43dc4772a8bd0f0/comments

Example Response

{
  "guid": "6b90147977bb42f782610f0211a94cfc",
  "text": "This is a comment...",
  "userId": 1,
  "createdAt": 1431174442000,
  "updatedAt": 1431174442000
}

Update snippet

PUT http://{host}:{port}/{context}/rest/snippets/1.0/snippets/{guid}

Example Request

curl -X PUT -u username:password -H "Content-Type:application/json" -d '{ "name" : "Example Snippet", "description" : "Example description...", "categories" : [ "Example Category" ], "files" : [{ "name" : "example.sql", "content" : "SELECT * FROM examples" }] }' http://bitbucket.example.com/rest/snippets/1.0/snippets/87dec410f4404d4ca43dc4772a8bd0f0

Example Response

{
  "guid": "87dec410f4404d4ca43dc4772a8bd0f0",
  "name": "Example Snippet",
  "description": "Example description...",
  "categories": [{
    "guid": "2f7c939e273f4d29b60f08f9a508298a",
    "name": "Example Category"
  }],
  "isVisible": true,
  "isPublic": false,
  "userId": 1,
  "createdAt": 1379175213548,
  "updatedAt": 1379180600230,
  "files": [{
    "guid": "0c7e081403ba49b4a4c0113d2d9933a5",
    "name": "example.sql",
    "content": "SELECT * FROM examples"
  }],
  "comments": []
}

Update comment

PUT http://{host}:{port}/{context}/rest/snippets/1.0/snippets/{snippetGuid}/comments/{commentGuid}

Example Request

curl -X PUT -u username:password -H "Content-Type:application/json" -d '{ "text" : "This is another comment..." }' http://bitbucket.example.com/rest/snippets/1.0/snippets/87dec410f4404d4ca43dc4772a8bd0f0/comments/6b90147977bb42f782610f0211a94cfc

Example Response

{
  "guid": "6b90147977bb42f782610f0211a94cfc",
  "text": "This is a comment...",
  "userId": 1,
  "createdAt": 1431174442000,
  "updatedAt": 1431176876101
}

Delete snippet

DELETE http://{host}:{port}/{context}/rest/snippets/1.0/snippets/{guid}

Example Request

curl -X DELETE -u username:password -H "Content-Type:application/json" http://bitbucket.example.com/rest/snippets/1.0/snippets/87dec410f4404d4ca43dc4772a8bd0f0

Delete comment

DELETE http://{host}:{port}/{context}/rest/snippets/1.0/snippets/{snippetGuid}/comments/{commentGuid}

Example Request

curl -X DELETE -u username:password -H "Content-Type:application/json" http://bitbucket.example.com/rest/snippets/1.0/snippets/87dec410f4404d4ca43dc4772a8bd0f0/comments/6b90147977bb42f782610f0211a94cfc

Error rendering macro 'excerpt-include' : No link could be created for 'DOC:Service Level Agreement'.