Database

DoltHub provides a database API for fetching and creating data on your database. You can create a database, create a pull request, create a pull request comment, and merge a pull request through these APIs.

Please make sure to send your requests to https://www.dolthub.com instead of https://dolthub.com.

Create database

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

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

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

Create a new Dolt database

post

This API allows you to create a new Dolt database.

Authorizations

APIKeyHeader

authorizationstringRequired

Body

application/json

descriptionstringOptional

A description of the database.

Example: Records from museums around the world.

ownerNamestringOptional

The name of the owner of the database.

Example: dolthub

repoNamestringOptional

The name of the repository for the database.

Example: museum-collections

visibilitystringOptional

The visibility of the database (public or private).

Example: public

Responses

200

Database created successfully.

application/json

statusstringOptionalExample: Success

descriptionstringOptionalExample: Records from museums around the world.

repository_ownerstringOptionalExample: dolthub

repository_namestringOptionalExample: museum-collections

visibilitystringOptionalExample: public

400

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

application/json

post

/api/v1alpha1/database

HTTPcURLJavaScriptPython

POST /api/v1alpha1/database HTTP/1.1
Host: www.dolthub.com
authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 132

{
  "description": "Records from museums around the world.",
  "ownerName": "dolthub",
  "repoName": "museum-collections",
  "visibility": "public"
}

{
  "status": "Success",
  "description": "Records from museums around the world.",
  "repository_owner": "dolthub",
  "repository_name": "museum-collections",
  "visibility": "public"
}

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': '[api token you created]'
}

Create a new pull request

post

This API allows you to create a new pull request.

Authorizations

APIKeyHeader

authorizationstringRequired

Path parameters

ownerstringRequired

The name of the owner of the database.

Example: dolthub

databasestringRequired

The name of the database.

Example: museum-collections

Body

application/json

titlestringOptional

The title of the pull request.

Example: LACMA data

descriptionstringOptional

The description of the pull request.

Example: Records from the Los Angeles County of Museum.

fromBranchOwnerNamestringOptional

The name of the owner of the source branch.

Example: liuliu

fromBranchRepoNamestringOptional

The name of the database containing the source branch.

Example: museum-collections

fromBranchNamestringOptional

The name of the source branch.

Example: lacma

toBranchOwnerNamestringOptional

The name of the owner of the destination branch.

Example: dolthub

toBranchRepoNamestringOptional

The name of the database containing the destination branch.

Example: museum-collections

toBranchNamestringOptional

The name of the destination branch.

Example: main

Responses

200

Pull request created successfully.

application/json

statusstringOptionalExample: Success

titlestringOptional

The title of the pull request.

Example: LACMA data

descriptionstringOptional

The description of the pull request.

Example: Records from the Los Angeles County of Museum.

from_owner_namestringOptional

The name of the owner of the source branch.

Example: liuliu

from_repository_namestringOptional

The name of the database containing the source branch.

Example: museum-collections

from_branch_namestringOptional

The name of the source branch.

Example: lacma

to_owner_namestringOptional

The name of the owner of the destination branch.

Example: dolthub

to_repository_namestringOptional

The name of the database containing the destination branch.

Example: museum-collections

to_branch_namestringOptional

The name of the destination branch.

Example: main

pull_idstringOptional

The id of the created pull request.

Example: 66

400

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

application/json

post

/{owner}/{database}/pulls

HTTPcURLJavaScriptPython

POST /api/v1alpha1/{owner}/{database}/pulls HTTP/1.1
Host: www.dolthub.com
authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 275

{
  "title": "LACMA data",
  "description": "Records from the Los Angeles County of Museum.",
  "fromBranchOwnerName": "liuliu",
  "fromBranchRepoName": "museum-collections",
  "fromBranchName": "lacma",
  "toBranchOwnerName": "dolthub",
  "toBranchRepoName": "museum-collections",
  "toBranchName": "main"
}

{
  "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"
}

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': '[api token you created]'
}

