Pull Requests#

API version: v1alpha1

DoltHub provides API endpoints for creating, getting, updating, listing, commenting on, and merging pull requests on a database.

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

Create pull request#

Here is an example of opening a pull request on the museum-collections database with data from the Los Angeles County Museum of Art. This data was added to the lacma branch on a fork database, whose owner is liuliu, we would like to eventually merge lacma branch into the main branch using an authorization token.

Include this header in your request.

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

POST /{owner}/{database}/pulls

Create a new pull request

This API allows you to create a new pull request.

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

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	No	The title of the pull request.
`description`	string	No	The description of the pull request.
`fromBranchOwnerName`	string	No	The name of the owner of the source branch.
`fromBranchRepoName`	string	No	The name of the database containing the source branch.
`fromBranchName`	string	No	The name of the source branch.
`toBranchOwnerName`	string	No	The name of the owner of the destination branch.
`toBranchRepoName`	string	No	The name of the database containing the destination branch.
`toBranchName`	string	No	The name of the destination branch.

Responses

200 Pull request created successfully.

Body — application/json

{
  "status": "Success",
  "title": "LACMA data",
  "description": "Records from the Los Angeles County of Museum.",
  "from_owner_name": "liuliu",
  "from_repository_name": "museum-collections",
  "from_branch_name": "lacma",
  "to_owner_name": "dolthub",
  "to_repository_name": "museum-collections",
  "to_branch_name": "main",
  "pull_id": "66"
}

Field	Type	Description
`status`	string
`title`	string	The title of the pull request.
`description`	string	The description of the pull request.
`from_owner_name`	string	The name of the owner of the source branch.
`from_repository_name`	string	The name of the database containing the source branch.
`from_branch_name`	string	The name of the source branch.
`to_owner_name`	string	The name of the owner of the destination branch.
`to_repository_name`	string	The name of the database containing the destination branch.
`to_branch_name`	string	The name of the destination branch.
`pull_id`	string	The id of the created pull request.

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

Body — application/json

{
  "status": "Error",
  "message": "Error creating a pull request.",
  "title": "LACMA data",
  "description": "Records from the Los Angeles County of Museum.",
  "from_owner_name": "liuliu",
  "from_repository_name": "museum-collections",
  "from_branch_name": "lacma",
  "to_owner_name": "dolthub",
  "to_repository_name": "museum-collections",
  "to_branch_name": "main"
}

Field	Type	Description
`status`	string
`message`	string
`title`	string	The title of the pull request.
`description`	string	The description of the pull request.
`from_owner_name`	string	The name of the owner of the source branch.
`from_repository_name`	string	The name of the database containing the source branch.
`from_branch_name`	string	The name of the source branch.
`to_owner_name`	string	The name of the owner of the destination branch.
`to_repository_name`	string	The name of the database containing the destination branch.
`to_branch_name`	string	The name of the destination branch.

Get pull request details#

This API allows you to retrieve the details of a specific pull request in the museum-collections database. In this example, we will retrieve the details of pull request #1.

Include this header in your request.

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

GET /{owner}/{database}/pulls/{pull_id}

Get pull request by ID

Get information about a specific pull request.

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

Parameters

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

Responses

200 Success

Body — application/json

{
  "status": "Success",
  "database_owner": "dolthub",
  "database_name": "museum-collections",
  "pull_id": "1",
  "title:": "Added new data",
  "description:": "Added missing museums, sourced from museums.com",
  "state": "merged",
  "from_branch_owner": "liuliu",
  "from_branch_database": "museum-collections",
  "from_branch": "feature",
  "to_branch_owner": "dolthub",
  "to_branch_database": "museum-collections",
  "to_branch": "main",
  "created_at": "2023-07-01T18:00:00Z",
  "author": "liuliu"
}

Field	Type	Description
`status`	string	Status of the request
`database_owner`	string	Owner of the database
`database_name`	string	Database name
`pull_id`	string	Pull request ID
`title:`	string	Title of the pull request
`description:`	string	Description of the pull request
`state`	string	State of the pull request
`from_branch_owner`	string	Owner of database of the source branch.
`from_branch_database`	string	Database name of source branch.
`from_branch`	string	Name of the source branch.
`to_branch_owner`	string	Owner of database of the destination branch.
`to_branch_database`	string	Database name of destination branch.
`to_branch`	string	Name of the destination branch.
`created_at`	string	Time at which the pull request was created
`author`	string	Author of the pull request

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

Body — application/json

{
  "status": "Error",
  "message": "Error getting a pull request.",
  "database_owner": "dolthub",
  "database_name": "museum-collections",
  "pull_id": "1"
}

Field	Type	Description
`status`	string
`message`	string
`database_owner`	string
`database_name`	string
`pull_id`	string

Update a pull request#

