buddybuild REST API documentation

Overview

The buddybuild API is a RESTful interface, providing programmatic access to much of the data in the system. It provides predictable URLs for accessing resources, and uses built-in HTTP features to receive commands and return responses. This makes it easy to communicate with from a wide variety of environments, from command-line utilities to client libraries to apps.

The API accepts JSON or form-encoded content in requests and returns JSON content in all of its responses, including errors. Only the UTF-8 character encoding is supported for both requests and responses.

At this time the buddybuild API responds to a single version of the API. All resources are available under the https://api.buddybuild.com/v1/ base URL.

Authentication

Each user in buddybuild has their own unique Personal Access Token, which can be used to talk to buddybuild on behalf of the user.

Note

Looking for your API access token?

To obtain your personal access token sign in to the buddybuild dashboard, hover over your profile icon and select My Profile, then select Access Token in the left menu. Or visit this direct link to your personal access token

Personal access tokens should be used when accessing the API, passing them in the Authorization header. Remember to keep your token secret, treating it just like a password. It acts on your behalf when interacting with the API. Don’t hardcode them into your programs; instead opt to use them as environment variables.

Using personal access tokens in requests
curl -H "Authorization: Bearer api-access-token" \
  'https://api.buddybuild.com/v1/apps'

Percent Encoding

Many of the buddybuild API methods accept URL parameters that must be percent encoded to avoid conflicts with reserved characters. Reserved characters are those characters that sometimes have special meaning in a URL.

For example, when passing a Git branch named feature/find&replace as a branch parameter it must be percent encoded as feature%2Ffind%26replace.

Errors

Sometimes requests to the API are not successful. Failures can occur for a wide range of reasons. In all cases, the API returns an HTTP Status Code that indicates the reason for the failure, with a response body in JSON format containing additional information.

Code Reason Description

200

OK

If data was requested, it is included in the response body.

400

Bad Request

This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.

401

Unauthorized

A valid API personal access token was not provided with the request, so the API could not associate a user with the request.

404

Not Found

Either the request method and path supplied do not specify a known action in the API, or the object specified by the request does not exist.

500

Server Error

There was a problem on buddybuild’s end. Contact support.

503

Service Unavailable

The buddybuild API server is temporarily unavailable because it is overloaded or down for maintenance. Check http://status.buddybuild.com/ for updates or contact support.

504

Gateway Time-out

The buddybuild API server is temporarily unavailable because it is overloaded or down for maintenance. Check http://status.buddybuild.com/ for updates or contact support.

In the event of an error, the response body contains an error field at the top level. This error message provides more detail about the error that occurred, if available.

Examples of common errors

Missing authorization header

Request
curl https://api.buddybuild.com/v1/apps
Response
HTTP/1.1 401 Unauthorized
{
  "error": "No authorization token was found"
}

Using an invalid or revoked access token

Request
curl -H "Authorization: Bearer INVALID_TOKEN" \
  'https://api.buddybuild.com/v1/apps'
Response
HTTP/1.1 401 Unauthorized
{
  "error": "Invalid authorization token"
}

results matching ""

    No results matching ""