Get pull request by ID

get

Get information about a specific pull request.

Authorizations

APIKeyHeader

authorizationstringRequired

Path parameters

ownerstringRequired

The name of the database owner.

Example: dolthub

databasestringRequired

The name of the database.

Example: museum-collections

pull_idstringRequired

ID of the pull request

Example: 1

Responses

200

Success

application/json

statusstringOptional

Status of the request

Example: Success

database_ownerstringOptional

Owner of the database

Example: dolthub

database_namestringOptional

Database name

Example: museum-collections

pull_idstringOptional

Pull request ID

Example: 1

title:stringOptional

Title of the pull request

Example: Added new data

description:stringOptional

Description of the pull request

Example: Added missing museums, sourced from museums.com

statestringOptional

State of the pull request

Example: merged

from_branch_ownerstringOptional

Owner of database of the source branch.

Example: liuliu

from_branch_databasestringOptional

Database name of source branch.

Example: museum-collections

from_branch_namestringOptional

Name of the source branch.

Example: feature

to_branch_ownerstringOptional

Owner of database of the destination branch.

Example: dolthub

to_branch_databasestringOptional

Database name of destination branch.

Example: museum-collections

to_branch_namestringOptional

Name of the destination branch.

Example: main

created_atstringOptional

Time at which the pull request was created

Example: 2023-07-01T18:00:00Z

authorstringOptional

Author of the pull request

Example: liuliu

400

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

application/json

get

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

HTTPcURLJavaScriptPython

GET /api/v1alpha1/{owner}/{database}/pulls/{pull_id} HTTP/1.1
Host: www.dolthub.com
authorization: YOUR_API_KEY
Accept: */*

{
  "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_name": "feature",
  "to_branch_owner": "dolthub",
  "to_branch_database": "museum-collections",
  "to_branch_name": "main",
  "created_at": "2023-07-01T18:00:00Z",
  "author": "liuliu"
}

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': '[api token you created]'
}

Update Pull Request

patch

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

Authorizations

APIKeyHeader

authorizationstringRequired

Path parameters

ownerstringRequired

The name of the database owner.

Example: dolthub

databasestringRequired

The name of the database.

Example: museum-collections

pull_idstringRequired

ID of the pull request to update.

Example: 1

Body

application/json

titlestringOptional

The updated title of the pull request.

Example: Added new data

descriptionstringOptional

The updated description of the pull request.

Example: Added new data from LACMA museum.

statestringOptional

The updated state of the pull request (can only update to 'closed')

Example: closed

Responses

200

Success

application/json

statusstringOptional

Status of the request

Example: Success

database_ownerstringOptional

Owner of the database

Example: dolthub

database_namestringOptional

Database name

Example: museum-collections

pull_idstringOptional

Updated pull request ID

Example: 1

titlestringOptional

Title of the pull request after update

Example: Added new data

descriptionstringOptional

Description of the pull request after update

Example: Added new data from LACMA museum.

statestringOptional

State of the pull request after update

Example: closed

400

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

application/json

patch

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

HTTPcURLJavaScriptPython

PATCH /api/v1alpha1/{owner}/{database}/pulls/{pull_id} HTTP/1.1
Host: www.dolthub.com
authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 93

{
  "title": "Added new data",
  "description": "Added new data from LACMA museum.",
  "state": "closed"
}

{
  "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"
}

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': '[api token you created]'
}

List pull requests of a database

get

List pull requests

Authorizations

APIKeyHeader

authorizationstringRequired

Path parameters

ownerstringRequired

The name of the database owner.

Example: dolthub

databasestringRequired

The name of the database.

Example: museum-collections

Query parameters

pageTokenstringOptional

The pageToken to get the next page of results

Example: AWE2Nm9uMWQ23FSQ7oRTbCXYTLLvNDhNs5hIFebQFI66FW-SYXGSlh3XcUQ8zmtLQ00QgD0X5FZr5ZTAhvT2FfRrGog7OuUno9wdTIXFQpkkX0opYoJL6Vrn2emlXkMBTiZYMqChyhR92_Yxd58B0w5nMrfXFf8v7xfAkN46hw

filterByStatestringOptional

Filter pulls by state, can be Open, Closed, or Merged.

Example: Open

filterByReviewStatusstringOptional

Filter pulls by review status, can be Approved, AssignedReviewer, Rejected or Reviewed

Example: Approved

querystringOptional

Search by pull request title or author name.

Example: test

Responses

200

Success

application/json

statusstringOptional

Status of the request

Example: Success

database_ownerstringOptional

Owner of the database

Example: dolthub

database_namestringOptional

Database name

Example: museum-collections

next_page_tokenstringOptional

page token for the next page of results

Example: AWE2Nm9uMWQ23FSQ7oRTbCXYTLLvNDhNs5hIFebQFI66FW-SYXGSlh3XcUQ8zmtLQ00QgD0X5FZr5ZTAhvT2FfRrGog7OuUno9wdTIXFQpkkX0opYoJL6Vrn2emlXkMBTiZYMqChyhR92_Yxd58B0w5nMrfXFf8v7xfAkN46hw

400

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

application/json

get

/{owner}/{database}/pulls

HTTPcURLJavaScriptPython

GET /api/v1alpha1/{owner}/{database}/pulls HTTP/1.1
Host: www.dolthub.com
authorization: YOUR_API_KEY
Accept: */*

