Database#

DoltHub databases and their metadata.

Databases#

Create a database#

POST /api/v2/databases

Creates a database under the named owner (a user or organization). The caller’s credentials must allow creating under that owner — creating for yourself works as long as you authenticate; creating for an organization requires membership with the appropriate role. Returns the new Database resource on 201. If a database with the same {owner, name} already exists, the response is 409 Conflict.

Request body

Example request

curl -X POST 'https://www.dolthub.com/api/v2/databases' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"owner":"dolthub","name":"us-jails","visibility":"public"}'

Responses

Example response 201

{
  "data": {
    "owner": "dolthub",
    "name": "us-jails",
    "description": "Open data about incarceration in the United States.",
    "visibility": "public",
    "fork_network_count": 3,
    "star_count": 42,
    "size_bytes": 10485760,
    "last_write_at": "2024-01-15T12:34:56Z"
  }
}

Get a database#

GET /api/v2/databases/{owner}/{database}

Returns the metadata for the database {owner}/{database}. Public databases are readable without authentication; private databases require a credential with access (and return 404 otherwise, so their existence isn’t leaked).

Parameters

Example request

curl -X GET 'https://www.dolthub.com/api/v2/databases/{owner}/{database}' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

Example response 200

{
  "data": {
    "owner": "dolthub",
    "name": "us-jails",
    "description": "Open data about incarceration in the United States.",
    "visibility": "public",
    "fork_network_count": 3,
    "star_count": 42,
    "size_bytes": 10485760,
    "last_write_at": "2024-01-15T12:34:56Z"
  }
}

SQL#

Run a read-only SQL query#

GET /api/v2/databases/{owner}/{database}/sql

Executes a read-only SQL query against the database at the given revision and returns the result rows, the column schema, and the query-execution status. Read queries are not paginated — the full row set comes back in one response, bounded by limit (default 1000) and the server-enforced row cap. For larger result sets, refine the query (LIMIT/WHERE/SELECT fewer columns) or use the phase-4 async SQL job. SQL-level errors (syntax errors, missing tables, timeouts, row-limit exceeded) come back as 200 with status: "error" | "timeout" | "row_limit" | "not_workspace" and a human-readable message — they are query-level conditions, not transport-level failures. HTTP 4xx / 5xx are reserved for transport-level problems (auth, the database doesn’t exist, malformed request). Public databases are readable without authentication; private databases require a credential with access (and return 404 otherwise, so their existence isn’t leaked).

Parameters

Example request

curl -X GET 'https://www.dolthub.com/api/v2/databases/{owner}/{database}/sql' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

Example response 200

{
  "data": {
    "columns": [
      {
        "name": "state_name",
        "type": "VARCHAR(255)",
        "is_primary_key": true,
        "source_table": "jails"
      },
      {
        "name": "count",
        "type": "BIGINT",
        "is_primary_key": false,
        "source_table": ""
      }
    ],
    "rows": [
      [
        "California",
        "162"
      ],
      [
        "Texas",
        "108"
      ],
      [
        null,
        "0"
      ]
    ],
    "status": "success",
    "warnings": []
  }
}

Run a read-only SQL query (large-query variant)#

POST /api/v2/databases/{owner}/{database}/sql

Identical to GET /sql but accepts the query in the request body to avoid the browser/proxy URL-length limit (~4–8 KB) that ?q= hits for large SQL statements. Use this when the query is too long for a query string; prefer GET for short queries (simpler to cache and log). The response shape is identical.

Parameters

Request body

Example request

curl -X POST 'https://www.dolthub.com/api/v2/databases/{owner}/{database}/sql' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"ref":"main","q":"SELECT name, year FROM jails WHERE state = 'California' LIMIT 10"}'

Responses

Example response 200

