Overview

Here you’ll find basic information on the Buddy’s API. If you’d like to see how things work in action, go to Hello World. In case of questions or requests, reach out on the live chat or write to support@buddy.works.

Permissions

By default, the API is disabled in every workspace. You can enable it in the workspace settings. Permissions for calling out the API methods are the same as those in the website service. For example, if the ability to delete projects is restricted to admins only, the same restriction will be applied to the API methods.

To enable the API, go to Workspace Settings under the Workspace tab. In the Developer API section, check the box labeled Enable developer API.

Image loading...

Endpoint

Depending on the account type, the API is available from three locations.

For US accounts starting with app.buddy.works:


https://api.buddy.works

For EU accounts starting with eu.buddy.works:


https://api.eu.buddy.works

For self-hosted installations of Buddy:


https://YOUR-IP-ADDRESS/api

HTTP Verbs

For each action, appropriate HTTP verbs need to be used:

Verb	Description
GET	used to fetch resources
POST	used to create resources
PATCH	used to update data; only fields sent in the request are updated
PUT	used to update data; updates all properties of the object; set to null if something is not to be posted
DELETE	used to delete resources

Authentication

Authentication is performed with OAuth2 mechanisms.

If you already have access_token, requests are sent with an HTTP HEADER:


Authorization: Bearer <access_token>

Schema

All requests must be sent and are received in JSON format. All API requests must be executed over HTTPS. Empty fields are returned as NULL and are not omitted. All dates are returned in the ISO format:


yyyy-MM-dd'T'HH:mm:ssZ

Summary and Detailed Objects

When you fetch a list of resources, the response is returned as a summary, which means that not all object fields are returned. It works this way to prevent impact on performance by large amount of data returned. For example, when fetching a list of commits, the response comes in a shortened version:


GET /workspaces/:domain/projects/:project_name/repository/commits

Sample Response

HTTP


Status: 200 OK
X-Rate-Limit-Limit: 1
X-Rate-Limit-Remaining: 999

JSON

json
{
  "url": "https://api.buddy.works/workspaces/buddy/projects/company-website/repository/commits",
  "html_url": "https://app.buddy.works/buddy/company-website/repository/commits",
  "commits": [
    {
      "url": "https://api.buddy.works/workspaces/buddy/projects/company-website/repository/commits/506a3963507943d6908154f4bc9646e829128a08",
      "html_url": "https://app.buddy.works/buddy/company-website/repository/commit/506a3963507943d6908154f4bc9646e829128a08",
      "revision": "506a3963507943d6908154f4bc9646e829128a08",
      "author_date": "2016-01-19T12:36:33Z",
      "commit_date": "2016-01-19T12:36:33Z",
      "message": "init repo\n",
      "committer": {
        "url": "https://api.buddy.works/workspaces/buddy/member/1",
        "html_url": "https://app.buddy.works/buddy/profile/1",
        "id": 1,
        "name": "Mike Benson",
        "avatar_url": "https://app.buddy.works/image-server/user/0/0/0/0/0/0/1/d643744fbe5ebf2906a4d075a5b97110/w/32/32/AVATAR.png"
      },
      "author": {
        "url": "https://api.buddy.works/workspaces/buddy/member/1",
        "html_url": "https://app.buddy.works/buddy/profile/1",
        "id": 1,
        "name": "Mike Benson",
        "avatar_url": "https://app.buddy.works/image-server/user/0/0/0/0/0/0/1/d643744fbe5ebf2906a4d075a5b97110/w/32/32/AVATAR.png"
      }
    }
  ]
}

When asking for a single commit, however, the response is a full object:


GET /workspaces/:domain/projects/:project_name/repository/commits/:revision

Sample Response

HTTP


Status: 200 OK
X-Rate-Limit-Limit: 1
X-Rate-Limit-Remaining: 999

JSON

json
{
  "url": "https://api.buddy.works/workspaces/buddy/projects/company-website/repository/commits/506a3963507943d6908154f4bc9646e829128a08",
  "html_url": "https://app.buddy.works/buddy/company-website/repository/commit/506a3963507943d6908154f4bc9646e829128a08",
  "revision": "506a3963507943d6908154f4bc9646e829128a08",
  "author_date": "2016-01-19T12:36:33Z",
  "commit_date": "2016-01-19T12:36:33Z",
  "message": "init repo\n",
  "stats": {
    "additions": 388,
    "deletions": 0,
    "total": 388
  },
  "files": [
    {
      "file_name": ".gitignore",
      "status": "ADDED",
      "additions": 3,
      "deletions": 0,
      "total": 3,
      "patch": "@@ -0,0 +1,3 @@\n+.idea/\n+.DS_Store\n+css/\n"
    }
  ],
  "committer": {
    "url": "https://api.buddy.works/workspaces/buddy/member/1",
    "html_url": "https://app.buddy.works/buddy/profile/1",
    "id": 1,
    "name": "Mike Benson",
    "avatar_url": "https://app.buddy.works/image-server/user/0/0/0/0/0/0/1/d643744fbe5ebf2906a4d075a5b97110/w/32/32/AVATAR.png"
  },
  "author": {
    "url": "https://api.buddy.works/workspaces/buddy/member/1",
    "html_url": "https://app.buddy.works/buddy/profile/1",
    "id": 1,
    "name": "Mike Benson",
    "avatar_url": "https://app.buddy.works/image-server/user/0/0/0/0/0/0/1/d643744fbe5ebf2906a4d075a5b97110/w/32/32/AVATAR.png"
  },
  "content_url": "https://api.buddy.works/workspaces/buddy/projects/company-website/repository/contents?revision=506a3963507943d6908154f4bc9646e829128a08"
}