{
  "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"
}

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': '[api token you created]'
}

Add comment to pull request

post

Authorizations

APIKeyHeader

authorizationstringRequired

Path parameters

ownerstringRequired

Owner of the database

Example: dolthub

databasestringRequired

database name

Example: museum-collections

pull_idstringRequired

Pull request ID

Example: 66

Body

application/json

commentstringRequired

Comment to be added to the pull request

Example: The pull request looks good!

Responses

200

Success

application/json

statusstringOptional

Status of the request

Example: Success

repository_ownerstringOptional

Owner of the database

Example: dolthub

repository_namestringOptional

Database name

Example: museum-collections

pull_idstringOptional

Pull request ID

Example: 66

commentstringOptional

Comment added to the pull request

Example: The pull request looks good!

400

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

application/json

post

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

HTTPcURLJavaScriptPython

POST /api/v1alpha1/{owner}/{database}/pulls/{pull_id}/comments HTTP/1.1
Host: www.dolthub.com
authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 42

{
  "comment": "The pull request looks good!"
}

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

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': '[api token you created]'
}

Merge a pull request

post

This endpoint merges a pull request into the destination branch.

Authorizations

APIKeyHeader

authorizationstringRequired

Path parameters

ownerstringRequired

The name of the database owner.

Example: dolthub

databasestringRequired

The name of the database.

Example: museum-collections

pull_idstringRequired

The ID of the pull request to merge.

Example: 66

Responses

200

The pull request was merged successfully.

application/json

statusstringOptionalExample: Success

database_ownerstringOptionalExample: dolthub

database_namestringOptionalExample: museum-collections

pull_idstringOptionalExample: 66

operation_namestringOptional

The job id that is performing the merge.

Example: repositoryOwners/dolthub/repositories/museum-collections/jobs/b09a9221-9dcb-4a15-9ca8-a64656946f12

user_operation_namestringOptional

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.

Example: users/liuliu/userOperations/5e4834c9-375d-4bbd-bdaf-09eb0734127c

400

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

application/json

post

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

HTTPcURLJavaScriptPython

