Releases#

API version: v1alpha1

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

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

Create a release#

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

Creating a release 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}/releases

Create Release

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

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

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
`title`	string	Yes	The title of the release.
`commitSha`	string	Yes	The commit SHA or branch name of the release.
`tag`	string	Yes	The name of the tag.
`description`	string	No	The description of the tag.
`createTagIfNotExists`	boolean	No	Whether to create a tag if it doesn't exist.

Responses

200 Success

Body — application/json

{
  "status": "Success",
  "database_owner": "dolthub",
  "database_name": "museum-collections",
  "release_tag": "v1",
  "release_description": "First version of the database",
  "release_commit_sha": "1234567890",
  "release_title": "my-release-v1",
  "release_created_at": "2021-01-01T00:00:00Z",
  "release_updated_at": "2021-01-01T00:00:00Z"
}

Field	Type	Description
`status`	string	Status of the create branch operation
`database_owner`	string	Owner of the database
`database_name`	string	Database name
`release_tag`	string	Name of the tag
`release_description`	string	Description of the release
`release_commit_sha`	string	Commit SHA of the release
`release_title`	string	Title of the release
`release_created_at`	string	Created at of the release
`release_updated_at`	string	Updated at of the release

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

Body — application/json

{
  "status": "Error",
  "message": "Error creating a release.",
  "database_owner": "dolthub",
  "database_name": "museum-collections",
  "release_tag": "v1",
  "release_description": "First version of the database",
  "release_commit_sha": "1234567890",
  "release_title": "my-release-v1"
}

Field	Type	Description
`status`	string
`message`	string
`database_owner`	string	Owner of the database
`database_name`	string	Database name
`release_tag`	string	Name of the tag
`release_description`	string	Description of the release
`release_commit_sha`	string	Commit SHA of the release
`release_title`	string	Title of the release

List releases#

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

Listing releases 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}/releases

List Releases

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

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

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`
`next_page_token`	query	string	No	The next page token. Example: `1234567890`

Responses

200 Success

Body — application/json

{
  "status": "Success",
  "database_owner": "dolthub",
  "database_name": "museum-collections",
  "next_page_token": "1234567890",
  "releases": [
    {
      "release_title": "my-release-v1",
      "release_tag": "v1",
      "release_commit_sha": "1234567890",
      "release_description": "First version of the database",
      "release_created_at": "2023-03-31T18:00:00Z",
      "release_updated_at": "2023-03-31T18:00:00Z"
    }
  ]
}

Field	Type	Description
`status`	string	Status of the request
`database_owner`	string	Owner of the database
`database_name`	string	Database name
`next_page_token`	string	Next page token
`releases`	array<object>	List of releases

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

Body — application/json

{
  "status": "Error",
  "message": "Error creating a release.",
  "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