Branches#

API version: v1alpha1

DoltHub provides API endpoints for creating and listing branches on a database.

Note: please send requests to https://www.dolthub.com, not https://dolthub.com.

Create a branch#

Here’s an example of how to create a new branch in database museum-collections under the organization dolthub using an authorization token.

Creating a branch requires authentication, so you must include this authorization header in your request. See the Authentication section for more details.

headers = {
    'authorization': 'token [api token you created]'
}

POST /{owner}/{database}/branches

Create Branch

This API endpoint allows you to create a new branch in your database.

URL https://www.dolthub.com/api/v1alpha1/{owner}/{database}/branches

Parameters

Name	In	Type	Required	Description
`owner`	path	string	Yes	The name of the owner of the database. Example: `dolthub`
`database`	path	string	Yes	The name of the database. Example: `museum-collections`

Request Body

Content-Type: application/json

Field	Type	Required	Description
`revisionType`	string	Yes	The type of revision, can be either 'branch', 'ref' or 'commit'.
`revisionName`	string	Yes	The name of revision. If revisionType is 'branch', this is the name of the base branch. If revisionType is 'commit', this is the commit hash.
`newBranchName`	string	Yes	The name of the new branch.

Responses

200 Success

Body — application/json

{
  "status": "Success",
  "database_owner": "dolthub",
  "database_name": "museum-collections",
  "new_branch_name": "feature-branch",
  "revision_type": "branch",
  "revision_name": "main"
}

Field	Type	Description
`status`	string	Status of the create branch operation
`database_owner`	string	Owner of the database
`database_name`	string	Database name
`new_branch_name`	string	Name of the new branch
`revision_type`	string	Type of the revision
`revision_name`	string	Name of the revision

400 Bad request. The request was invalid or could not be processed.

Body — application/json

{
  "status": "Error",
  "message": "Error creating a branch.",
  "database_owner": "dolthub",
  "database_name": "museum-collections",
  "new_branch_name": "feature-branch",
  "revision_type": "branch",
  "revision_name": "main"
}

Field	Type	Description
`status`	string
`message`	string
`database_owner`	string	Owner of the database
`database_name`	string	Database name
`new_branch_name`	string	Name of the new branch
`revision_type`	string	Type of the revision
`revision_name`	string	Name of the revision

List branches#

Here’s an example of how to list branches in the database museum-collections under the organization dolthub using an authorization token.

Listing branches requires authentication, so you must include this authorization header in your request. See the Authentication section for more details.

headers = {
    'authorization': 'token [api token you created]'
}

GET /{owner}/{database}/branches

List Branches

This API endpoint allows you to list all branches in your database.

URL https://www.dolthub.com/api/v1alpha1/{owner}/{database}/branches

Parameters

Name	In	Type	Required	Description
`owner`	path	string	Yes	The name of the owner of the database. Example: `dolthub`
`database`	path	string	Yes	The name of the database. Example: `museum-collections`

Responses

200 Success

Body — application/json

{
  "status": "Success",
  "database_owner": "dolthub",
  "database_name": "museum-collections",
  "branches": [
    {
      "branch_name": "main"
    }
  ]
}

Field	Type	Description
`status`	string	Status of the request.
`database_owner`	string	Owner of the database
`database_name`	string	Database name
`branches`	array<object>	List of branches

400 Bad request. The request was invalid or could not be processed.

Body — application/json

{
  "status": "Error",
  "message": "Error getting the branches list.",
  "database_owner": "dolthub",
  "database_name": "museum-collections"
}

Field	Type	Description
`status`	string
`message`	string
`database_owner`	string	Owner of the database
`database_name`	string	Database name