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, visit our Forum, or contact us directly at 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 API methods.

Endpoint

You can get the API here:

https://api.buddy.works

The API for your Buddy Enterprise (on-premises) installation is available here:

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. Click here for more details.

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
Status: 200 OK
X-Rate-Limit-Limit: 1
X-Rate-Limit-Remaining: 999
{
  "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",
        "title": "Creative director"
      },
      "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",
        "title": "Creative director"
      }
    }
  ]
}

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

GET
/workspaces/:domain/projects/:project_name/repository/commits/:revision
Sample Response
Status: 200 OK
X-Rate-Limit-Limit: 1
X-Rate-Limit-Remaining: 999
{
  "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",
    "title": "Creative director"
  },
  "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",
    "title": "Creative director"
  },
  "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
{
  "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/1.1 400 Bad Request
{
    "errors": [
        {
            "message": "API is disabled in this workspace."
        }
    ]
}

2. If the URL is in bad format

 HTTP/1.1 400 Bad Request
 {
    "errors": [
        {
            "message": "Invalid url: /api/ws/account/permissions"
        }
    ]
}

3. If the parameters are sent as a wrong type

HTTP/1.1 400 Bad Request
{ 
    "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 1000 requests in a 15-minute window. 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
Status: 200 OK
X-Rate-Limit-Limit: 1
X-Rate-Limit-Remaining: 999
X-Rate-Limit-Reset: 1446629442

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

Header Name Description
X-RateLimit-Limit The maximum number of requests that the consumer is permitted to make per window (15 minutes).
X-RateLimit-Remaining The number of requests remaining in the current rate limit window.
X-RateLimit-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/1.1 403 Forbidden
{
 "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 page query 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
esc

Sign up for free

No setup fees. No requirements. No obligation.

or sign up with