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 enabled in every workspace. You can disable 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.

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:

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

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:

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

Cross Origin Resource Sharing

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)