{
  "data": {
    "columns": [
      {
        "name": "state_name",
        "type": "VARCHAR(255)",
        "is_primary_key": true,
        "source_table": "jails"
      },
      {
        "name": "count",
        "type": "BIGINT",
        "is_primary_key": false,
        "source_table": ""
      }
    ],
    "rows": [
      [
        "California",
        "162"
      ],
      [
        "Texas",
        "108"
      ],
      [
        null,
        "0"
      ]
    ],
    "status": "success",
    "warnings": []
  }
}

Branches#

List branches#

GET /api/v2/databases/{owner}/{database}/branches

Returns the branches of the database {owner}/{database}, ordered by the backend. Cursor-paginated via page_token (request) / meta.next_page_token (response); when next_page_token is absent or empty there are no further pages. Public databases are readable without authentication; private databases require a credential with access (and return 404 otherwise, so their existence isn’t leaked).

Parameters

Example request

curl -X GET 'https://www.dolthub.com/api/v2/databases/{owner}/{database}/branches' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

Example response 200

{
  "data": [
    {
      "name": "main",
      "head_commit_sha": "vt1u8gdsovtj0qq2qmd6he7n5o4mq2qm",
      "last_updated_at": "2024-01-15T12:34:56Z"
    }
  ],
  "meta": {
    "next_page_token": "eyJvZmZzZXQiOjI1fQ"
  }
}

Create a branch#

POST /api/v2/databases/{owner}/{database}/branches

Creates a new branch in {owner}/{database} pointing at the source revision named by from. Authentication required; the caller must have write access. Returns the new Branch resource on 201. A 409 Conflict comes back if a branch with the same name already exists.

Parameters

Request body

Example request

curl -X POST 'https://www.dolthub.com/api/v2/databases/{owner}/{database}/branches' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"name":"feature-x","from":0}'

Responses

Example response 201

{
  "data": {
    "name": "main",
    "head_commit_sha": "vt1u8gdsovtj0qq2qmd6he7n5o4mq2qm",
    "last_updated_at": "2024-01-15T12:34:56Z"
  }
}

Tags#

List tags#

GET /api/v2/databases/{owner}/{database}/tags

Returns the tags of the database {owner}/{database}, ordered by the backend. Cursor-paginated via page_token (request) / meta.next_page_token (response); when next_page_token is absent or empty there are no further pages. Public databases are readable without authentication; private databases require a credential with access (and return 404 otherwise, so their existence isn’t leaked).

Parameters

Example request

curl -X GET 'https://www.dolthub.com/api/v2/databases/{owner}/{database}/tags' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

Example response 200

{
  "data": [
    {
      "name": "v1.0.0",
      "commit_sha": "vt1u8gdsovtj0qq2qmd6he7n5o4mq2qm",
      "message": "First public release.",
      "tagged_at": "2024-01-15T12:34:56Z"
    }
  ],
  "meta": {
    "next_page_token": "eyJvZmZzZXQiOjI1fQ"
  }
}

Create a tag#

POST /api/v2/databases/{owner}/{database}/tags

Creates a new tag in {owner}/{database} pointing at the source revision named by from. The optional message makes the tag annotated; omitted yields a lightweight tag. Returns the new Tag resource on 201. Authentication required; the caller must have write access. A 409 Conflict comes back if a tag with the same name already exists.

Parameters

Request body

Example request

curl -X POST 'https://www.dolthub.com/api/v2/databases/{owner}/{database}/tags' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"name":"v1.0.0","from":0}'

Responses

Example response 201

{
  "data": {
    "name": "v1.0.0",
    "commit_sha": "vt1u8gdsovtj0qq2qmd6he7n5o4mq2qm",
    "message": "First public release.",
    "tagged_at": "2024-01-15T12:34:56Z"
  }
}

Forks#

List forks#

GET /api/v2/databases/{owner}/{database}/forks

Returns the databases that have been directly forked from {owner}/{database} — immediate children only. Forks-of-forks are not flattened into the list; use fork_network_count on the Database resource for the transitive total. Topology context (parent, network_root, total fork_network_count) lives on the Database resource. Pagination (page_token / meta.next_page_token) will be added when the backend supports it; until then the full list is returned in one response. Public databases are readable without authentication; private databases require a credential with access (and return 404 otherwise, so their existence isn’t leaked).