POST /api/v1alpha1/{owner}/{database}/pulls/{pull_id}/merge HTTP/1.1
Host: www.dolthub.com
authorization: YOUR_API_KEY
Accept: */*

{
  "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"
}

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

Check merge operation status

get

Poll the operation to check if the merge operation is done

Authorizations

APIKeyHeader

authorizationstringRequired

Path parameters

ownerstringRequired

The owner of the database

Example: dolthub

databasestringRequired

The database name

Example: museum-collections

pull_idstringRequired

The ID of the pull request

Example: 66

Query parameters

operationNamestringRequired

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

application/json

statusstringOptional

The status of the operation, Success if the merge was successful

Example: Success

operation_namestringOptional

The operation name

Example: repositoryOwners/dolthub/repositories/museum-collections/jobs/b09a9221-9dcb-4a15-9ca8-a64656946f12

job_createdbooleanOptional

True if the job is created, False otherwise

Example: true

database_ownerstringOptional

The owner of the database

Example: dolthub

database_namestringOptional

The name of the database

Example: museum-collections

pull_idstringOptional

The ID of the pull request

Example: 66

job_statusstringOptional

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

Example: In Progress

400

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

application/json

get

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

HTTPcURLJavaScriptPython

GET /api/v1alpha1/{owner}/{database}/pulls/{pull_id}/merge?operationName=repositoryOwners%2Fdolthub%2Frepositories%2Fmuseum-collections%2Fjobs%2Fb09a9221-9dcb-4a15-9ca8-a64656946f12 HTTP/1.1
Host: www.dolthub.com
authorization: YOUR_API_KEY
Accept: */*

{
  "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"
}

Upload a file

Here is an example of uploading a file lacma.csv to create a table lacma on a database museum-collections using an authorization token. Note that the file import 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 file upload post to query the API. Once the operation is complete, the response will contain a job_id field indicating the job that's running the file import as well as the id of the pull request that's created when the import job is completed.

Keep in mind that the time it takes for the import operation to complete can vary depending on the size of the file and the complexity of the changes being applied to the database. The file size limit is 100 MB.

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

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

To upload the file, include two fields in the request body, file and params, the file should be type of Blob, and params should be a JSON object.

Upload a file to a DoltHub database

post

This endpoint allows you to upload a file to DoltHub to create, update, overwrite, or replace a table.

Authorizations

APIKeyHeader

authorizationstringRequired

Path parameters

ownerstringRequired

The name of the database owner.

Example: dolthub

databasestringRequired

The name of the database.

Example: museum-collections

Body

multipart/form-data

filestring · binaryOptional

The file to be uploaded.

Responses

200

Pull request created successfully.

application/json

statusstringOptionalExample: Success

database_ownerstringOptionalExample: dolthub

database_namestringOptionalExample: museum-collections

branch_namestringOptionalExample: main

table_namestringOptionalExample: lacma

operation_namestringOptional

The job id that is performing the upload.

Example: repositoryOwners/dolthub/repositories/museum-collections/jobs/b09a9221-9dcb-4a15-9ca8-a64656946f12

user_operation_namestringOptional

The operation id that is associated to the upload job. It corresponds to the 'operation_name' field returned in the response of the list operations API.

Example: users/liuliu/userOperations/5e4834c9-375d-4bbd-bdaf-09eb0734127c

400

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

application/json

post

/{owner}/{database}/upload

HTTPcURLJavaScriptPython

