Hosted API v1#

API version: v1

The v1 API is the public HTTP surface for the Hosted Dolt control plane. Every endpoint lives under https://hosted.doltdb.com/api/v1/.

It is an OpenAPI-defined contract, and commits to:

• Consistent HTTP semantics (correct status codes, idempotent GETs, 202 for work that continues after the response)
• A single error model (RFC 9457 problem details) — see Problem
• A uniform success Envelope wrapping every response
• Cursor pagination on list endpoints

Scope. v1 covers the control plane only. Querying the data inside a deployment is not part of this API — connect to the deployment’s SQL endpoint directly with your database credentials.

Authentication#

Every endpoint requires a Hosted API token, sent as a bearer token:

curl 'https://hosted.doltdb.com/api/v1/user' \
  -H 'Authorization: Bearer hsat.v1.YOUR_TOKEN_HERE'

See Authentication for how to create and manage tokens.

All endpoints#

User#

Deployment#

Pull request#

Operation#

Response shape#

Every 2xx response body is an Envelope: the resource, or an array of resources, under data, with optional meta.

{
  "data": { "owner": "acme", "name": "analytics", "state": "started" }
}

List endpoints put the pagination cursor in meta:

{
  "data": [ { "owner": "acme", "name": "analytics" } ],
  "meta": { "next_page_token": "eyJvZmZzZXQiOjI1fQ" }
}

When meta.next_page_token is present, pass it back as the page_token query parameter to fetch the next page. On the last page meta is omitted entirely, so checking whether the token is present is all a client needs — it is never returned present but empty. Page size is fixed and not caller-controlled, so a full page is not itself a sign that another one follows.

Two kinds of list depart from that. A pull request’s comments and its activity log, and a deployment’s metrics catalogue and service windows, are small enough by nature to be returned whole, so they take no page_token at all. And log retrieval walks a window of history rather than a finite list: it is the only endpoint that pages in both directions, and the only one whose page size you set (lines). There meta.next_page_token reads further back, meta.prev_page_token reads toward the present, both can be present at once, and either can come back on a page with no lines — so stop when a page comes back empty, not when a token is missing.

Each endpoint’s parameters say which of the three it is.

Errors#

Every non-2xx response is a Problem with content type application/problem+json:

{
  "type": "https://docs.dolthub.com/products/hosted/api/v1/models/#model-errorcode",
  "title": "Not found",
  "status": 404,
  "detail": "Deployment 'analytics' does not exist for owner 'acme'",
  "instance": "/api/v1/deployments/acme/analytics",
  "code": "NOT_FOUND",
  "request_id": "req_01HZX9P7Q5N2M8"
}

Branch on code — a stable, machine-readable ErrorCode — never on the human-readable title or detail, which may be reworded at any time.

Every response, including successful ones, carries an x-request-id header, echoed in the body as request_id on errors. Include it when contacting support so a request can be traced end to end.

Long-running work#

Creating a deployment returns 202 Accepted with the deployment in its starting state — provisioning continues after the response. Poll Get a deployment until state becomes started.

Disabling a deployment works the same way: 202 Accepted with the deployment in stopping, then poll until state is stopped.

Instance changes are also 202, but there is no per-instance state field to poll, so they are observed through the instance list instead. After adding a replica, poll until that instance reports a host — that is when it is reachable. After removing one, poll until it disappears from the list, which only reports instances that aren’t stopped.

Exposing or unexposing a service is 202 too, and is polled on the deployment itself: read it back until expose_remotesapi_endpoint or expose_mcp reports the value you asked for, which is written once the change reaches the instances. The 202 body echoes the request rather than the deployment’s current state. Exposing the remotesapi endpoint needs a WebPKI certificate — webpki_cert on the deployment says whether it has one, and without it the request is a 400 rather than a queued change.

Taking a backup, rolling the database version, and rebooting an instance return 202 with an OperationRef. Follow its href, or pass its id to Get an operation, and poll with a delay until status is succeeded or failed. Completion means different things for each action: a version roll waits for every instance to report the requested version, backup completion is inferred from successful backup timestamps, and a reboot succeeds when the platform accepts the request, before the database is necessarily ready. A failed operation does not imply rollback, and a transient HTTP error while polling is not a reason to submit the action again.

Issuing, removing, or replacing Dolt credentials also returns 202 with an OperationRef to poll. These credentials let the deployment access private databases on DoltHub. After issuing or replacing them succeeds, read the public key and add it to the appropriate DoltHub account. After removal succeeds, that read returns 404. Replacement can temporarily leave instances with different credentials, and a failed operation does not roll back changes.

Deployment names are unique within an owner, which makes creates idempotent by name: retrying after an ambiguous failure returns 409 Conflict rather than provisioning a second deployment.

Creating a deployment incurs cost. Disabling one tears down its instances and their storage — take a backup first and confirm completion if you want the data.

Stability#

v1 is additive. New endpoints, new optional request fields, new response fields, and new ErrorCode values may be introduced within v1. Renaming or removing a field, or changing an existing one’s meaning, requires a new major version.