Parameters

Example request

curl -X GET 'https://www.dolthub.com/api/v2/databases/{owner}/{database}/forks' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

Example response 200

{
  "data": [
    {
      "owner": "dolthub",
      "name": "us-jails"
    }
  ],
  "meta": {
    "next_page_token": "eyJvZmZzZXQiOjI1fQ"
  }
}

Fork a database#

POST /api/v2/databases/{owner}/{database}/forks

Forks {owner}/{database} into owner’s namespace. Returns 202 with an OperationRef; follow OperationRef.href to poll for completion (operation IDs contain slashes and must not be interpolated raw into path templates). The caller must have read access on the source database and may only fork into a namespace they own. Duplicate forks (same source forked twice into the same owner) surface as 422 via the standard error model. Authentication is required.

Parameters

Request body

Example request

curl -X POST 'https://www.dolthub.com/api/v2/databases/{owner}/{database}/forks' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"owner":"taylor"}'

Responses

Releases#

List releases#

GET /api/v2/databases/{owner}/{database}/releases

Returns the releases of the database {owner}/{database}, ordered by the backend. Cursor-paginated via page_token (request) / meta.next_page_token (response); when next_page_token is absent or empty there are no further pages. Public databases are readable without authentication; private databases require a credential with access (and return 404 otherwise, so their existence isn’t leaked).

Parameters

Example request

curl -X GET 'https://www.dolthub.com/api/v2/databases/{owner}/{database}/releases' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

Example response 200

{
  "data": [
    {
      "tag": "v1.0.0",
      "title": "First public release",
      "commit_sha": "vt1u8gdsovtj0qq2qmd6he7n5o4mq2qm",
      "description": "## Highlights\n- new join planner",
      "created_at": "2024-01-15T12:34:56Z",
      "updated_at": "2024-01-15T12:34:56Z"
    }
  ],
  "meta": {
    "next_page_token": "eyJvZmZzZXQiOjI1fQ"
  }
}

Create a release#

POST /api/v2/databases/{owner}/{database}/releases

Creates a release in {owner}/{database} pinned to the commit named by commit_sha and published under tag. When create_tag_if_not_exists is true and no tag with that name exists, the backend creates one pointing at the same commit; otherwise the tag must already exist and point at the same commit. Returns the new Release resource on 201. Authentication required; the caller must have write access. A 409 Conflict comes back if a release with the same tag already exists.

Parameters

Request body

Example request

curl -X POST 'https://www.dolthub.com/api/v2/databases/{owner}/{database}/releases' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"tag":"v1.0.0","title":"First public release","commit_sha":"vt1u8gdsovtj0qq2qmd6he7n5o4mq2qm"}'

Responses

Example response 201

{
  "data": {
    "tag": "v1.0.0",
    "title": "First public release",
    "commit_sha": "vt1u8gdsovtj0qq2qmd6he7n5o4mq2qm",
    "description": "## Highlights\n- new join planner",
    "created_at": "2024-01-15T12:34:56Z",
    "updated_at": "2024-01-15T12:34:56Z"
  }
}

Pull Requests#

List pull requests#

GET /api/v2/databases/{owner}/{database}/pulls

Returns the pull requests for the database {owner}/{database}, ordered by the backend. Cursor-paginated via page_token (request) / meta.next_page_token (response); when next_page_token is absent or empty there are no further pages. Public databases are readable without authentication; private databases require a credential with access (and return 404 otherwise, so their existence isn’t leaked).

Parameters

Example request

curl -X GET 'https://www.dolthub.com/api/v2/databases/{owner}/{database}/pulls' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

Example response 200