POST /api/v1alpha1/{owner}/{database}/upload HTTP/1.1
Host: www.dolthub.com
authorization: YOUR_API_KEY
Content-Type: multipart/form-data
Accept: */*
Content-Length: 149

{
  "file": "binary",
  "params": {
    "tableName": "lacma",
    "fileName": "lacma.csv",
    "branchName": "main",
    "fileType": "Csv",
    "importOp": "Create",
    "primaryKeys": [
      "id"
    ]
  }
}

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

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

Check import operation status

get

Poll the operation to check if the file import operation is done

Authorizations

APIKeyHeader

authorizationstringRequired

Path parameters

ownerstringRequired

The owner of the database

Example: dolthub

databasestringRequired

The database name

Example: museum-collections

Query parameters

branchstringRequired

The name of the branch to upload the file to.

Example: main

operationNamestringRequired

The operation name to check

Example: repositoryOwners/dolthub/repositories/museum-collections/jobs/b09a9221-9dcb-4a15-9ca8-a64656946f12

Responses

200

The status of the file import operation

application/json

statusstringOptional

The status of the operation, Success if the file import was successful

Example: Success

operation_namestringOptional

The operation name

Example: repositoryOwners/dolthub/repositories/museum-collections/jobs/b09a9221-9dcb-4a15-9ca8-a64656946f12

job_createdbooleanOptional

True if the import job is created, False otherwise

Example: true

database_ownerstringOptional

The owner of the database

Example: dolthub

database_namestringOptional

The name of the database

Example: museum-collections

pull_idstringOptional

The ID of the pull request that the import job created. This is only present if the import job is completed

Example: 66

job_statusstringOptional

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

Example: Completed

400

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

application/json

get

/{owner}/{database}/upload

HTTPcURLJavaScriptPython

GET /api/v1alpha1/{owner}/{database}/upload?branch=main&operationName=repositoryOwners%2Fdolthub%2Frepositories%2Fmuseum-collections%2Fjobs%2Fb09a9221-9dcb-4a15-9ca8-a64656946f12 HTTP/1.1
Host: www.dolthub.com
authorization: YOUR_API_KEY
Accept: */*

{
  "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": "Completed"
}

Here is an example of uploading a CSV file to create a table through this api endpoint in Javascript, you can reference the dolt table import documentation for additional information.:

Please make sure to send your requests to https://www.dolthub.com/api/v1alpha1/{owner}/{database}/upload instead of https://www.dolthub.com/api/v1alpha1/{owner}/{database}/upload/, do not need the last /.

const fs = require("fs");

const url =
  "https://www.dolthub.com/api/v1alpha1/dolthub/museum-collections/upload";


const headers = {
  "Content-Type": "application/json",
  authorization: [api token you created],
};

const filePath = "lacma.csv";

fetchFileAndSend(filePath);

async function fetchFileAndSend(filePath) {
  const params = {
    tableName: "lacma",
    fileName: "lacma.csv",
    branchName:"main",
    fileType: "Csv",
    importOp: "Create",
    primaryKeys: ["id"],
  };

  const formData = new FormData();
  const fileData = fs.readFileSync(filePath);
  const blob = new Blob([buffer], { type: "application/octet-stream" });
  await formData.append("file", blob, "lacma.csv");
  formData.append("params", JSON.stringify(params));

  fetch(url, {
    method: "POST",
    headers,
    body: formData,
  })
   .then((response) => {
        // process response
    })
    .catch((error) => {
      // process error
    });
}

And an example of polling the job status in Javascript:

function pollOperation(op_name,branch_name) {
  const url = `https: //www.dolthub.com/api/v1alpha1/dolthub/museum-collections/upload?branchName=${branch_name}&operationName=${op_name}`;
  const headers = {
    "Content-Type": "application/json",
    authorization: [api token you created],
  };

  while (true) {
    const res = await fetch(url, {
      method: "GET",
      headers,
    });
    const data = await res.json();
    if (data.job_created) {
      return data;
    } else {
      await new Promise(r => setTimeout(r, 1000));
    }
  }

}

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': '[api token you created]'
}

Create Branch

post

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

Authorizations

APIKeyHeader

authorizationstringRequired

Path parameters

ownerstringRequired

The name of the owner of the database.

Example: dolthub

databasestringRequired

The name of the database.

Example: museum-collections

Body

application/json

revisionTypestringRequired

The type of revision, can be either 'branch', 'ref' or 'commit'.

Example: branch

revisionNamestringRequired

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.

Example: main

newBranchNamestringRequired

The name of the new branch.

Example: feature-branch

Responses

200

Success

application/json

statusstringOptional

Status of the create branch operation

Example: Success

database_ownerstringOptional

Owner of the database

Example: dolthub

database_namestringOptional

Database name

Example: museum-collections

new_branch_namestringOptional

Name of the new branch

Example: feature-branch

revision_typestringOptional

Type of the revision

Example: branch

