# Overview

> For AI agents: the complete documentation index is at https://buddy.works/llms.txt

Basic information about Buddy's API. Learn about the HTTP Verbs and Authentication.

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](https://buddy.works/docs/api/getting-started/hello-world.md). In case of questions or requests, reach out on the live chat or write to <support@buddy.works>.

> **Info**
>
> Need a machine-readable API definition? See the [OpenAPI specification](#openapi-specification).

## 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.

![To enable the API, go to Workspace Settings under the Workspace tab. In the Developer API section, check the box labeled Enable developer API.](https://buddy.works/docs/api/getting-started/how-enabled-api.png)

## Endpoint

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

For US accounts starting with `app.buddy.works`:

```text
https://api.buddy.works
```

For EU accounts starting with `eu.buddy.works`:

```text
https://api.eu.buddy.works
```

For Asia accounts starting with `asia.buddy.works`:

```text
https://api.asia.buddy.works
```

For self-hosted installations of Buddy:

```text
https://YOUR-IP-ADDRESS/api
```

## OpenAPI specification

The Buddy REST API is described by an OpenAPI 3 specification. Use it to generate API clients or import the API into tools like Postman, Insomnia, or Swagger UI.

[Download the OpenAPI specification](https://buddy.works/openapi.json) (updated on every Buddy release).

## 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](https://buddy.works/docs/api/getting-started/oauth2.md).

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

```text
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:

```text
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:

```text
GET /workspaces/:workspace/projects/:project_name/repository/commits
```

**Sample Response**

HTTP

```text
Status: 200 OK
X-Rate-Limit-Limit: 1000
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": "2025-04-10T12:36:33Z",
      "commit_date": "2025-04-10T12: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",
        "email": "mike.benson@example.com",
        "admin": true,
        "workspace_owner": false
      },
      "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",
        "email": "mike.benson@example.com",
        "admin": true,
        "workspace_owner": false
      }
    }
  ]
}

```

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

```text
GET /workspaces/:workspace/projects/:project_name/repository/commits/:revision
```

**Sample Response**

HTTP

```text
Status: 200 OK
X-Rate-Limit-Limit: 1000
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": "2025-04-10T12:36:33Z",
  "commit_date": "2025-04-10T12: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",
    "email": "mike.benson@example.com",
    "admin": true,
    "workspace_owner": false
  },
  "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",
    "email": "mike.benson@example.com",
    "admin": true,
    "workspace_owner": false
  },
  "content_url": "https://api.buddy.works/workspaces/buddy/projects/company-website/repository/contents?revision=506a3963507943d6908154f4bc9646e829128a08",
  "parents": [
    {
      "url": "https://api.buddy.works/workspaces/buddy/projects/company-website/repository/commits/73a01319575d455c87fe24e9a2becf5c1ca699a6",
      "html_url": "https://app.buddy.works/buddy/company-website/repository/commit/73a01319575d455c87fe24e9a2becf5c1ca699a6",
      "revision": "73a01319575d455c87fe24e9a2becf5c1ca699a6"
    }
  ]
}

```

`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:

```text
GET https://api.buddy.works/workspaces/:workspace/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:

```text
GET https://api.buddy.works/workspaces/:workspace/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**

```text
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

```text
 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

```text
 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

```text
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

Rate limits are applied per resource. The limit can vary, so check the HTTP headers returned by an API request for the current limit and remaining requests. The values below are only an example:

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

HTTP

```text
Status: 200 OK
X-Rate-Limit-Limit: 1000
X-Rate-Limit-Remaining: 999
X-Rate-Limit-Reset: <UTC epoch seconds>
```

The response headers describe the current rate limit:

| Header Name | Description |
| :--- | :--- |
| X-Rate-Limit-Limit | The maximum number of requests to this resource in the current window. |
| X-Rate-Limit-Remaining | The number of requests to this resource remaining in the current window. |
| X-Rate-Limit-Reset | The time when the next rate limit window begins, in UTC epoch seconds. |
| Retry-After | When present, the number of seconds to wait before retrying. |

When the limit is exceeded, the API can return `429 Too Many Requests` with `Retry-After`:

HTTP

```text
HTTP/1.1 429 Too Many Requests
X-Rate-Limit-Limit: 3000
X-Rate-Limit-Remaining: 0
X-Rate-Limit-Reset: <UTC epoch seconds>
Retry-After: <seconds>
```

A rate limit error can also return `403 Forbidden` with the same error message and rate limit headers, but without `Retry-After`. Check the error message and headers to distinguish it from other `403` responses.

JSON

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

Wait until `X-Rate-Limit-Reset` before sending another request to the same resource. If the response includes `Retry-After`, you can use it to determine how long to wait. Requests sent before the window resets will keep hitting the limit.

## 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:

```text
https://api.buddy.works/workspaces/:workspace/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`:

```text
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)
```


---
Original source: https://buddy.works/docs/api/getting-started/overview