{
  "data": [
    {
      "pull_number": 42,
      "title": "Fix join planner regression",
      "description": "Fixes #99.",
      "state": "open",
      "created_at": "2024-01-15T12:34:56Z",
      "creator": "dolthub"
    }
  ],
  "meta": {
    "next_page_token": "eyJvZmZzZXQiOjI1fQ"
  }
}

Create a pull request#

POST /api/v2/databases/{owner}/{database}/pulls

Opens a new pull request in {owner}/{database}. to_branch.database must equal the URL’s {owner}/{database}. from_branch.database is usually the same; for a cross-fork pull it points at a fork — in that case the caller must have read access on the fork’s database and the fork’s network root must match the target. Returns the new Pull resource on 201. Authentication is required.

Parameters

Request body

Example request

curl -X POST 'https://www.dolthub.com/api/v2/databases/{owner}/{database}/pulls' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"title":"Fix join planner regression","from_branch":{"database":{"owner":"dolthub","name":"us-jails"},"branch_name":"my-feature"},"to_branch":{"database":{"owner":"dolthub","name":"us-jails"},"branch_name":"my-feature"}}'

Responses

Example response 201

{
  "data": {
    "pull_number": 42,
    "title": "Fix join planner regression",
    "description": "Fixes #99.",
    "state": "open",
    "from_branch": {
      "database": {
        "owner": "dolthub",
        "name": "us-jails"
      },
      "branch_name": "my-feature"
    },
    "to_branch": {
      "database": {
        "owner": "dolthub",
        "name": "us-jails"
      },
      "branch_name": "main"
    },
    "created_at": "2024-01-15T12:34:56Z",
    "creator": "dolthub"
  }
}

Get a pull request#

GET /api/v2/databases/{owner}/{database}/pulls/{pull_number}

Returns the pull request {pull_number} in the database {owner}/{database}. Unlike the list endpoint, the per-pull resource exposes structured from_branch / to_branch references, each carrying the database the branch lives in — necessary to disambiguate cross-fork pulls where the source branch lives in a different repository. Public databases are readable without authentication; private databases require a credential with access (and return 404 otherwise, so their existence isn’t leaked).

Parameters

Example request

curl -X GET 'https://www.dolthub.com/api/v2/databases/{owner}/{database}/pulls/{pull_number}' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

Example response 200

{
  "data": {
    "pull_number": 42,
    "title": "Fix join planner regression",
    "description": "Fixes #99.",
    "state": "open",
    "from_branch": {
      "database": {
        "owner": "dolthub",
        "name": "us-jails"
      },
      "branch_name": "my-feature"
    },
    "to_branch": {
      "database": {
        "owner": "dolthub",
        "name": "us-jails"
      },
      "branch_name": "main"
    },
    "created_at": "2024-01-15T12:34:56Z",
    "creator": "dolthub"
  }
}

Update a pull request#

PATCH /api/v2/databases/{owner}/{database}/pulls/{pull_number}

Partially updates the pull request {pull_number} in {owner}/{database}. The body carries only the fields the caller is changing — any subset of title, description, state; at least one must be present. state is restricted to the writable transitions (open ↔ closed); merging happens via the dedicated merge operation (phase 4), not by writing state here. Returns the canonical Pull resource on 200. Authentication required.

Parameters

Request body

Example request

curl -X PATCH 'https://www.dolthub.com/api/v2/databases/{owner}/{database}/pulls/{pull_number}' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

Responses

Example response 200

{
  "data": {
    "pull_number": 42,
    "title": "Fix join planner regression",
    "description": "Fixes #99.",
    "state": "open",
    "from_branch": {
      "database": {
        "owner": "dolthub",
        "name": "us-jails"
      },
      "branch_name": "my-feature"
    },
    "to_branch": {
      "database": {
        "owner": "dolthub",
        "name": "us-jails"
      },
      "branch_name": "main"
    },
    "created_at": "2024-01-15T12:34:56Z",
    "creator": "dolthub"
  }
}

List a pull request’s comments#

GET /api/v2/databases/{owner}/{database}/pulls/{pull_number}/comments

