---
title: "Deployment"
description: Creating, listing, and reading Hosted Dolt deployments and their instances.
---
# Deployment
Hosted Dolt deployments and their lifecycle.
## List the options a deployment can be created with {#getDeploymentOptions}
GET /api/v1/deployment-options
Returns the zones, instance types, and storage options available for a cloud, so a caller can construct a valid `POST /api/v1/deployments` request.
The options narrow in steps, because each depends on the one before it. Supply `cloud` alone for its zones; add `zone` to also get that zone's instance types; add `instance_type_id` to also get the storage options compatible with that instance. Fields you haven't narrowed enough to determine are absent rather than empty.
Each list is filtered to what you selected: supplying `zone` narrows `zones` to that zone, and supplying `instance_type_id` narrows `instance_types` to that instance type. A fully narrowed request therefore describes one combination rather than repeating the whole catalogue.
A `zone` or `instance_type_id` that doesn't exist is a `422` rather than an empty result, so a typo can't be mistaken for a combination with nothing available. `instance_type_id` requires `zone`; supplying it alone is a `400`.
The `id` of an instance type or storage option is what `POST /api/v1/deployments` accepts; `name` is for display.
**Parameters**
| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `cloud` | query | [`CloudProvider`](/products/hosted/api/v1/models#model-cloudprovider) | yes | The cloud to list options for. |
| `zone` | query | string | no | A zone from this cloud's `zones`. Supply it to receive `instance_types`. |
| `instance_type_id` | query | string | no | An instance type `id` from `instance_types`. Supply it, together with `zone`, to receive `storage_options`. |
**Example request**
```sh
curl -X GET 'https://hosted.doltdb.com/api/v1/deployment-options?cloud=aws' \
-H 'Authorization: Bearer YOUR_TOKEN'
```
**Responses**
| Status | Description | Schema |
|--------|-------------|--------|
| `200` | The available options, narrowed by the supplied parameters. | [`DeploymentOptions`](/products/hosted/api/v1/models#model-deploymentoptions) |
| `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) |
| `405` | The HTTP method is not supported for this resource. | [`Problem`](/products/hosted/api/v1/models#model-problem) |
| `422` | The request was well-formed but semantically invalid. | [`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": {
"cloud": "aws",
"zones": [
"us-east-1"
],
"instance_types": [
{
"id": "aws.t2.medium",
"name": "t2.medium",
"cpus": 2,
"memory_gb": 4,
"description": "Trial tier, the lowest spec that runs a Dolt SQL server.",
"hourly_cost_usd": 0.06849315
}
],
"storage_options": [
{
"id": "aws.ebs.gp3_50",
"name": "Trial 50GB EBS",
"description": "Trial tier storage capped at 50GB",
"min_size_gb": 50,
"max_size_gb": 50,
"monthly_cost_usd_per_gb": 0
}
]
}
}
```
---
## Create a deployment {#createDeployment}
POST /api/v1/deployments
Provisions a new deployment and returns `202` with the deployment in its `starting` state. Provisioning continues after the response: poll `GET /api/v1/deployments/{owner}/{deployment}` until `state` becomes `started`.
Deployment names are unique within an owner, so a create is idempotent by name — a retry after an ambiguous failure returns `409` rather than provisioning a second deployment. Callers should still treat `409` as "it already exists", not as a different failure.
`instance_type_id` and `volume_type_id` take the **ids** from the deployment options endpoint, not the display names a deployment reports back on a read.
As with any create, a `5xx` or a dropped connection does not tell you whether the deployment was created — the call can succeed remotely and fail on the way back. Retry: it returns `409` if the deployment now exists, and `GET` confirms either way.
**Creating a deployment incurs cost.**
**Request body**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `owner` | string | yes | The user or organization that will own the deployment. The caller must have permission to create deployments for it. 3–32 characters of letters, digits, hyphens, and underscores. |
| `name` | string | yes | The deployment name, unique within the owner. 3–32 characters of letters, digits, hyphens, and underscores. |
| `cloud` | [`CloudProvider`](/products/hosted/api/v1/models#model-cloudprovider) | yes | The cloud the deployment runs in. |
| `zone` | string | yes | The cloud region to provision in, as listed by the deployment options. |
| `cluster_type` | [`ClusterType`](/products/hosted/api/v1/models#model-clustertype) | no | The database engine the deployment runs. `mysql_with_dolt_replicas` is a MySQL primary with Dolt read replicas. |
| `instance_type_id` | string | yes | The **id** of the instance type, from the deployment options endpoint. Note a deployment reports `instance_type_name` on a read — the id and the display name are different values. |
| `volume_type_id` | string | yes | The **id** of the storage type, from the deployment options endpoint. As with `instance_type_id`, this is the id rather than the display name. |
| `volume_size_gb` | integer | yes | The size of the storage volume, in gigabytes. Must fall within the selected storage type's supported range. |
| `replicas` | integer | no | The number of read replicas. Defaults to `0` when omitted. |
| `webpki_cert` | boolean | no | Serve a publicly-trusted (WebPKI) TLS certificate rather than a Hosted-issued one. Defaults to `false` when omitted. |
| `expose_remotesapi_endpoint` | boolean | no | Expose a Dolt remotes API endpoint. Defaults to `false` when omitted. |
| `expose_mcp` | boolean | no | Expose an MCP endpoint. Defaults to `false` when omitted. |
| `expose_stats` | boolean | no | Expose a statistics endpoint. Defaults to `false` when omitted. |
**Example request**
```sh
curl -X POST 'https://hosted.doltdb.com/api/v1/deployments' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"owner":"acme","name":"analytics","cloud":"aws","zone":"us-east-1","instance_type_id":"aws.t2.medium","volume_type_id":"aws.ebs.gp3_50","volume_size_gb":50}'
```
**Responses**
| Status | Description | Schema |
|--------|-------------|--------|
| `202` | The deployment has been accepted and is provisioning. `state` is `starting`. | [`Deployment`](/products/hosted/api/v1/models#model-deployment) |
| `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) |
| `405` | The HTTP method is not supported for this resource. | [`Problem`](/products/hosted/api/v1/models#model-problem) |
| `409` | The request conflicts with the current state of the resource (e.g. it already exists). | [`Problem`](/products/hosted/api/v1/models#model-problem) |
| `422` | The request was well-formed but semantically invalid. | [`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": {
"owner": "acme",
"name": "analytics",
"state": "starting",
"cloud": "aws",
"zone": "us-east-1",
"cluster_type": "dolt",
"instance_type_name": "t2.medium",
"volume_type_name": "Trial 50GB EBS",
"volume_size_gb": 50,
"replicas": 0,
"host": "",
"port": 3306,
"caller_role": "admin",
"created_by": "acme-ops",
"created_at": "2026-08-11T09:14:00Z"
}
}
```
---
## List an owner's deployments {#listDeployments}
GET /api/v1/deployments/{owner}
Returns the deployments belonging to `{owner}` that the caller can see, newest cursor page first. Requires a credential with access to the owner.
Items are `DeploymentSummary`, not the full `Deployment` — the backing RPC returns a narrower shape for lists. Fetch `GET /api/v1/deployments/{owner}/{deployment}` for the complete resource.
Pagination is cursor-based: when `meta.next_page_token` is present, pass it back as `page_token` to fetch the next page. On the last page `meta` is omitted entirely, so presence of the token is the only check a client needs.
**Parameters**
| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `owner` | path | string | yes | The user or organization whose deployments to list. 3–32 characters of letters, digits, hyphens, and underscores. |
| `page_token` | query | string | no | The `meta.next_page_token` from a previous response. Omit for the first page. |
| `state` | query | [`DeploymentState`](/products/hosted/api/v1/models#model-deploymentstate) | no | Return only deployments in this state. Omit for all states. |
**Example request**
```sh
curl -X GET 'https://hosted.doltdb.com/api/v1/deployments/{owner}' \
-H 'Authorization: Bearer YOUR_TOKEN'
```
**Responses**
| Status | Description | Schema |
|--------|-------------|--------|
| `200` | The owner's deployments. | [`DeploymentSummary[]`](/products/hosted/api/v1/models#model-deploymentsummary) |
| `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) |
**Example response `200`**
```json
{
"data": [
{
"owner": "acme",
"name": "analytics",
"state": "started",
"cloud": "aws",
"zone": "us-west-2",
"cluster_type": "dolt",
"instance_type_name": "m5.large",
"volume_type_name": "gp3",
"volume_size_gb": 100,
"replicas": 0,
"database_version": "1.58.4",
"hourly_cost_usd": 0.192,
"webpki_cert": true
}
],
"meta": {
"next_page_token": "eyJvZmZzZXQiOjI1fQ"
}
}
```
---
## Get a deployment {#getDeployment}
GET /api/v1/deployments/{owner}/{deployment}
Returns the deployment `{owner}/{deployment}`. Requires a credential with at least read access; a deployment the caller cannot see returns `404` rather than `403`, so its existence isn't leaked.
**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}' \
-H 'Authorization: Bearer YOUR_TOKEN'
```
**Responses**
| Status | Description | Schema |
|--------|-------------|--------|
| `200` | The deployment. | [`Deployment`](/products/hosted/api/v1/models#model-deployment) |
| `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 `200`**
```json
{
"data": {
"owner": "acme",
"name": "analytics",
"state": "started",
"cloud": "aws",
"zone": "us-east-1",
"cluster_type": "dolt",
"instance_type_name": "t2.medium",
"volume_type_name": "Trial 50GB EBS",
"volume_size_gb": 50,
"replicas": 0,
"database_version": "1.58.4",
"host": "analytics.dbs.hosted.doltdb.com",
"port": 3306,
"hourly_cost_usd": 0.06849315,
"webpki_cert": true,
"expose_remotesapi_endpoint": false,
"expose_mcp": false,
"expose_stats": false,
"disable_automatic_dolt_updates": false,
"caller_role": "admin",
"created_by": "acme-ops",
"created_at": "2026-07-01T18:22:04Z"
}
}
```
---
## Update a deployment's settings {#updateDeployment}
PATCH /api/v1/deployments/{owner}/{deployment}
Changes settings on an existing deployment. Only the fields present in the body are changed; anything omitted is left alone.
This endpoint does not resize, move or restart a deployment. Instance type, volume, zone and cloud are fixed once a deployment exists, and replicas are changed through the instances endpoints. What is settable here is deployment-level policy, currently just whether Dolt updates itself.
Only a deployment administrator may change settings.
**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 |
|-------|------|----------|-------------|
| `disable_automatic_dolt_updates` | boolean | no | Whether to stop Dolt updating itself during the deployment's service window. Turn this on to pin the version, then roll it forward deliberately. |
_Send at least one of these fields._
**Example request**
```sh
curl -X PATCH 'https://hosted.doltdb.com/api/v1/deployments/{owner}/{deployment}' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"disable_automatic_dolt_updates":true}'
```
**Responses**
| Status | Description | Schema |
|--------|-------------|--------|
| `200` | The deployment after the change. | [`Deployment`](/products/hosted/api/v1/models#model-deployment) |
| `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) |
| `422` | The request was well-formed but semantically invalid. | [`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": {
"owner": "acme",
"name": "analytics",
"state": "started",
"cloud": "aws",
"zone": "us-east-1",
"cluster_type": "dolt",
"caller_role": "admin",
"created_at": "2026-08-11T09:14:00Z",
"disable_automatic_dolt_updates": true
}
}
```
---
## List a deployment's instances {#listDeploymentInstances}
GET /api/v1/deployments/{owner}/{deployment}/instances
Returns the instances backing `{owner}/{deployment}` — one for a single-instance deployment, or a primary plus its read replicas.
Stopped instances are not listed; starting, started, and stopping ones all are. The `state` field tells you where each listed instance is in its lifecycle, and an empty array means the deployment has none outside the stopped state — normal while a deployment is itself `starting`.
The list is not paginated: a deployment has a primary and its replicas, a set small enough to return whole.
**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}/instances' \
-H 'Authorization: Bearer YOUR_TOKEN'
```
**Responses**
| Status | Description | Schema |
|--------|-------------|--------|
| `200` | The deployment's non-stopped instances. | [`DeploymentInstance[]`](/products/hosted/api/v1/models#model-deploymentinstance) |
| `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 `200`**
```json
{
"data": [
{
"id": "9b1f5c2e-4d3a-4f8b-9c0d-1e2f3a4b5c6d",
"index": 0,
"is_primary": true,
"state": "started",
"host": "analytics-0.dbs.hosted.doltdb.com",
"instance_type_name": "t2.medium",
"volume_type_name": "Trial 50GB EBS",
"volume_size_gb": 50,
"hourly_cost_usd": 0.06849315
},
{
"id": "2c4e6a8b-1d3f-4a5c-8e9b-0f1a2b3c4d5e",
"index": 1,
"is_primary": false,
"state": "started",
"host": "analytics-1.dbs.hosted.doltdb.com",
"instance_type_name": "t2.medium",
"volume_type_name": "Trial 50GB EBS",
"volume_size_gb": 50,
"hourly_cost_usd": 0.06849315
}
]
}
```
---
## Add a read replica to a deployment {#addDeploymentInstance}
POST /api/v1/deployments/{owner}/{deployment}/instances
Adds an instance to `{owner}/{deployment}` and returns `202` with the new instance, which is still being provisioned and so reports `state: starting`. Poll `GET /api/v1/deployments/{owner}/{deployment}/instances` until that instance reports `state: started` and a `host`; that is when it is reachable.
This is also how a disabled deployment is started again: adding an instance clears the shutdown and brings it back to `starting`. Pass `backup_id` to restore a backup into it, or it comes back empty.
`instance_type_id` and `volume_type_id` take the **ids** from the deployment options endpoint, not the display names an instance reports on a read.
Instances can only be added when the deployment is settled. If it is stopping, or any instance is still starting or stopping, the request conflicts with the deployment's current state and is rejected with `409`. Retry once it settles.
As with any create, a `5xx` does not tell you whether the instance was added. List the instances to find out; a retry while the new instance is still starting is rejected with `409` rather than adding a second one.
**Adding a replica incurs cost.**
**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 |
|-------|------|----------|-------------|
| `instance_type_id` | string | yes | The **id** of the instance type, from the deployment options endpoint. Note an instance reports `instance_type_name` on a read — the id and the display name are different values. |
| `volume_type_id` | string | yes | The **id** of the storage type, from the deployment options endpoint. |
| `volume_size_gb` | integer | yes | The size of the instance's storage volume, in gigabytes. Must fall within the selected storage type's supported range. |
| `backup_id` | string | no | A backup of this deployment to restore into the new instance, from the backups list. Only valid when the deployment is disabled and this request is restarting it; supplying it otherwise is a `400`. Without it a restarted deployment comes up empty. |
**Example request**
```sh
curl -X POST 'https://hosted.doltdb.com/api/v1/deployments/{owner}/{deployment}/instances' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"instance_type_id":"aws.t2.medium","volume_type_id":"aws.ebs.gp3_50","volume_size_gb":50}'
```
**Responses**
| Status | Description | Schema |
|--------|-------------|--------|
| `202` | The instance has been accepted and is starting. | [`DeploymentInstance`](/products/hosted/api/v1/models#model-deploymentinstance) |
| `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) |
| `409` | The request conflicts with the current state of the resource (e.g. it already exists). | [`Problem`](/products/hosted/api/v1/models#model-problem) |
| `500` | An unexpected server error occurred. | [`Problem`](/products/hosted/api/v1/models#model-problem) |
**Example response `202`**
```json
{
"data": {
"id": "2c4e6a8b-1d3f-4a5c-8e9b-0f1a2b3c4d5e",
"index": 1,
"is_primary": false,
"state": "starting",
"instance_type_name": "t2.medium",
"volume_type_name": "Trial 50GB EBS",
"volume_size_gb": 50
}
}
```
---
## List a deployment's backups {#listDeploymentBackups}
GET /api/v1/deployments/{owner}/{deployment}/backups
Returns the backups held for `{owner}/{deployment}`, newest first. Deleted backups are not included.
The list is not paginated: a deployment's retained backups are a bounded set.
**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}/backups' \
-H 'Authorization: Bearer YOUR_TOKEN'
```
**Responses**
| Status | Description | Schema |
|--------|-------------|--------|
| `200` | The deployment's backups. | [`Backup[]`](/products/hosted/api/v1/models#model-backup) |
| `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 `200`**
```json
{
"data": [
{
"id": "20260812T020000.000",
"databases": [
"analytics",
"staging"
],
"instance_index": 0,
"created_at": "2026-08-12T02:00:00Z"
},
{
"id": "20260811T020000.000",
"databases": [
"analytics",
"staging"
],
"size_bytes": 1048576,
"instance_index": 0,
"created_at": "2026-08-11T02:00:00Z"
}
]
}
```
---
## Take a backup of a deployment {#createDeploymentBackup}
POST /api/v1/deployments/{owner}/{deployment}/backups
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}
GET /api/v1/deployments/{owner}/{deployment}/config
Returns the deployment's effective database configuration: every setting Hosted supports, carrying the deployment's own value where it has overridden one and the default otherwise. This is what the deployment's Configuration page shows.
`is_overridden` distinguishes the two, and `default` is always reported, so a caller can tell what has been changed and what it would revert to.
Values are strings as stored, including numeric and boolean settings.
**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}/config' \
-H 'Authorization: Bearer YOUR_TOKEN'
```
**Responses**
| Status | Description | Schema |
|--------|-------------|--------|
| `200` | The deployment's effective configuration — every supported setting, at the value it is running. | [`DeploymentConfig`](/products/hosted/api/v1/models#model-deploymentconfig) |
| `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 `200`**
```json
{
"data": {
"settings": [
{
"key": "listener_max_connections",
"value": "500",
"default": "100",
"is_overridden": true
},
{
"key": "behavior_read_only",
"value": "false",
"default": "false",
"is_overridden": false
}
]
}
}
```
---
## Change some of a deployment's configuration overrides {#patchDeploymentConfig}
PATCH /api/v1/deployments/{owner}/{deployment}/config
Changes the overrides named in the body and leaves the rest alone, returning the configuration that results.
A key set to `null` is cleared and reverts to its default. This is the only way to remove a single override; omitting a key leaves it as it was, and an empty `overrides` object changes nothing.
Only a deployment administrator may change configuration. Values are strings whatever the setting's underlying type, and are validated against the same rules `GET` reports, so an unknown key or an out-of-range value is rejected rather than stored.
**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 |
|-------|------|----------|-------------|
| `overrides` | object | yes | Setting key to value, or to `null` to clear it. Keys are the `key` values `GET` reports; values are strings whatever the setting's underlying type, so a boolean is `"true"` or `"false"` and a number is its decimal digits. |
**Example request**
```sh
curl -X PATCH 'https://hosted.doltdb.com/api/v1/deployments/{owner}/{deployment}/config' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"overrides":{"behavior_auto_commit":"false"}}'
```
**Other request bodies**
_Clear one override without touching the others._
```json
{
"overrides": {
"listener_max_connections": null
}
}
```
**Responses**
| Status | Description | Schema |
|--------|-------------|--------|
| `200` | The configuration after the change. | [`DeploymentConfig`](/products/hosted/api/v1/models#model-deploymentconfig) |
| `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) |
| `422` | The request was well-formed but semantically invalid. | [`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": {
"settings": [
{
"key": "behavior_auto_commit",
"value": "false",
"default": "true",
"is_overridden": true
},
{
"key": "listener_max_connections",
"value": "100",
"default": "100",
"is_overridden": false
}
]
}
}
```
---
## List the versions a deployment can run {#listDeploymentDatabaseVersions}
GET /api/v1/deployments/{owner}/{deployment}/database-version
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) |
| `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 `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}
POST /api/v1/deployments/{owner}/{deployment}/database-version
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 Dolt credentials {#getDeploymentDoltCredentials}
GET /api/v1/deployments/{owner}/{deployment}/dolt-credentials
Returns the public half of the Dolt credentials the deployment uses to authenticate to DoltHub, so it can clone from and push to private databases. The private key is held by the deployment's instances and is never returned here.
These are not the deployment's SQL username and password, and not a way to connect to the deployment. They are a `dolt creds` key pair belonging to the deployment itself, and the public key is what you add to a DoltHub account to let the deployment in.
`404` when the deployment has no credentials, which is the state it starts in.
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 GET 'https://hosted.doltdb.com/api/v1/deployments/{owner}/{deployment}/dolt-credentials' \
-H 'Authorization: Bearer YOUR_TOKEN'
```
**Responses**
| Status | Description | Schema |
|--------|-------------|--------|
| `200` | The deployment's Dolt credentials. | [`DoltCredentials`](/products/hosted/api/v1/models#model-doltcredentials) |
| `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) |
| `422` | The request was well-formed but semantically invalid. | [`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": {
"key_id": "qi54ma4nlm0dvvhbrgv2p0lqmgs1kgnd",
"public_key": "7pnjqfqgqgqfhs5rgkcbhjqgxzqfnkqfhs5rgkcbhjqgxzqfnkqa"
}
}
```
---
## Issue Dolt credentials for a deployment {#createDeploymentDoltCredentials}
POST /api/v1/deployments/{owner}/{deployment}/dolt-credentials
Generates a `dolt creds` key pair, hands the private half to the deployment's instances, and records the public half. Use it once; to replace an existing key pair use `POST .../dolt-credentials/reroll`, which removes the old key in the same pass.
The work is queued, so this returns `202` with an operation to poll. The operation does not carry the key: read `GET .../dolt-credentials` once it succeeds.
Requires admin on the deployment, which must be `started`.
**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}/dolt-credentials' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json'
```
**Responses**
| Status | Description | Schema |
|--------|-------------|--------|
| `202` | The request to issue credentials was accepted and 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) |
| `409` | The request conflicts with the current state of the resource (e.g. it already exists). | [`Problem`](/products/hosted/api/v1/models#model-problem) |
| `422` | The request was well-formed but semantically invalid. | [`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"
}
}
```
---
## Remove a deployment's Dolt credentials {#deleteDeploymentDoltCredentials}
DELETE /api/v1/deployments/{owner}/{deployment}/dolt-credentials
Removes the key pair from the deployment's instances and clears the recorded public key. Anything on DoltHub that trusted that public key stops letting the deployment in.
The work is queued, so this returns `202` with an operation to poll rather than `204`. `GET .../dolt-credentials` answers `404` once it succeeds.
`404` when the deployment has no credentials to remove. 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 DELETE 'https://hosted.doltdb.com/api/v1/deployments/{owner}/{deployment}/dolt-credentials' \
-H 'Authorization: Bearer YOUR_TOKEN'
```
**Responses**
| Status | Description | Schema |
|--------|-------------|--------|
| `202` | The removal 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) |
| `422` | The request was well-formed but semantically invalid. | [`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"
}
}
```
---
## Replace a deployment's Dolt credentials {#rerollDeploymentDoltCredentials}
POST /api/v1/deployments/{owner}/{deployment}/dolt-credentials/reroll
Issues a new `dolt creds` key pair and requests removal of the old one in the same per-instance update. This is not an atomic change across the deployment: instances can temporarily disagree, and a failed operation does not roll back changes.
The new public key has to be added to DoltHub before the deployment can reach private databases again, so expect a gap between this succeeding and access being restored.
The work is queued, so this returns `202` with an operation to poll. Read `GET .../dolt-credentials` once it succeeds for the new public key.
`404` when the deployment has no credentials to replace; use `POST` to issue the first pair. 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}/dolt-credentials/reroll' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json'
```
**Responses**
| Status | Description | Schema |
|--------|-------------|--------|
| `202` | The replacement 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) |
| `422` | The request was well-formed but semantically invalid. | [`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}
GET /api/v1/deployments/{owner}/{deployment}/logs
Returns log lines from one of the deployment's instances, newest page first.
Logs come from a single instance. Omit `instance_id` and the deployment's primary is used, which is what you want unless you are chasing something on a specific replica; `GET /api/v1/deployments/{owner}/{deployment}/instances` lists the ids. Only instances that are not stopped can be read.
This endpoint pages in both directions: `meta.next_page_token` walks further back through history, `meta.prev_page_token` walks toward the present, and either goes back as the query parameter of the same name. Both may be present at once, and either can come back on a page with no lines, so stop paging on an empty page rather than on a missing token.
`start_time` and `end_time` bound the window; omit both for the most recent `lines` lines.
**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. |
| `instance_id` | query | string | no | Which instance to read. Defaults to the deployment's primary. `404` if the id names no live instance of this deployment. |
| `lines` | query | integer | no | How many lines to return at most. Defaults to 100. |
| `start_time` | query | string | no | Only return lines logged at or after this time. |
| `end_time` | query | string | no | Only return lines logged at or before this time. |
| `page_token` | query | string | no | The `meta.next_page_token` from a previous response, to read further back. Omit for the most recent page. |
| `prev_page_token` | query | string | no | The `meta.prev_page_token` from a previous response, to read toward the present. |
**Example request**
```sh
curl -X GET 'https://hosted.doltdb.com/api/v1/deployments/{owner}/{deployment}/logs' \
-H 'Authorization: Bearer YOUR_TOKEN'
```
**Responses**
| Status | Description | Schema |
|--------|-------------|--------|
| `200` | A page of log lines. | [`LogLine[]`](/products/hosted/api/v1/models#model-logline) |
| `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 responses `200`**
_Two lines with more history available._
```json
{
"data": [
{
"time": "2026-09-03T09:14:02.481Z",
"text": "2026-09-03T09:14:02Z INFO server ready on port 3306"
},
{
"time": "2026-09-03T09:14:07.902Z",
"text": "2026-09-03T09:14:07Z INFO accepted connection from 10.0.1.7"
}
],
"meta": {
"next_page_token": "eyJvZmZzZXQiOjI1fQ"
}
}
```
_A window with nothing in it._
```json
{
"data": []
}
```
---
## Expose or stop exposing a deployment's remotesapi or MCP endpoint {#exposeDeploymentService}
PATCH /api/v1/deployments/{owner}/{deployment}/expose
Turns one of the deployment's optional endpoints on or off. Send exactly one of `remotesapi` or `mcp`.
Returns `202`: the change is queued, not applied. Poll `GET /api/v1/deployments/{owner}/{deployment}` until `expose_remotesapi_endpoint` or `expose_mcp` reports the value you asked for. Those fields are written once the change reaches the deployment's instances, so they are the signal that it took effect — the `202` only confirms the request was accepted.
Exposing the remotesapi endpoint requires a WebPKI certificate; `webpki_cert` on the deployment says whether it has one, and a request without it returns `400`.
Asking for the value a deployment already has is accepted and does nothing.
**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 |
|-------|------|----------|-------------|
| `remotesapi` | boolean | no | Whether to serve the remotesapi endpoint, which is what `dolt clone` and `dolt pull` talk to. Requires the deployment to have a WebPKI certificate — `400` otherwise, since a public endpoint with a private CA is unusable. |
| `mcp` | boolean | no | Whether to serve the MCP endpoint. |
_Send exactly one of these fields._
**Example request**
```sh
curl -X PATCH 'https://hosted.doltdb.com/api/v1/deployments/{owner}/{deployment}/expose' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"mcp":true}'
```
**Other request bodies**
_Stop serving the remotesapi endpoint._
```json
{
"remotesapi": false
}
```
**Responses**
| Status | Description | Schema |
|--------|-------------|--------|
| `202` | The change was accepted and queued. | [`ExposeAccepted`](/products/hosted/api/v1/models#model-exposeaccepted) |
| `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": {
"owner": "acme",
"name": "analytics",
"service": "mcp",
"requested": true
}
}
```
---
## List a deployment's service windows {#listDeploymentServiceWindows}
GET /api/v1/deployments/{owner}/{deployment}/service-windows
Returns the weekly windows in which Hosted may restart the deployment's instances to apply maintenance.
A window covers whole hours in UTC on one day of the week. `start_hour_utc` is inclusive and `end_hour_utc` is exclusive, so 7 and 8 mean the hour beginning 07:00 UTC.
Every deployment has at least one. Until one is set, the list holds a single window with `is_default` set: Sunday 07:00 to 08:00 UTC.
**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}/service-windows' \
-H 'Authorization: Bearer YOUR_TOKEN'
```
**Responses**
| Status | Description | Schema |
|--------|-------------|--------|
| `200` | The deployment's service windows. | [`ServiceWindow[]`](/products/hosted/api/v1/models#model-servicewindow) |
| `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) |
| `422` | The request was well-formed but semantically invalid. | [`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 responses `200`**
_A window set for early Tuesday morning UTC._
```json
{
"data": [
{
"id": "7c1e9a3b-2d4f-4a6c-8b0d-1e2f3a4b5c6d",
"day_of_week": "tuesday",
"start_hour_utc": 3,
"end_hour_utc": 5,
"is_default": false
}
]
}
```
_A deployment with no window configured._
```json
{
"data": [
{
"id": "00000000-0000-0000-0000-000000000000",
"day_of_week": "sunday",
"start_hour_utc": 7,
"end_hour_utc": 8,
"is_default": true
}
]
}
```
---
## Disable a deployment {#disableDeployment}
POST /api/v1/deployments/{owner}/{deployment}/disable
Shuts the deployment down, tearing down its instances and their storage. Returns `202` with the deployment in `stopping`; poll `GET /api/v1/deployments/{owner}/{deployment}` until `state` is `stopped`.
**Take a backup first if you want the data.**
The deployment itself is not deleted. It stays readable with `disabled_at` and `disabled_by` set — which is why this is a `POST` to an action rather than a `DELETE` — and can be brought back by adding an instance with `POST /api/v1/deployments/{owner}/{deployment}/instances`; give that request a `backup_name` to restore the data, or it comes back empty.
Not idempotent: disabling a deployment that is already stopping or stopped returns `422`. The `202` only confirms acceptance — `GET` the deployment for its full state.
**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}/disable' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json'
```
**Responses**
| Status | Description | Schema |
|--------|-------------|--------|
| `202` | The teardown has been accepted. `state` is `stopping`. | [`DisableAccepted`](/products/hosted/api/v1/models#model-disableaccepted) |
| `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) |
| `422` | The request was well-formed but semantically invalid. | [`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": {
"owner": "acme",
"name": "analytics",
"state": "stopping"
}
}
```
---
## List a deployment's metrics {#listDeploymentMetrics}
GET /api/v1/deployments/{owner}/{deployment}/metrics
Returns the metrics this deployment collects. Each `id` is a value that `GET /api/v1/deployments/{owner}/{deployment}/metrics/{metric}` accepts.
The set is not the same for every deployment: it depends on the cloud the deployment runs in, on whether it is Dolt or MySQL with Dolt replicas, and on whether it has read replicas.
**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}/metrics' \
-H 'Authorization: Bearer YOUR_TOKEN'
```
**Responses**
| Status | Description | Schema |
|--------|-------------|--------|
| `200` | The metrics this deployment collects. | [`Metric[]`](/products/hosted/api/v1/models#model-metric) |
| `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) |
| `422` | The request was well-formed but semantically invalid. | [`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": [
{
"id": "connections",
"display_name": "Connections"
},
{
"id": "queries",
"display_name": "Queries"
},
{
"id": "query_latency",
"display_name": "Query Latency"
},
{
"id": "cpu",
"display_name": "CPU Utilization"
},
{
"id": "mem",
"display_name": "Memory Usage"
},
{
"id": "disk",
"display_name": "Disk Usage"
},
{
"id": "diskio",
"display_name": "Disk IO"
},
{
"id": "network",
"display_name": "Network"
}
]
}
```
---
## Read one of a deployment's metrics {#getDeploymentMetric}
GET /api/v1/deployments/{owner}/{deployment}/metrics/{metric}
Returns one metric's readings over a window of time, oldest first.
A metric is one or more series measured together, each named for what it measures and where it came from: `cpu` reports one series per host, and `network` reports bytes sent and bytes received for each host and interface, named like `Sent ip-10-0-0-125 ens3`. `timestamps` is the time axis they share, and every series has one value per timestamp. A `null` value means nothing was measured at that moment. It does not mean zero.
`period_seconds` is how far apart the readings are. Hosted chooses it from the width of the window, so a wider window comes back coarser. Do not work it out from `timestamps`, which leaves out any moment no series measured.
`start_time` and `end_time` default to the last hour. They must be in order and no more than 30 days apart, and the response echoes them back as asked. The readings themselves are minute-aligned: Hosted moves the start forward and the end backward to whole minutes before querying, so the first and last timestamps can sit inside the window rather than on its edges.
`GET /api/v1/deployments/{owner}/{deployment}/metrics` lists the metrics a deployment collects. Asking for one it does not collect is a `404`.
**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. |
| `metric` | path | string | yes | Which metric to read, as listed by `GET /api/v1/deployments/{owner}/{deployment}/metrics`. |
| `instance_id` | query | string | no | Which instance to read. Defaults to the deployment's primary. `404` if the id names no live instance of this deployment. |
| `start_time` | query | string | no | The start of the window, inclusive. Defaults to an hour before `end_time`. |
| `end_time` | query | string | no | The end of the window, inclusive. Defaults to now. |
**Example request**
```sh
curl -X GET 'https://hosted.doltdb.com/api/v1/deployments/{owner}/{deployment}/metrics/{metric}' \
-H 'Authorization: Bearer YOUR_TOKEN'
```
**Responses**
| Status | Description | Schema |
|--------|-------------|--------|
| `200` | The metric's series over the window. | [`MetricData`](/products/hosted/api/v1/models#model-metricdata) |
| `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) |
| `422` | The request was well-formed but semantically invalid. | [`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": {
"metric": "network",
"instance_id": "3f1c9e7a-3b6d-4c5e-8a9f-0d1e2f3a4b5c",
"start_time": "2026-09-09T12:00:00Z",
"end_time": "2026-09-09T12:03:00Z",
"period_seconds": 60,
"timestamps": [
"2026-09-09T12:00:00Z",
"2026-09-09T12:01:00Z",
"2026-09-09T12:02:00Z"
],
"series": [
{
"name": "Sent ip-10-0-0-125 ens3",
"unit": "Bytes",
"values": [
79210,
null,
72480
]
},
{
"name": "Received ip-10-0-0-125 ens3",
"unit": "Bytes",
"values": [
74120,
60240,
66310
]
}
]
}
}
```
---
## Remove an instance from a deployment {#deleteDeploymentInstance}
DELETE /api/v1/deployments/{owner}/{deployment}/instances/{id}
Removes an instance from `{owner}/{deployment}` and returns `202`. The instance is marked stopping and torn down in the background.
Poll `GET /api/v1/deployments/{owner}/{deployment}/instances` until the instance leaves the list. The list reports only instances that have not stopped; while it is present, its `state` distinguishes running from stopping.
Instances can only be removed when the deployment is settled. If it is stopping, or any instance is still starting or stopping, the request conflicts with the deployment's current state and is rejected with `409`. Retry once it settles. Removing an instance that has already stopped is `422`.
**This removes a database server and the data on its volume.** It is meant for removing a read replica, so check `is_primary` on the instances list before picking an id: removing the primary shuts the deployment down. To do that, use `POST /api/v1/deployments/{owner}/{deployment}/disable`, which records `disabled_at` and `disabled_by` — removing the instance leaves the deployment with nothing running and no record of why.
**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 DELETE 'https://hosted.doltdb.com/api/v1/deployments/{owner}/{deployment}/instances/{id}' \
-H 'Authorization: Bearer YOUR_TOKEN'
```
**Responses**
| Status | Description | Schema |
|--------|-------------|--------|
| `202` | The removal has been accepted and the instance is stopping. | [`InstanceDeleteAccepted`](/products/hosted/api/v1/models#model-instancedeleteaccepted) |
| `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) |
| `409` | The request conflicts with the current state of the resource (e.g. it already exists). | [`Problem`](/products/hosted/api/v1/models#model-problem) |
| `422` | The request was well-formed but semantically invalid. | [`Problem`](/products/hosted/api/v1/models#model-problem) |
| `500` | An unexpected server error occurred. | [`Problem`](/products/hosted/api/v1/models#model-problem) |
**Example response `202`**
```json
{
"data": {
"id": "2c4e6a8b-1d3f-4a5c-8e9b-0f1a2b3c4d5e",
"state": "stopping"
}
}
```
---
## Reboot one of a deployment's instances {#rebootDeploymentInstance}
POST /api/v1/deployments/{owner}/{deployment}/instances/{id}/reboot
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"
}
}
```
---
## Change the primary instance of a deployment {#changePrimary}
POST /api/v1/deployments/{owner}/{deployment}/change-primary
Starts an asynchronous primary switch for a deployment with at least one replica. Provide the id of the instance currently listed as primary; Hosted chooses the replacement from the replicas. Hosted verifies that the supplied id is still the deployment's primary before accepting the request. This prevents a stale request from overriding a newer primary change.
The `202` response means the request was queued, not that the primary has changed yet. Poll the returned operation until it reports `SUCCEEDED`, `FAILED`, or `EXPIRED`. When it reports `SUCCEEDED`, the primary change has completed; use the instances endpoint to see which instance is now primary. 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. |
**Request body**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `current_primary_id` | string | yes | The id of the instance that is currently primary. The request is rejected if it is stale or does not belong to this deployment. |
**Example request**
```sh
curl -X POST 'https://hosted.doltdb.com/api/v1/deployments/{owner}/{deployment}/change-primary' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"current_primary_id":"2c4e6a8b-1d3f-4a5c-8e9b-0f1a2b3c4d5e"}'
```
**Responses**
| Status | Description | Schema |
|--------|-------------|--------|
| `202` | The primary change was accepted and queued for processing. | [`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) |
| `409` | The request conflicts with the current state of the resource (e.g. it already exists). | [`Problem`](/products/hosted/api/v1/models#model-problem) |
| `422` | The request was well-formed but semantically invalid. | [`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"
}
}
```