Asynchronous write endpoint that executes INSERT / UPDATE / DELETE SQL against a destination branch (created from a source branch if missing) and returns an operation name to poll for completion and the resulting commit IDs. Requires a Bearer / token authorization header.
openapi: 3.0.1
info:
title: DoltHub API
description: >-
The DoltHub HTTP API (v1alpha1) for the version-controlled SQL database
"Git for data". Provides read SQL queries, asynchronous write SQL queries,
and version-control management of databases, branches, tags, forks, jobs,
and operations on Dolt databases hosted at dolthub.com. Read queries against
public databases are unauthenticated; write queries and access to private
databases require an API token sent as an authorization header.
termsOfService: https://www.dolthub.com/terms
contact:
name: DoltHub Support
url: https://www.dolthub.com/contact
version: v1alpha1
servers:
- url: https://www.dolthub.com/api/v1alpha1
security:
- tokenAuth: []
- {}
paths:
/{owner}/{database}/{ref}:
get:
operationId: executeReadQuery
tags:
- SQL
summary: Execute a read SQL query
description: >-
Executes a read-only SQL query (passed in the `q` query parameter)
against the given database at the given branch/ref and returns the
schema and result rows as JSON.
parameters:
- name: owner
in: path
required: true
schema:
type: string
description: Database owner name (e.g. dolthub).
- name: database
in: path
required: true
schema:
type: string
description: Database (repository) name (e.g. ip-to-country).
- name: ref
in: path
required: true
schema:
type: string
description: Branch name, ref, or commit to query.
- name: q
in: query
required: true
schema:
type: string
description: The SQL query to execute (e.g. SELECT * FROM states).
responses:
'200':
description: Query result with schema and rows.
content:
application/json:
schema:
$ref: '#/components/schemas/QueryResponse'
/{owner}/{database}:
get:
operationId: executeReadQueryDefaultBranch
tags:
- SQL
summary: Execute a read SQL query against the default branch
description: >-
Same as the read query endpoint but omits the branch/ref segment and
runs the query against the database default branch.
parameters:
- name: owner
in: path
required: true
schema:
type: string
description: Database owner name.
- name: database
in: path
required: true
schema:
type: string
description: Database (repository) name.
- name: q
in: query
required: true
schema:
type: string
description: The SQL query to execute.
responses:
'200':
description: Query result with schema and rows.
content:
application/json:
schema:
$ref: '#/components/schemas/QueryResponse'
/{owner}/{database}/write/{fromBranch}/{toBranch}:
post:
operationId: executeWriteQuery
tags:
- SQL
summary: Execute an asynchronous write SQL query
description: >-
Executes an INSERT / UPDATE / DELETE query (passed in `q`) against
`toBranch`, which is created from `fromBranch` if it does not exist. An
empty query merges `fromBranch` into `toBranch`. Returns an
`operation_name` to poll. Requires authentication.
security:
- tokenAuth: []
parameters:
- name: owner
in: path
required: true
schema:
type: string
- name: database
in: path
required: true
schema:
type: string
- name: fromBranch
in: path
required: true
schema:
type: string
description: Source branch the destination branch is based on.
- name: toBranch
in: path
required: true
schema:
type: string
description: Destination branch the write is committed to.
- name: q
in: query
required: false
schema:
type: string
description: The write SQL query. An empty value merges fromBranch into toBranch.
responses:
'200':
description: Asynchronous operation accepted.
content:
application/json:
schema:
$ref: '#/components/schemas/WriteOperationResponse'
/{owner}/{database}/write:
get:
operationId: pollWriteOperation
tags:
- SQL
summary: Poll the status of a write operation
description: >-
Polls the status of a previously submitted write operation using the
`operationName` returned by the write endpoint. Poll until `done` is
true.
security:
- tokenAuth: []
parameters:
- name: owner
in: path
required: true
schema:
type: string
- name: database
in: path
required: true
schema:
type: string
- name: operationName
in: query
required: true
schema:
type: string
description: Operation name returned by the write endpoint.
responses:
'200':
description: Operation status, including commit IDs when done.
content:
application/json:
schema:
$ref: '#/components/schemas/WriteStatusResponse'
/database:
post:
operationId: createDatabase
tags:
- Databases
summary: Create a database
description: Creates a new Dolt database (repository) owned by the given owner.
security:
- tokenAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDatabaseRequest'
responses:
'200':
description: Database created.
/fork:
post:
operationId: forkDatabase
tags:
- Databases
summary: Fork a database
description: >-
Forks a parent database into a new owner namespace. Asynchronous;
returns an operation name to poll via GET /fork.
security:
- tokenAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ForkDatabaseRequest'
responses:
'200':
description: Fork operation accepted.
content:
application/json:
schema:
$ref: '#/components/schemas/WriteOperationResponse'
get:
operationId: pollForkOperation
tags:
- Databases
summary: Poll the status of a fork operation
security:
- tokenAuth: []
parameters:
- name: operationName
in: query
required: true
schema:
type: string
responses:
'200':
description: Fork operation status.
/{owner}/{database}/forks:
get:
operationId: listForks
tags:
- Databases
summary: List forks of a database
parameters:
- name: owner
in: path
required: true
schema:
type: string
- name: database
in: path
required: true
schema:
type: string
responses:
'200':
description: List of forks in the network.
/{owner}/{database}/branches:
get:
operationId: listBranches
tags:
- Branches
summary: List branches
parameters:
- name: owner
in: path
required: true
schema:
type: string
- name: database
in: path
required: true
schema:
type: string
responses:
'200':
description: List of branches.
post:
operationId: createBranch
tags:
- Branches
summary: Create a branch
security:
- tokenAuth: []
parameters:
- name: owner
in: path
required: true
schema:
type: string
- name: database
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateBranchRequest'
responses:
'200':
description: Branch created.
/{owner}/{database}/tags:
get:
operationId: listTags
tags:
- Tags
summary: List tags
parameters:
- name: owner
in: path
required: true
schema:
type: string
- name: database
in: path
required: true
schema:
type: string
responses:
'200':
description: List of tags.
post:
operationId: createTag
tags:
- Tags
summary: Create a tag
security:
- tokenAuth: []
parameters:
- name: owner
in: path
required: true
schema:
type: string
- name: database
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateTagRequest'
responses:
'200':
description: Tag created.
/{owner}/{database}/pulls:
post:
operationId: createPullRequest
tags:
- Pull Requests
summary: Create a pull request
security:
- tokenAuth: []
parameters:
- name: owner
in: path
required: true
schema:
type: string
- name: database
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePullRequest'
responses:
'200':
description: Pull request created.
/{owner}/{database}/pulls/{pullId}/comments:
post:
operationId: addPullRequestComment
tags:
- Pull Requests
summary: Add a comment to a pull request
security:
- tokenAuth: []
parameters:
- name: owner
in: path
required: true
schema:
type: string
- name: database
in: path
required: true
schema:
type: string
- name: pullId
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
comment:
type: string
required:
- comment
responses:
'200':
description: Comment added.
/{owner}/{database}/pulls/{pullId}/merge:
post:
operationId: mergePullRequest
tags:
- Pull Requests
summary: Merge a pull request
description: Initiates an asynchronous merge of a pull request.
security:
- tokenAuth: []
parameters:
- name: owner
in: path
required: true
schema:
type: string
- name: database
in: path
required: true
schema:
type: string
- name: pullId
in: path
required: true
schema:
type: string
responses:
'200':
description: Merge operation accepted.
content:
application/json:
schema:
$ref: '#/components/schemas/WriteOperationResponse'
get:
operationId: pollMergePullRequest
tags:
- Pull Requests
summary: Poll the status of a pull request merge
security:
- tokenAuth: []
parameters:
- name: owner
in: path
required: true
schema:
type: string
- name: database
in: path
required: true
schema:
type: string
- name: pullId
in: path
required: true
schema:
type: string
- name: operationName
in: query
required: true
schema:
type: string
responses:
'200':
description: Merge operation status.
/{owner}/{database}/jobs:
get:
operationId: listJobs
tags:
- Jobs
summary: List jobs for a database
security:
- tokenAuth: []
parameters:
- name: owner
in: path
required: true
schema:
type: string
- name: database
in: path
required: true
schema:
type: string
- name: pageToken
in: query
required: false
schema:
type: string
responses:
'200':
description: List of jobs.
/users/{username}/operations:
get:
operationId: listOperations
tags:
- Operations
summary: List operations created by a user
security:
- tokenAuth: []
parameters:
- name: username
in: path
required: true
schema:
type: string
- name: operationType
in: query
required: false
schema:
type: string
enum:
- SqlWrite
- SqlRead
- Import
- Merge
- Migrate
- name: pageToken
in: query
required: false
schema:
type: string
responses:
'200':
description: List of operations.
components:
securitySchemes:
tokenAuth:
type: apiKey
in: header
name: authorization
description: >-
DoltHub API token sent as the `authorization` header in the form
"token YOUR_API_TOKEN". Required for write queries and access to
private databases.
schemas:
QueryResponse:
type: object
properties:
query_execution_status:
type: string
query_execution_message:
type: string
repository_owner:
type: string
repository_name:
type: string
commit_ref:
type: string
sql_query:
type: string
schema:
type: array
items:
type: object
properties:
columnName:
type: string
columnType:
type: string
rows:
type: array
items:
type: object
additionalProperties: true
WriteOperationResponse:
type: object
properties:
operation_name:
type: string
WriteStatusResponse:
type: object
properties:
done:
type: boolean
res_details:
type: object
properties:
from_commit_id:
type: string
to_commit_id:
type: string
CreateDatabaseRequest:
type: object
properties:
ownerName:
type: string
repoName:
type: string
visibility:
type: string
enum:
- public
- private
description:
type: string
required:
- ownerName
- repoName
- visibility
ForkDatabaseRequest:
type: object
properties:
parentOwnerName:
type: string
parentDatabaseName:
type: string
ownerName:
type: string
required:
- parentOwnerName
- parentDatabaseName
- ownerName
CreateBranchRequest:
type: object
properties:
revisionType:
type: string
enum:
- branch
- ref
- commit
revisionName:
type: string
newBranchName:
type: string
required:
- revisionType
- revisionName
- newBranchName
CreateTagRequest:
type: object
properties:
tagName:
type: string
tagMessage:
type: string
revisionType:
type: string
enum:
- branch
- ref
- commit
revisionName:
type: string
required:
- tagName
- tagMessage
- revisionType
- revisionName
CreatePullRequest:
type: object
properties:
title:
type: string
description:
type: string
fromBranchOwnerName:
type: string
fromBranchRepoName:
type: string
fromBranchName:
type: string
toBranchOwnerName:
type: string
toBranchRepoName:
type: string
toBranchName:
type: string
required:
- title
- fromBranchOwnerName
- fromBranchRepoName
- fromBranchName
- toBranchOwnerName
- toBranchRepoName
- toBranchName