revision_namestringOptional

Name of the revision

Example: main

400

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

application/json

post

/{owner}/{database}/branches

HTTPcURLJavaScriptPython

POST /api/v1alpha1/{owner}/{database}/branches HTTP/1.1
Host: www.dolthub.com
authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 80

{
  "revisionType": "branch",
  "revisionName": "main",
  "newBranchName": "feature-branch"
}

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

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': '[api token you created]'
}

List Branches

get

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

Authorizations

APIKeyHeader

authorizationstringRequired

Path parameters

ownerstringRequired

The name of the owner of the database.

Example: dolthub

databasestringRequired

The name of the database.

Example: museum-collections

Responses

200

Success

application/json

statusstringOptional

Status of the request.

Example: Success

database_ownerstringOptional

Owner of the database

Example: dolthub

database_namestringOptional

Database name

Example: museum-collections

400

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

application/json

get

/{owner}/{database}/branches

HTTPcURLJavaScriptPython

GET /api/v1alpha1/{owner}/{database}/branches HTTP/1.1
Host: www.dolthub.com
authorization: YOUR_API_KEY
Accept: */*

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

Create a tag

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

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

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

Create Tag

post

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

Authorizations

APIKeyHeader

authorizationstringRequired

Path parameters

ownerstringRequired

The name of the owner of the database.

Example: dolthub

databasestringRequired

The name of the database.

Example: museum-collections

Body

application/json

tagNamestringRequired

The name of the tag.

Example: v1

tagMessagestringRequired

The description of the tag.

Example: First version of the database

revisionTypestringRequired

The type of revision, can be either 'branch', 'ref' or 'commit'.

Example: branch

revisionNamestringRequired

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.

Example: main

Responses

200

Success

application/json

statusstringOptional

Status of the create branch operation

Example: Success

database_ownerstringOptional

Owner of the database

Example: dolthub

database_namestringOptional

Database name

Example: museum-collections

tag_namestringOptional

Name of the tag

Example: v1

tag_descriptionstringOptional

Description of the tag

Example: First version of the database

revision_typestringOptional

Type of the revision

Example: branch

revision_namestringOptional

Name of the revision

Example: main

400

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

application/json

post

/{owner}/{database}/tags

HTTPcURLJavaScriptPython

POST /api/v1alpha1/{owner}/{database}/tags HTTP/1.1
Host: www.dolthub.com
authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 107

{
  "tagName": "v1",
  "tagMessage": "First version of the database",
  "revisionType": "branch",
  "revisionName": "main"
}

{
  "status": "Success",
  "database_owner": "dolthub",
  "database_name": "museum-collections",
  "tag_name": "v1",
  "tag_description": "First version of the database",
  "revision_type": "branch",
  "revision_name": "main"
}

List tags

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

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

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

List Tags

get

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

Authorizations

APIKeyHeader

authorizationstringRequired

Path parameters

ownerstringRequired

The name of the owner of the database.

Example: dolthub

databasestringRequired

The name of the database.

Example: museum-collections

Responses

200

Success

application/json

statusstringOptional

Status of the request

Example: Success

database_ownerstringOptional

Owner of the database

Example: dolthub

database_namestringOptional

Database name

Example: museum-collections

400

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

application/json

get

/{owner}/{database}/tags

HTTPcURLJavaScriptPython

GET /api/v1alpha1/{owner}/{database}/tags HTTP/1.1
Host: www.dolthub.com
authorization: YOUR_API_KEY
Accept: */*

{
  "status": "Success",
  "database_owner": "dolthub",
  "database_name": "museum-collections",
  "tags": [
    {
      "tag_name": "v1",
      "tag_description": "First version of the database",
      "tagged_at": "2023-03-31T18:00:00Z"
    }
  ]
}

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': '[api token you created]'
}

{% swagger src="../../../.gitbook/assets/dolthub-api/createRelease.json" path="/{owner}/{database}/releases" method="post" % } createRelease.json

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': '[api token you created]'
}

