Skip to content

Update Hosted API docs for background operations #215

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tbantle22 merged 1 commit into from
Sep 28, 2026
Merged

Update Hosted API docs for background operations #215

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions scripts/generate-hosted-api-v1.mjs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@
* user.md — User-tagged endpoints
* deployment.md — Deployment-tagged endpoints
* pull-request.md — Pull request-tagged endpoints
* operation.md — Operation-tagged endpoints
* models.md — all component schemas
*
* authentication.md and README.md are hand-written; this script does not touch
Expand Down Expand Up @@ -40,6 +41,12 @@ generateApiDocs({
frontmatter:
'---\ntitle: "Deployment"\ndescription: Creating, listing, and reading Hosted Dolt deployments and their instances.\n---\n\n# Deployment',
},
{
tag: "Operation",
file: "operation.md",
frontmatter:
'---\ntitle: "Operation"\ndescription: Polling background work in the Hosted v1 API.\n---\n\n# Operation',
},
{
tag: "Pull request",
file: "pull-request.md",
Expand Down
14 changes: 13 additions & 1 deletion site/dolt/src/content/products/hosted/api/v1/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,7 @@ See [Authentication](/products/hosted/api/v1/authentication) for how to create a
| **GET** | `/api/v1/deployments/{owner}/{deployment}/instances` | [List a deployment's instances](/products/hosted/api/v1/deployment#listDeploymentInstances) |
| **POST** | `/api/v1/deployments/{owner}/{deployment}/instances` | [Add a read replica to a deployment](/products/hosted/api/v1/deployment#addDeploymentInstance) |
| **DELETE** | `/api/v1/deployments/{owner}/{deployment}/instances/{id}` | [Remove an instance from a deployment](/products/hosted/api/v1/deployment#deleteDeploymentInstance) |
| **POST** | `/api/v1/deployments/{owner}/{deployment}/instances/{id}/reboot` | [Reboot one of a deployment's instances](/products/hosted/api/v1/deployment#rebootDeploymentInstance) |
| **GET** | `/api/v1/deployments/{owner}/{deployment}/config` | [Get a deployment's configuration](/products/hosted/api/v1/deployment#getDeploymentConfig) |
| **PATCH** | `/api/v1/deployments/{owner}/{deployment}/config` | [Change some of a deployment's configuration overrides](/products/hosted/api/v1/deployment#patchDeploymentConfig) |
| **GET** | `/api/v1/deployments/{owner}/{deployment}/logs` | [Read a deployment's logs](/products/hosted/api/v1/deployment#getDeploymentLogs) |
Expand All @@ -57,6 +58,9 @@ See [Authentication](/products/hosted/api/v1/authentication) for how to create a
| **GET** | `/api/v1/deployments/{owner}/{deployment}/metrics` | [List a deployment's metrics](/products/hosted/api/v1/deployment#listDeploymentMetrics) |
| **GET** | `/api/v1/deployments/{owner}/{deployment}/metrics/{metric}` | [Read one of a deployment's metrics](/products/hosted/api/v1/deployment#getDeploymentMetric) |
| **GET** | `/api/v1/deployments/{owner}/{deployment}/backups` | [List a deployment's backups](/products/hosted/api/v1/deployment#listDeploymentBackups) |
| **POST** | `/api/v1/deployments/{owner}/{deployment}/backups` | [Take a backup of a deployment](/products/hosted/api/v1/deployment#createDeploymentBackup) |
| **GET** | `/api/v1/deployments/{owner}/{deployment}/database-version` | [List the versions a deployment can run](/products/hosted/api/v1/deployment#listDeploymentDatabaseVersions) |
| **POST** | `/api/v1/deployments/{owner}/{deployment}/database-version` | [Roll a deployment's database engine to another version](/products/hosted/api/v1/deployment#updateDeploymentDatabaseVersion) |
| **POST** | `/api/v1/deployments/{owner}/{deployment}/disable` | [Disable a deployment](/products/hosted/api/v1/deployment#disableDeployment) |

### Pull request
Expand All @@ -68,6 +72,12 @@ See [Authentication](/products/hosted/api/v1/authentication) for how to create a
| **POST** | `/api/v1/deployments/{owner}/{deployment}/pulls/{id}/comments` | [Comment on a pull request](/products/hosted/api/v1/pull-request#createDeploymentPullComment) |
| **GET** | `/api/v1/deployments/{owner}/{deployment}/pulls/{id}/logs` | [List a pull request's activity log](/products/hosted/api/v1/pull-request#listDeploymentPullLogs) |

### Operation

| Method | Path | What it does |
|--------|------|--------------|
| **GET** | `/api/v1/operations/{id}` | [Get the status of queued work](/products/hosted/api/v1/operation#getOperation) |

## Response shape

Every `2xx` response body is an [Envelope](/products/hosted/api/v1/models#model-envelope): the resource, or an array of resources, under `data`, with optional `meta`.
Expand Down Expand Up @@ -123,9 +133,11 @@ Instance changes are also `202`, but there is no per-instance `state` field to p

[Exposing or unexposing a service](/products/hosted/api/v1/deployment#exposeDeploymentService) 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](/products/hosted/api/v1/deployment#createDeploymentBackup), [rolling the database version](/products/hosted/api/v1/deployment#updateDeploymentDatabaseVersion), and [rebooting an instance](/products/hosted/api/v1/deployment#rebootDeploymentInstance) return `202` with an [OperationRef](/products/hosted/api/v1/models#model-operationref). Follow its `href`, or pass its `id` to [Get an operation](/products/hosted/api/v1/operation#getOperation), 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.

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](/products/hosted/api/v1/deployment#listDeploymentBackups) if you want the data.
> **Creating a deployment incurs cost.** Disabling one tears down its instances and their storage — [take a backup first](/products/hosted/api/v1/deployment#createDeploymentBackup) and confirm completion if you want the data.

## Stability

Expand Down
224 changes: 224 additions & 0 deletions site/dolt/src/content/products/hosted/api/v1/deployment.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -565,6 +565,61 @@ curl -X GET 'https://hosted.doltdb.com/api/v1/deployments/{owner}/{deployment}/b

---

## Take a backup of a deployment {#createDeploymentBackup}
<span class="api-method" style="background:#6DB0FC">POST</span> <code class="api-path">/api/v1/deployments/{owner}/{deployment}/backups</code>

Queues a backup of every database on the deployment. Scheduled backups keep running alongside it; this is the on-demand one, for taking a snapshot before a migration or a version roll.

The backup is queued rather than taken inline, so this returns `202` with an operation to poll. It reaches each instance separately, and the operation reports `succeeded` once every current instance reports a completed backup started after the operation was queued. This is inferred from timestamps: a scheduled backup can satisfy the check, so success does not identify a particular on-demand backup.

If an instance rejects the backup request, the operation is `failed`. After the request is accepted, Hosted may not see later failures because instances report only their newest successful backup. If Hosted cannot confirm completion, timeout finalization reports `FAILED` when dispatch was confirmed, or `EXPIRED` when it was not. Either status means completion is unknown; a backup may still exist.

The operation does not name the backup it produced. Read `GET /api/v1/deployments/{owner}/{deployment}/backups` to inspect the available backups. Scheduled and other on-demand backups can overlap, so the newest backup cannot be reliably attributed to this operation.

Requires admin on the deployment.


**Parameters**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `owner` | path | string | yes | The user or organization that owns the deployment. 3–32 characters of letters, digits, hyphens, and underscores. |
| `deployment` | path | string | yes | The deployment name, unique within the owner. 3–32 characters of letters, digits, hyphens, and underscores. |

**Example request**

```sh
curl -X POST 'https://hosted.doltdb.com/api/v1/deployments/{owner}/{deployment}/backups' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json'
```

**Responses**

| Status | Description | Schema |
|--------|-------------|--------|
| `202` | The backup was queued. | [`OperationRef`](/products/hosted/api/v1/models#model-operationref) |
| `400` | The request was malformed or failed input validation. | [`Problem`](/products/hosted/api/v1/models#model-problem) |
| `401` | Authentication credentials were missing or invalid. | [`Problem`](/products/hosted/api/v1/models#model-problem) |
| `403` | Authenticated, but not permitted to perform this action. | [`Problem`](/products/hosted/api/v1/models#model-problem) |
| `404` | The requested resource does not exist. | [`Problem`](/products/hosted/api/v1/models#model-problem) |
| `405` | The HTTP method is not supported for this resource. | [`Problem`](/products/hosted/api/v1/models#model-problem) |
| `500` | An unexpected server error occurred. | [`Problem`](/products/hosted/api/v1/models#model-problem) |
| `503` | The service is temporarily unavailable. | [`Problem`](/products/hosted/api/v1/models#model-problem) |

**Example response `202`**

```json
{
"data": {
"id": "3f2a9c14-8e7b-4d21-9a05-6c3e1b8f4d72",
"href": "https://hosted.doltdb.com/api/v1/operations/3f2a9c14-8e7b-4d21-9a05-6c3e1b8f4d72"
}
}
```

---

## Get a deployment's configuration {#getDeploymentConfig}
<span class="api-method" style="background:#29E3C1">GET</span> <code class="api-path">/api/v1/deployments/{owner}/{deployment}/config</code>

Expand Down Expand Up @@ -709,6 +764,121 @@ _Clear one override without touching the others._

---

## List the versions a deployment can run {#listDeploymentDatabaseVersions}
<span class="api-method" style="background:#29E3C1">GET</span> <code class="api-path">/api/v1/deployments/{owner}/{deployment}/database-version</code>

Returns the deployment's current database engine version and the versions it can be upgraded or downgraded to. The list combines the latest releases with versions previously installed on this deployment, which is what `POST` on this path accepts.

Hosted offers the most recent releases rather than every one ever published, and that list moves as new versions ship, so read it before each roll rather than keeping a copy. Versions previously installed on this deployment remain available even after they leave the latest release list. Which releases appear depends on the deployment's `cluster_type`: a `dolt` cluster is offered Dolt versions and a `doltgres` one Doltgres versions.

`current` is the version the deployment records. During a roll it is still the old one until every instance reports the new version, so poll the operation rather than this list to find out when a roll is done.


**Parameters**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `owner` | path | string | yes | The user or organization that owns the deployment. 3–32 characters of letters, digits, hyphens, and underscores. |
| `deployment` | path | string | yes | The deployment name, unique within the owner. 3–32 characters of letters, digits, hyphens, and underscores. |

**Example request**

```sh
curl -X GET 'https://hosted.doltdb.com/api/v1/deployments/{owner}/{deployment}/database-version' \
-H 'Authorization: Bearer YOUR_TOKEN'
```

**Responses**

| Status | Description | Schema |
|--------|-------------|--------|
| `200` | The deployment's current version and the ones it can be rolled to. | [`DatabaseVersions`](/products/hosted/api/v1/models#model-databaseversions) |
| `400` | The request was malformed or failed input validation. | [`Problem`](/products/hosted/api/v1/models#model-problem) |
| `401` | Authentication credentials were missing or invalid. | [`Problem`](/products/hosted/api/v1/models#model-problem) |
| `404` | The requested resource does not exist. | [`Problem`](/products/hosted/api/v1/models#model-problem) |
| `405` | The HTTP method is not supported for this resource. | [`Problem`](/products/hosted/api/v1/models#model-problem) |
| `500` | An unexpected server error occurred. | [`Problem`](/products/hosted/api/v1/models#model-problem) |
| `503` | The service is temporarily unavailable. | [`Problem`](/products/hosted/api/v1/models#model-problem) |

**Example response `200`**

```json
{
"data": {
"current": "1.59.2",
"available": [
"1.60.0",
"1.59.2",
"1.59.1",
"1.58.4",
"1.58.3"
]
}
}
```

---

## Roll a deployment's database engine to another version {#updateDeploymentDatabaseVersion}
<span class="api-method" style="background:#6DB0FC">POST</span> <code class="api-path">/api/v1/deployments/{owner}/{deployment}/database-version</code>

Sets the version of the database engine the deployment runs: a Dolt version on a `dolt` cluster, a Doltgres version on a `doltgres` one. Which versions are accepted depends on the deployment's `cluster_type`, and a version that is valid for one is not necessarily valid for the other.

Call `GET /api/v1/deployments/{owner}/{deployment}/database-version` first to see the deployment's current version and the versions available for its database engine.

The current version is `database_version` on the deployment. Downgrades are allowed, so this can be used to roll back as well as forward.

The roll is queued rather than applied inline, so this returns `202` with an operation to poll. On a deployment with replicas it reaches each instance separately, and the operation reports `succeeded` only once every instance reports the version asked for. Instances restart as they take the new version, so expect a brief interruption.


**Parameters**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `owner` | path | string | yes | The user or organization that owns the deployment. 3–32 characters of letters, digits, hyphens, and underscores. |
| `deployment` | path | string | yes | The deployment name, unique within the owner. 3–32 characters of letters, digits, hyphens, and underscores. |

**Request body**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `version` | string | yes | A version the deployment's `cluster_type` supports, without a leading `v`. A version this API does not recognize is rejected rather than queued. |

**Example request**

```sh
curl -X POST 'https://hosted.doltdb.com/api/v1/deployments/{owner}/{deployment}/database-version' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"version":"1.60.0"}'
```

**Responses**

| Status | Description | Schema |
|--------|-------------|--------|
| `202` | The roll was queued. | [`OperationRef`](/products/hosted/api/v1/models#model-operationref) |
| `400` | The request was malformed or failed input validation. | [`Problem`](/products/hosted/api/v1/models#model-problem) |
| `401` | Authentication credentials were missing or invalid. | [`Problem`](/products/hosted/api/v1/models#model-problem) |
| `403` | Authenticated, but not permitted to perform this action. | [`Problem`](/products/hosted/api/v1/models#model-problem) |
| `404` | The requested resource does not exist. | [`Problem`](/products/hosted/api/v1/models#model-problem) |
| `405` | The HTTP method is not supported for this resource. | [`Problem`](/products/hosted/api/v1/models#model-problem) |
| `500` | An unexpected server error occurred. | [`Problem`](/products/hosted/api/v1/models#model-problem) |
| `503` | The service is temporarily unavailable. | [`Problem`](/products/hosted/api/v1/models#model-problem) |

**Example response `202`**

```json
{
"data": {
"id": "3f2a9c14-8e7b-4d21-9a05-6c3e1b8f4d72",
"href": "https://hosted.doltdb.com/api/v1/operations/3f2a9c14-8e7b-4d21-9a05-6c3e1b8f4d72"
}
}
```

---

## Read a deployment's logs {#getDeploymentLogs}
<span class="api-method" style="background:#29E3C1">GET</span> <code class="api-path">/api/v1/deployments/{owner}/{deployment}/logs</code>

Expand Down Expand Up @@ -1207,3 +1377,57 @@ curl -X DELETE 'https://hosted.doltdb.com/api/v1/deployments/{owner}/{deployment
}
```

---

## Reboot one of a deployment's instances {#rebootDeploymentInstance}
<span class="api-method" style="background:#6DB0FC">POST</span> <code class="api-path">/api/v1/deployments/{owner}/{deployment}/instances/{id}/reboot</code>

Restarts the machine the instance runs on. Its data volume survives, so this is a reboot rather than a replacement, but the database on it is unreachable until the machine is back.

The reboot is queued rather than performed inline, so this returns `202` with an operation to poll. It reports `succeeded` once the reboot has been requested from the instance's platform, which is the last thing this system observes. A `succeeded` operation means the reboot was issued, not that the database is serving again. The instances endpoint can confirm that the instance is still part of the deployment, but it does not expose reboot or readiness state. Check the database connection separately.

Rebooting the primary interrupts writes for as long as the machine takes to come back, so check `is_primary` on the instances list before picking an id.

Requires admin on the deployment.


**Parameters**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `owner` | path | string | yes | The user or organization that owns the deployment. 3–32 characters of letters, digits, hyphens, and underscores. |
| `deployment` | path | string | yes | The deployment name, unique within the owner. 3–32 characters of letters, digits, hyphens, and underscores. |
| `id` | path | string | yes | The instance's id, as reported by the instances list. |

**Example request**

```sh
curl -X POST 'https://hosted.doltdb.com/api/v1/deployments/{owner}/{deployment}/instances/{id}/reboot' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json'
```

**Responses**

| Status | Description | Schema |
|--------|-------------|--------|
| `202` | The reboot was queued. | [`OperationRef`](/products/hosted/api/v1/models#model-operationref) |
| `400` | The request was malformed or failed input validation. | [`Problem`](/products/hosted/api/v1/models#model-problem) |
| `401` | Authentication credentials were missing or invalid. | [`Problem`](/products/hosted/api/v1/models#model-problem) |
| `403` | Authenticated, but not permitted to perform this action. | [`Problem`](/products/hosted/api/v1/models#model-problem) |
| `404` | The requested resource does not exist. | [`Problem`](/products/hosted/api/v1/models#model-problem) |
| `405` | The HTTP method is not supported for this resource. | [`Problem`](/products/hosted/api/v1/models#model-problem) |
| `500` | An unexpected server error occurred. | [`Problem`](/products/hosted/api/v1/models#model-problem) |
| `503` | The service is temporarily unavailable. | [`Problem`](/products/hosted/api/v1/models#model-problem) |

**Example response `202`**

```json
{
"data": {
"id": "3f2a9c14-8e7b-4d21-9a05-6c3e1b8f4d72",
"href": "https://hosted.doltdb.com/api/v1/operations/3f2a9c14-8e7b-4d21-9a05-6c3e1b8f4d72"
}
}
```

Loading
Loading