Project Branches REST API


List branches for a project


⚠️ Breaking Changes: The Bencher API is in beta and under active development. We may introduce breaking changes in future releases. We will announce any breaking changes in the release notes.

List all branches for a project. If the project is public, then the user does not need to be authenticated. If the project is private, then the user must be authenticated and have `view` permissions for the project. By default, the branches are sorted in alphabetical order by name.

Headers


Content-Type

string

Required

Set to application/json.


Authorization

string

Set to Bearer BENCHER_API_TOKEN, where BENCHER_API_TOKEN is a vaild Bencher API token.

Path Parameters


project

string

Required

The slug or UUID for a project.

Query Parameters


direction

string

The direction to sort by. If not specified, the default sort direction is used.

Default: asc

One of: asc, desc


page

integer

The page number to return. If not specified, the first page is returned.

Default: 1


per_page

integer

The number of items to return per page. If not specified, the default number of items per page (8) is used.

Default: 8


sort

string

The field to sort by. If not specified, the default sort field is used.

Default: name

One of: name


name

string

Filter by branch name, exact match.


search

string

Search by branch name, slug, or UUID.

GET
/v0/projects/{project}/branches
Bencher Cloud https://api.bencher.dev
Bencher Self-Hosted http://localhost:61016

Bencher CLI

bencher branch list PROJECT

View OpenAPI Spec

Create a branch


⚠️ Breaking Changes: The Bencher API is in beta and under active development. We may introduce breaking changes in future releases. We will announce any breaking changes in the release notes.

Create a branch for a project. The user must have `create` permissions for the project.

Headers


Content-Type

string

Required

Set to application/json.


Authorization

string

Required

Set to Bearer BENCHER_API_TOKEN, where BENCHER_API_TOKEN is a vaild Bencher API token.

Path Parameters


project

string

Required

The slug or UUID for a project.

Body Parameters


name

string

Required

The name of the branch. Maximum length is 256 characters.


slug

string

The preferred slug for the branch. If not provided, the slug will be generated from the name. If the provided or generated slug is already in use, a unique slug will be generated. Maximum length is 64 characters.


soft

boolean

If set to `true` and a branch with the same name already exits, the existing branch will be returned without an error. This is useful in cases where there may be a race condition to create a new branch, such as multiple jobs in a CI/CD pipeline.


start_point

object

The start point for the new branch. All branch versions from the start point branch will be shallow copied over to the new branch. That is, all historical metrics data for the start point branch will appear in queries for the new branch. For example, pull request branches often use their base branch as their start point branch. After the new branch is created, it is not kept in sync with the start point branch. If not provided, the new branch will have no historical data.

Properties of start_point

branch

string

Required

The UUID, slug, or name of the branch to use as the start point.


hash

string

The full `git` hash of the branch to use as the start point.


thresholds

boolean

If set to `true`, the thresholds from the start point branch will be deep copied to the new branch. This can be useful for pull request branches that should have the same thresholds as their target branch.

POST
/v0/projects/{project}/branches
Bencher Cloud https://api.bencher.dev
Bencher Self-Hosted http://localhost:61016

Bencher CLI

bencher branch create PROJECT

View OpenAPI Spec

View a branch


⚠️ Breaking Changes: The Bencher API is in beta and under active development. We may introduce breaking changes in future releases. We will announce any breaking changes in the release notes.

View a branch for a project. If the project is public, then the user does not need to be authenticated. If the project is private, then the user must be authenticated and have `view` permissions for the project.

Headers


Content-Type

string

Required

Set to application/json.


Authorization

string

Set to Bearer BENCHER_API_TOKEN, where BENCHER_API_TOKEN is a vaild Bencher API token.

Path Parameters


branch

string

Required

The slug or UUID for a branch.


project

string

Required

The slug or UUID for a project.

GET
/v0/projects/{project}/branches/{branch}
Bencher Cloud https://api.bencher.dev
Bencher Self-Hosted http://localhost:61016

Bencher CLI

bencher branch view PROJECT BRANCH

View OpenAPI Spec

Update a branch


⚠️ Breaking Changes: The Bencher API is in beta and under active development. We may introduce breaking changes in future releases. We will announce any breaking changes in the release notes.

Update a branch for a project. The user must have `edit` permissions for the project.

Headers


Content-Type

string

Required

Set to application/json.


Authorization

string

Required

Set to Bearer BENCHER_API_TOKEN, where BENCHER_API_TOKEN is a vaild Bencher API token.

Path Parameters


branch

string

Required

The slug or UUID for a branch.


project

string

Required

The slug or UUID for a project.

Body Parameters


hash

string

The full `git` commit hash for the next version of the branch. This is useful in cases where there may be a race condition when a start point branch has been updated but its benchmarks have not yet finished.


name

string

The new name of the branch. Maximum length is 256 characters.


slug

string

The preferred new slug for the branch. Maximum length is 64 characters.

PATCH
/v0/projects/{project}/branches/{branch}
Bencher Cloud https://api.bencher.dev
Bencher Self-Hosted http://localhost:61016

Bencher CLI

bencher branch update PROJECT BRANCH

View OpenAPI Spec

Delete a branch


⚠️ Breaking Changes: The Bencher API is in beta and under active development. We may introduce breaking changes in future releases. We will announce any breaking changes in the release notes.

Delete a branch for a project. The user must have `delete` permissions for the project. All reports and thresholds that use this branch must be deleted first!

Headers


Content-Type

string

Required

Set to application/json.


Authorization

string

Required

Set to Bearer BENCHER_API_TOKEN, where BENCHER_API_TOKEN is a vaild Bencher API token.

Path Parameters


branch

string

Required

The slug or UUID for a branch.


project

string

Required

The slug or UUID for a project.

DELETE
/v0/projects/{project}/branches/{branch}
Bencher Cloud https://api.bencher.dev
Bencher Self-Hosted http://localhost:61016

Bencher CLI

bencher branch delete PROJECT BRANCH

View OpenAPI Spec


Published: Mon, February 12, 2024 at 7:26:00 AM UTC | Last Updated: Wed, April 3, 2024 at 11:23:00 AM UTC