List Releases

get

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

Authorizations

APIKeyHeader

authorizationstringRequired

Path parameters

ownerstringRequired

The name of the owner of the database.

Example: dolthub

databasestringRequired

The name of the database.

Example: museum-collections

Query parameters

next_page_tokenstringOptional

The next page token.

Example: 1234567890

Responses

200

Success

application/json

statusstringOptional

Status of the request

Example: Success

database_ownerstringOptional

Owner of the database

Example: dolthub

database_namestringOptional

Database name

Example: museum-collections

next_page_tokenstringOptional

Next page token

Example: 1234567890

400

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

application/json

get

/{owner}/{database}/releases

HTTPcURLJavaScriptPython

GET /api/v1alpha1/{owner}/{database}/releases HTTP/1.1
Host: www.dolthub.com
authorization: YOUR_API_KEY
Accept: */*

{
  "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"
    }
  ]
}

List operations

DoltHub provides support for asynchronous operations, including merging, SQL writes, and file importing. When you execute one of these operations from the API, you will get an operation name that you can poll using another endpoint to check the operation status and other information.

This API endpoint lets you monitor the status of all the operations you started in one place without needing to poll the endpoints for singular operations. These operations have error and metadata fields which contain useful information for troubleshooting and debugging.

For example, if you have executed a few SQL write queries using that API endpoint, you can list those operations using the operationType query parameter to filter for SqlWrite operations. The metadata will show the query executed, database and branch that the query ran on, as well as any syntax or other errors you may have encountered.

Here's an example of how to list SqlWrite operations initiated by user liuliu using an authorization token.

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

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

List operations

get

This API endpoint allows you to list all operations that are created by the user.

Authorizations

APIKeyHeader

authorizationstringRequired

Path parameters

usernamestringRequired

The name of the user who initiated the operations. This user's name must match the user associated with the api token.

Example: liuliu

Query parameters

operationTypestringOptional

Specific type of operation for this query. Supported operation types are SqlWrite, SqlRead, Import, Merge, Migrate.

Example: SqlWrite

pageTokenstringOptional

Token for the next page of results

Example: AWE2Nm9uMWQ26pQQpqLNLXu7a60647lpiZoDFrf5WDGHo68XNC-rfr068rymbEdUHCXidRxx7_fwGBMSzQi6C_D50NcJFXm0BwRnGmmHEL4T4xxkWoX3sL5mKD-PuMRuxeHPsR0NB5Rzi70jGzblVlfBTIHPJ20c630pNLrI_spxH0tYTzMnQ4uPpr3ub9P50FEH9i4Au0gUkmvj8NUibbGWi-R1AJYplEPr=

Responses

200

Success

application/json

statusstringOptional

Status of the request.

Example: Success

next_page_tokenstringOptional

Token for the next page of results

Example: AWE2Nm9uMWQ26pQQpqLNLXu7a60647lpiZoDFrf5WDGHo68XNC-rfr068rymbEdUHCXidRxx7_fwGBMSzQi6C_D50NcJFXm0BwRnGmmHEL4T4xxkWoX3sL5mKD-PuMRuxeHPsR0NB5Rzi70jGzblVlfBTIHPJ20c630pNLrI_spxH0tYTzMnQ4uPpr3ub9P50FEH9i4Au0gUkmvj8NUibbGWi-R1AJYplEPr=

400

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

application/json

get

/users/{username}/operations

HTTPcURLJavaScriptPython

GET /api/v1alpha1/users/{username}/operations HTTP/1.1
Host: www.dolthub.com
authorization: YOUR_API_KEY
Accept: */*

