services Resource

Overview

Bitbucket integrates with external services (hooks) through a set of brokers that run in response to certain events.  Brokers are Python scripts that receive information about an event and then take one or more actions. For example, there is a Bamboo broker for integrating with Bamboo.   The Bitbucket team developed many of our brokers. Third-party vendors also developed several brokers.

The Bitbucket services resource provides functionality for adding, removing, and configuring brokers on your repositories.  All the methods on this resource require the caller to authenticate.  Services have the following structure:

The fields in the service structure are the following:

Field Description
id A Bitbucket assigned integer representing a unique identifier for the service.
service A profile describing the service.
  fields A parameter array containing a name and value pair for each parameter associated with the service.
  type One of the supported services. The type is a case-insensitive value.

The following services are supported:

Name Description and Parameters
POST Bitbucket POSTs to the service URL you specify. The service receives an POST whenever user pushes to the repository.
URL
The URL to which Bitbucket should send its update messages.
FogBugz Bug tracking service . This service has the following parameters.
Repository ID
The ID of the FogBugz repository.
CVSSubmit URL
Enter the URL to which Bitbucket should send its update messages
Basecamp
A web-based project management application.
Password
Your Basecamp password.
Discussion URL
Enter the URL to which Bitbucket should send its update messages.
Username
The Basecamp username.
Lighthouse
A simple issue tracking system.
Project ID
Enter the numeric ID for your project. You can get it from your project URL at Lighthouse.
For example, let's say your Lighthouse project URL is this: 
XXXXX . lighthouseapp.com/projects/ 00000 -yourproject/overview
In this case,  00000  would be your Project ID.
API Key
Enter the API token you have created at Lighthouse (see above).
Subdomain
The Lighthouse account name.
For example, let's say your Lighthouse project URL is this: 
XXXXX . lighthouseapp.com/projects/ 00000 -yourproject/overview
In this case,  XXXXX  would be your subdomain.
Issues
Allows users to reference Bitbucket issue tracker issues from commit messages. Bitbucket adds this service automatically for new issue trackers created after August 2012. This service has no parameters.
Email
Allows Bitbucket to send an email message to a given email address, for each pushed changegroup.
Email The email address to send to.
Diff
Set up Bitbucket to send an email message to a given email address when the repository is updated.
Email
The email address where Bitbucket should send the email messages.
FriendFeed
Bitbucket will post information to FriendFeed as a feed when your project is updated.
Username
Your FriendFeed username.
Remote Key
Your remote key at  friendfeed.com/remotekey .
Format
The format of the message sent to FriendFeed. Use the default value or change the template to suit your needs, as described in FriendFeed service management.
Rietveld

 
A code review tool.
Email

The URL of your Rietveld site. The default value is: http://reitveld-bitbucket.appspot.com/

Password
Rietveld user password.
URL
Rietveld email address.
Superfeeder
Superfeedr a real-time cloud feed parsing service. This service takes no parameters.
Geocommit
Geocommit is a service to add geolocation to your commits.
Pivotal Tracker
An agile project management tool.
Token
Tracker uses a token mechanism to authenticate API users, and access control to projects and stories is based on the user's project memberships.To generate a token, use the "Create New Token" link on the My Profile page.
Twitter
Although you can add Twitter service via API, since it requires three-legged OAuth authentication, you must configure it via the GUI interface. For details, see Twitter service management
Secret
Secret generated by Twitter.
Token
Token generated by Twitter.
Format
The format of the Twitter update.

GET a list of services on a repository

Lists the services existing on a repository.

GET https://api.bitbucket.org/1.0/repositories/{accountname}/{repo_slug}/services
  Click here to expand...

GET a single service attached to your repository

Returns the profile of a single service attached to your repository.  You must have the service Id to use this call.

GET https://api.bitbucket.org/1.0/repositories/{accountname}/{repo_slug}/services/{id}
  Click here to expand...

POST a new service

Adds a service to a repository. Only the type of the service is required in the POST data. (Service type is a case-insensitive match.)  Optionally, you can provide all the service parameters.  You can update service fields later.  For example, the following shows a call to create a POST service:

curl -u tutorials:8798987 -X POST https://api.bitbucket.org/1.0/repositories/tutorials/testrepo/services/ -d "type=POST&URL=https%3A%2F%2Fbitbucket.org/post"
POST https://api.bitbucket.org/1.0/repositories/{accountname}/{repo_slug}/services/ --data "type=value&parameter=value&..."
  Click here to expand...

 

PUT a change to a service

To update a service, issue a PUT request with the id of the repository service included in the URL.  Pass each parameter separately.  You must include all the parameters in the service.  If you omit a parameter or pass an invalid parameter, the PUT removes all the values for the service.

For example:

$ curl --request PUT --user mcatalbas:password https://api.bitbucket.org/1.0/repositories/mcatalbas/test/services/5/ --data "URL=https://bitbucket.org/new_post"
PUT https://api.bitbucket.org/1.0/repositories/{accountname}/{repo_slug}/services/{id} --data "parameter=value"  --data "parameter=value" ...
  Click here to expand...

DELETE a service

Removes a service. The caller must supply the id of the service to remove for example:

$ curl --request DELETE --user mcatalbas:password https://api.bitbucket.org/1.0/repositories/mcatalbas/test/services/5/.

Was this helpful?

Thanks for your feedback!

Powered by Confluence and Scroll Viewport