This API allows you to update a pull request by providing the fields you want to update in the request body. You can update the title, description, and state (only closing a pull request is supported).

Here’s an example of how to update pull request #1 on the museum-collections database. In this example, we will set a new title, description, and close the pull request.

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

PATCH /{owner}/{database}/pulls/{pull_id}

Update Pull Request

Updates a pull request by ID, including its title, description, and sets its state to be 'closed'.

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

Parameters

Name	In	Type	Required	Description
`owner`	path	string	Yes	The name of the database owner. Example: `dolthub`
`database`	path	string	Yes	The name of the database. Example: `museum-collections`
`pull_id`	path	string	Yes	ID of the pull request to update. Example: `1`

Request Body

Content-Type: application/json

Field	Type	Required	Description
`title`	string	No	The updated title of the pull request.
`description`	string	No	The updated description of the pull request.
`state`	string	No	The updated state of the pull request (can only update to 'closed')

Responses

200 Success

Body — application/json

{
  "status": "Success",
  "database_owner": "dolthub",
  "database_name": "museum-collections",
  "pull_id": "1",
  "title": "Added new data",
  "description": "Added new data from LACMA museum.",
  "state": "closed"
}

Field	Type	Description
`status`	string	Status of the request
`database_owner`	string	Owner of the database
`database_name`	string	Database name
`pull_id`	string	Updated pull request ID
`title`	string	Title of the pull request after update
`description`	string	Description of the pull request after update
`state`	string	State of the pull request after update

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

Body — application/json

{
  "status": "Error",
  "message": "Error updating the pull request.",
  "database_owner": "dolthub",
  "database_name": "museum-collections",
  "pull_id": "1"
}

Field	Type	Description
`status`	string
`message`	string
`database_owner`	string
`database_name`	string
`pull_id`	string

List pull requests#

Here is an example of listing pull requests for the museum-collections database using an authorization token. The response of pull request list is paginated, so you need to use the next page token included in the response to retrieve the following pages of pull requests.

Include this header in your request.

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

GET /{owner}/{database}/pulls

List pull requests of a database

List pull requests

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

Parameters

Name	In	Type	Required	Description
`owner`	path	string	Yes	The name of the database owner. Example: `dolthub`
`database`	path	string	Yes	The name of the database. Example: `museum-collections`
`pageToken`	query	string	No	The pageToken to get the next page of results Example: `AWE2Nm9uMWQ23FSQ7oRTbCXYTLLvNDhNs5hIFebQFI66FW-SYXGSlh3XcUQ8zmtLQ00QgD0X5FZr5ZTAhvT2FfRrGog7OuUno9wdTIXFQpkkX0opYoJL6Vrn2emlXkMBTiZYMqChyhR92_Yxd58B0w5nMrfXFf8v7xfAkN46hw`

Responses

200 Success

Body — application/json

{
  "status": "Success",
  "database_owner": "dolthub",
  "database_name": "museum-collections",
  "pulls": [
    {
      "pull_id": "1",
      "title:": "Added new data",
      "description:": "Added missing museums, sourced from museums.com",
      "state": "merged",
      "created_at": "2023-07-01T18:00:00Z",
      "creator": "liuliu"
    }
  ],
  "next_page_token": "AWE2Nm9uMWQ23FSQ7oRTbCXYTLLvNDhNs5hIFebQFI66FW-SYXGSlh3XcUQ8zmtLQ00QgD0X5FZr5ZTAhvT2FfRrGog7OuUno9wdTIXFQpkkX0opYoJL6Vrn2emlXkMBTiZYMqChyhR92_Yxd58B0w5nMrfXFf8v7xfAkN46hw"
}

Field	Type	Description
`status`	string	Status of the request
`database_owner`	string	Owner of the database
`database_name`	string	Database name
`pulls`	array<object>	List of pull requests
`next_page_token`	string	page token for the next page of results

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

Body — application/json

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

Field	Type	Description
`status`	string
`message`	string
`database_owner`	string
`database_name`	string

Create a pull request comment#

Here is an example of adding a pull request comment using an authorization token.

Include this header in your request.

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

POST /{owner}/{database}/pulls/{pull_id}/comments

Add comment to pull request

URL https://www.dolthub.com/api/v1alpha1/{owner}/{database}/pulls/{pull_id}/comments

Parameters

Name	In	Type	Required	Description
`owner`	path	string	Yes	Owner of the database Example: `dolthub`
`database`	path	string	Yes	database name Example: `museum-collections`
`pull_id`	path	string	Yes	Pull request ID Example: `66`

Request Body

Content-Type: application/json

Field	Type	Required	Description
`comment`	string	Yes	Comment to be added to the pull request

Responses

200 Success

Body — application/json

{
  "status": "Success",
  "repository_owner": "dolthub",
  "repository_name": "museum-collections",
  "pull_id": "66",
  "comment": "The pull request looks good!"
}