status in file object can be either ADDED, MODIFIED, REPLACED, or DELETED

The documentation provides example responses for each API method. The response illustrates all attributes that are returned by that method.

Parameters

Required parameters are sent as path parameters. For example, the name of the project is a required parameter when fetching a list of commits:


GET https://api.buddy.works/workspaces/:domain/projects/:project_name/repository/commits

Optional parameters are posted as a query string. For example, in order to narrow a commit list to a specific time range, you need to execute the following method:


GET https://api.buddy.works/workspaces/:domain/projects/:project_name/repository/commits?since=2014-11-6T00:00:00Z&until=2014-11-7T00:00:00Z&page=1&per_page=2

For POST, PATCH, PUT and DELETE, parameters should be sent as body in JSON with Content-Type set to application/json. For example, to add a project you need to execute the following request:

Request


POST https://api.buddy.works/workspaces/buddy/projects

JSON

json
{
  "name": "landing-page",
  "display_name": "Landing page"
}

Client Errors

All API requests are validated. If something goes wrong, you’ll receive a descriptive error so that it can be quickly fixed by the invoker. There are three possible types of client errors that can be returned:

1. If you’re trying to execute an API method in a workspace with disabled API

HTTP


 HTTP/1.1 400 Bad Request

JSON

json
{
    "errors": [
        {
            "message": "API is disabled in this workspace."
        }
     ]
}

2. If the URL is in bad format

HTTP


 HTTP/1.1 400 Bad Request

JSON

json
{
    "errors": [
        {
            "message": "Invalid url: /api/ws/account/permissions"
        }
    ]
}

3. If the parameters are sent as a wrong type

HTTP


HTTP/1.1 400 Bad Request

JSON

json
{
    "errors": [
        {
            "message": "Value of 'name' cannot be empty."
        }
    ]
}

Timezone

Some requests can be paremetrized with a timestamp. For example, you can restrict a list of commits to a specific time range with the query param since/until. All dates should be sent in UTC timezone.

Rate Limiting

Hint

Updated on March 1, 2020.

User is allowed to make 5000 requests per hour regardless of the resource type. If you want to see your current rate limit status, check the returned HTTP headers of any API request:


GET https://api.buddy.works/user

HTTP


Status: 200 OK
X-Rate-Limit-Limit: 5000
X-Rate-Limit-Remaining: 4999
X-Rate-Limit-Reset: 1446629442

All information about your current rate limit status is told with headers:

Header Name	Description
X-Rate-Limit-Limit	The current number of requests that the consumer can make in the current window (60 minutes).
X-Rate-Limit-Remaining	The number of requests remaining in the current rate limit window.
X-Rate-Limit-Reset	The time at which the current rate limit window resets in UTC epoch seconds.

If the limit is exceeded, you’ll receive the following response:

HTTP


HTTP/1.1 403 Forbidden

JSON

json
{
 "errors": [
  {
   "message": "Rate limit exceeded."
  }
 ]
}

Pagination

Some requests which return a list of objects are divided in pages of 20 items as default. To change the number of items returned, you need to use per_page in the query parameter. To fetch the proceeding pages, you need to use the pagequery parameter. If the parameter page is not found, only the first page of the results will be returned:


https://api.buddy.works/workspaces/:domain/projects/:project_name/repository/commits?since=2014-11-6T00:00:00Z&until=2014-11-7T00:00:00Z&page=1&per_page=2

The API supports Cross Origin Resource Sharing (CORS) for AJAX requests from any origin. Here’s a sample request sent from a browser hitting http://example.com:


curl -kH "Origin: http://example.com" --verbose -H "Access-Control-Request-Method: POST" -H "Access-Control-Request-Headers: X-Requested-With" -X OPTIONS https://api.buddy.works/workspaces/example/projects

OPTIONS /workspaces/example/projects HTTP/1.1
Host: api.buddy.works
User-Agent: curl/7.47.0
Accept: */*
Origin: http://example.com
Access-Control-Request-Method: POST
Access-Control-Request-Headers: X-Requested-With

HTTP/1.1 200 OK
Date: Thu, 20 Jul 2017 11:56:53 GMT
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: Content-Type, Authorization
Access-Control-Allow-Methods: POST GET
X-Buddy-Media-Type: buddy.v1.0.0
Access-Control-Allow-Origin: *
Content-Length: 0
Server: Jetty(9.4.6.v20170531)

Last modified on Nov 15, 2024

Hello World