Returns the top-level comments on pull request {pull_number} in {owner}/{database}, in the order the backend returns them. The backend doesn’t paginate comments today, so the full list is returned in one response; if a comment volume hot spot appears, page_token / meta.next_page_token will be wired through without changing the resource shape. Diff-line comments and review comments are separate resources (not in v2 yet). Public databases are readable without authentication; private databases require a credential with access (and return 404 otherwise, so their existence isn’t leaked).

Parameters

Example request

curl -X GET 'https://www.dolthub.com/api/v2/databases/{owner}/{database}/pulls/{pull_number}/comments' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

Example response 200

{
  "data": [
    {
      "comment_id": "1c8f3b1e-5d2e-4a3a-9f2b-0e7a6d5c4b3a",
      "author": "alice",
      "body": "LGTM — one nit on the join planner case.",
      "created_at": "2024-01-15T12:34:56Z",
      "updated_at": "2024-01-15T12:34:56Z"
    }
  ],
  "meta": {
    "next_page_token": "eyJvZmZzZXQiOjI1fQ"
  }
}

Add a top-level comment to a pull request#

POST /api/v2/databases/{owner}/{database}/pulls/{pull_number}/comments

Posts a new top-level comment on pull request {pull_number} in {owner}/{database}. The body carries only the comment text; author and timestamps are server-assigned from the authenticated caller and the server clock. Returns the new PullComment on 201. Diff-line and review comments are separate resources (not in v2 yet).

Parameters

Request body

Example request

curl -X POST 'https://www.dolthub.com/api/v2/databases/{owner}/{database}/pulls/{pull_number}/comments' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"body":"LGTM — one nit on the join planner case."}'

Responses

Example response 201

{
  "data": {
    "comment_id": "1c8f3b1e-5d2e-4a3a-9f2b-0e7a6d5c4b3a",
    "author": "alice",
    "body": "LGTM — one nit on the join planner case.",
    "created_at": "2024-01-15T12:34:56Z",
    "updated_at": "2024-01-15T12:34:56Z"
  }
}

Merge a pull request#

POST /api/v2/databases/{owner}/{database}/pulls/{pull_number}/merge

Kicks off a merge of pull {pull_number} in {owner}/{database}. Returns 202 with an OperationRef; poll GET /api/v2/operations/{id} until status is succeeded (the operation’s result.pull_id echoes the merged pull) or failed. The caller must have write access on the database. Preconditions like “pull is already merged” or “has conflicts” surface as 422 via the standard error model rather than being pre-checked here. Authentication is required.

Parameters

Example request

curl -X POST 'https://www.dolthub.com/api/v2/databases/{owner}/{database}/pulls/{pull_number}/merge' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

Responses

Imports#

Initialize a multipart upload for an import#

POST /api/v2/databases/{owner}/{database}/imports/uploads

Starts a multipart upload session and returns the pre-signed part URLs the client uses to upload the source file directly to object storage. Once every part is uploaded, call POST /api/v2/databases/{owner}/{database}/imports with the returned token, contents_key, and the collected completed_parts to create the import operation. Authentication is required.

Parameters

Request body

Example request

curl -X POST 'https://www.dolthub.com/api/v2/databases/{owner}/{database}/imports/uploads' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"content_length":1048576,"num_parts":4,"file_type":"csv"}'

Responses

Create an import operation#

POST /api/v2/databases/{owner}/{database}/imports

Imports the previously-uploaded file into {owner}/{database} as the table named in the body. The upload (token, contents_key, and the parts uploaded against the URLs returned by POST .../imports/uploads) must already be complete; the import itself runs asynchronously. Returns 202 + an OperationRef; poll GET /api/v2/operations/{id} until status is succeeded or failed. Authentication is required.

Parameters

Request body

Example request

curl -X POST 'https://www.dolthub.com/api/v2/databases/{owner}/{database}/imports' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"branch_name":"main","table_name":"states","file_name":"states.csv","file_size":1048576}'

Responses