{
  "status": "Success",
  "operations": [
    {
      "operation_name": "users/liuliu/userOperations/5e4834c9-375d-4bbd-bdaf-09eb0734127c",
      "creator": "liuliu",
      "description": "Run query CREATE TABLE tablename (\\n  pk INT,\\n  col1 VARCHAR(255),\\n  PRIMARY KEY (pk)\\n);",
      "operation_type": "SqlWrite",
      "operation_status": "liuliu",
      "error": "table with name tablename already exists",
      "metadata": "{'from_branch_name':'main','from_repo_name':'api-db','from_repo_owner':'liuliu','sql_query':'CREATE TABLE tablename (\\n  pk INT,\\n  col1 VARCHAR(255),\\n  PRIMARY KEY (pk)\\n);','to_branch_name':'main','to_repo_name':'api-db','to_repo_owner':'liuliu'}",
      "created_at": "2024-01-09T22:19:49.000Z",
      "updated_at": "2024-01-09T22:19:50.000Z"
    }
  ],
  "next_page_token": "AWE2Nm9uMWQ26pQQpqLNLXu7a60647lpiZoDFrf5WDGHo68XNC-rfr068rymbEdUHCXidRxx7_fwGBMSzQi6C_D50NcJFXm0BwRnGmmHEL4T4xxkWoX3sL5mKD-PuMRuxeHPsR0NB5Rzi70jGzblVlfBTIHPJ20c630pNLrI_spxH0tYTzMnQ4uPpr3ub9P50FEH9i4Au0gUkmvj8NUibbGWi-R1AJYplEPr="
}

List jobs

DoltHub performs certain asynchronous operations through job execution, including merging, importing, SQL reading, and migrating. When these operations are initiated via the API, you receive an operation name that includes the job ID.

This API endpoint lets you monitor the status of jobs started in a specific database.

Here is an example of how to list all the jobs on a database museum-collections using an authorization token.

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

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

List jobs

get

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

Authorizations

APIKeyHeader

authorizationstringRequired

Path parameters

ownerstringRequired

The name of the owner of the database.

Example: dolthub

databasestringRequired

The name of the database.

Example: museum-collections

Responses

200

Success

application/json

statusstringOptional

Status of the request.

Example: Success

database_ownerstringOptional

Name of the owner of the database

Example: dolthub

database_namestringOptional

Name of the database

Example: museum-collections

next_page_tokenstringOptional

Token for the next page of results

Example: AWE2Nm9uMWQ2M84_Q_ajmYOdCDIg_Ac8OuedPyAGoTT3TsBNnTSE29QPb6oJmZdbjYwdFjTwu6_ioVx4nsp3eCPoO5zyATKGsauocvy4onXjoWGfqmatl2dcm-2Ks45NPT0qRPu37HjVcaC0Qj2X5_KHcYI70fzOLn1RogexmtBlf_AtI3os4DntzhZtfp9GFtHiVekppo_26viXiKcjy0DpKay5

400

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

application/json

get

/{owner}/{database}/jobs

HTTPcURLJavaScriptPython

GET /api/v1alpha1/{owner}/{database}/jobs HTTP/1.1
Host: www.dolthub.com
authorization: YOUR_API_KEY
Accept: */*

{
  "status": "Success",
  "database_owner": "dolthub",
  "database_name": "museum-collections",
  "jobs": [
    {
      "job_id": "repositoryOwners/dolthub/repositories/museum-collections/jobs/aa37149c-61c3-4ce2-b3d8-694d2a152257",
      "creator": "liuliu",
      "description": "Merge pull request #9",
      "job_type": "Merge",
      "status": "Failed",
      "created_at": "2024-01-09T22:19:49.000Z",
      "error": "failed to push to branch"
    }
  ],
  "next_page_token": "AWE2Nm9uMWQ2M84_Q_ajmYOdCDIg_Ac8OuedPyAGoTT3TsBNnTSE29QPb6oJmZdbjYwdFjTwu6_ioVx4nsp3eCPoO5zyATKGsauocvy4onXjoWGfqmatl2dcm-2Ks45NPT0qRPu37HjVcaC0Qj2X5_KHcYI70fzOLn1RogexmtBlf_AtI3os4DntzhZtfp9GFtHiVekppo_26viXiKcjy0DpKay5"
}