Field	Type	Description
`status`	string	Status of the request
`repository_owner`	string	Owner of the database
`repository_name`	string	Database name
`pull_id`	string	Pull request ID
`comment`	string	Comment added to the pull request

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

Body — application/json

{
  "status": "Error",
  "message": "Error merging a pull request.",
  "repository_owner": "dolthub",
  "repository_name": "museum-collections",
  "pull_id": "66",
  "comment": "The pull request looks good!"
}

Field	Type	Description
`status`	string
`message`	string
`repository_owner`	string	Owner of the database
`repository_name`	string	Database name
`pull_id`	string	Pull request ID
`comment`	string	Comment added to the pull request

Merge pull request#

Here is an example of merging a pull request #66 on a database museum-collections using an authorization token. Note that the merge operation is asynchronous and creates an operation that can be polled to get the result.

To poll the operation and check its status, you can use the operationName in the returned response of the merge request to query the API. Once the operation is complete, the response will contain a job_id field indicating the job that’s running the merge, as well as other information such as the database_owner, database_name, and pull_id.

Keep in mind that the time it takes for the merge operation to complete can vary depending on the size of the pull request and the complexity of the changes being merged.

Include this header in your request with the API token you created.

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

POST /{owner}/{database}/pulls/{pull_id}/merge

Merge a pull request

This endpoint merges a pull request into the destination branch.

URL https://www.dolthub.com/api/v1alpha1/{owner}/{database}/pulls/{pull_id}/merge

Parameters

Name	In	Type	Required	Description
`owner`	path	string	Yes	The name of the database owner. Example: `dolthub`
`database`	path	string	Yes	The name of the database. Example: `museum-collections`
`pull_id`	path	string	Yes	The ID of the pull request to merge. Example: `66`

Responses

200 The pull request was merged successfully.

Body — application/json

{
  "status": "Success",
  "database_owner": "dolthub",
  "database_name": "museum-collections",
  "pull_id": "66",
  "operation_name": "repositoryOwners/dolthub/repositories/museum-collections/jobs/b09a9221-9dcb-4a15-9ca8-a64656946f12",
  "user_operation_name": "users/liuliu/userOperations/5e4834c9-375d-4bbd-bdaf-09eb0734127c"
}

Field	Type	Description
`status`	string
`database_owner`	string
`database_name`	string
`pull_id`	string
`operation_name`	string	The job id that is performing the merge.
`user_operation_name`	string	The operation id that is associated to the merge job. It corresponds to the 'operation_name' field returned in the response of the list operations API.

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

Body — application/json

{
  "status": "Error",
  "message": "Error merging a pull request.",
  "database_owner": "dolthub",
  "database_name": "museum-collections",
  "pull_id": "66"
}

Field	Type	Description
`status`	string
`message`	string
`database_owner`	string
`database_name`	string
`pull_id`	string

Then use GET to poll the operation to check if the merge operation is done.

GET /{owner}/{database}/pulls/{pull_id}/merge

Check merge operation status

Poll the operation to check if the merge operation is done

URL https://www.dolthub.com/api/v1alpha1/{owner}/{database}/pulls/{pull_id}/merge

Parameters

Name	In	Type	Required	Description
`owner`	path	string	Yes	The owner of the database Example: `dolthub`
`database`	path	string	Yes	The database name Example: `museum-collections`
`pull_id`	path	string	Yes	The ID of the pull request Example: `66`
`operationName`	query	string	Yes	The operation name to check Example: `repositoryOwners/dolthub/repositories/museum-collections/jobs/b09a9221-9dcb-4a15-9ca8-a64656946f12`

Responses

200 The status of the merge operation

Body — application/json

{
  "status": "Success",
  "operation_name": "repositoryOwners/dolthub/repositories/museum-collections/jobs/b09a9221-9dcb-4a15-9ca8-a64656946f12",
  "job_created": true,
  "database_owner": "dolthub",
  "database_name": "museum-collections",
  "pull_id": "66",
  "job_status": "In Progress"
}

Field	Type	Description
`status`	string	The status of the operation, Success if the merge was successful
`operation_name`	string	The operation name
`job_created`	boolean	True if the job is created, False otherwise
`database_owner`	string	The owner of the database
`database_name`	string	The name of the database
`pull_id`	string	The ID of the pull request
`job_status`	string	The status of the job, In Progress if the job is still running, Completed if the job is done, Pending if the job is waiting to be run

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

Body — application/json

{
  "status": "Error",
  "message": "Error polling an operation status.",
  "operation_name": "repositoryOwners/dolthub/repositories/museum-collections/jobs/b09a9221-9dcb-4a15-9ca8-a64656946f12"
}

Field	Type	Description
`status`	string
`message`	string
`operation_name`	string