curl -H "Authorization: Bearer api-access-token" \
'https://api.buddybuild.com/v1/apps'
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.
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 |
Request succeeded, and the data requested is included in the response body. |
201 |
Created |
The request to create a resource succeeded. The ID of the newly created resource may be returned in the response body. |
204 |
No Content |
Request succeeded, but no data is returned. |
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
curl https://api.buddybuild.com/v1/apps
HTTP/1.1 401 Unauthorized
{
"error": "No authorization token was found"
}
Using an invalid or revoked access token
curl -H "Authorization: Bearer INVALID_TOKEN" \
'https://api.buddybuild.com/v1/apps'
HTTP/1.1 401 Unauthorized
{
"error": "Invalid authorization token"
}