Deployment#

Hosted Dolt deployments and their lifecycle.

List the options a deployment can be created with#

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

Example request

curl -X GET 'https://hosted.doltdb.com/api/v1/deployment-options?cloud=aws' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

Example response 200

{
  "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#

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

Example request

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

Example response 202

{
  "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#

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

Example request

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

Responses

Example response 200

{
  "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#

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

Example request

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

Responses

Example response 200

{
  "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#

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

Request body

Send at least one of these fields.

Example request

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

Example response 200

{
  "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#

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. So an instance appearing here is part of the deployment but not necessarily serving traffic, and an empty array means it 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

Example request

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

Responses

Example response 200

{
  "data": [
    {
      "id": "9b1f5c2e-4d3a-4f8b-9c0d-1e2f3a4b5c6d",
      "index": 0,
      "is_primary": true,
      "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,
      "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#

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 has no host yet. Poll GET /api/v1/deployments/{owner}/{deployment}/instances until that instance reports a host; that is when it is reachable. There is no per-instance state field to watch.

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

Request body

Example request

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

Example response 202

{
  "data": {
    "id": "2c4e6a8b-1d3f-4a5c-8e9b-0f1a2b3c4d5e",
    "index": 1,
    "is_primary": false,
    "instance_type_name": "t2.medium",
    "volume_type_name": "Trial 50GB EBS",
    "volume_size_gb": 50
  }
}

List a deployment’s backups#

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

Example request

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

Responses

Example response 200

{
  "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#

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

Example request

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

Responses

Example response 202

{
  "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#

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

Example request

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

Responses

Example response 200

{
  "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#

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

Request body

Example request

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.

{
  "overrides": {
    "listener_max_connections": null
  }
}

Responses

Example response 200

{
  "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#

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

Example request

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

Responses

Example response 200

{
  "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#

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

Request body

Example request

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

Example response 202

{
  "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#

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

Example request

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

Responses

Example response 200

{
  "data": {
    "key_id": "qi54ma4nlm0dvvhbrgv2p0lqmgs1kgnd",
    "public_key": "7pnjqfqgqgqfhs5rgkcbhjqgxzqfnkqfhs5rgkcbhjqgxzqfnkqa"
  }
}

Issue Dolt credentials for a deployment#

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

Example request

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

Example response 202

{
  "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#

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

Example request

curl -X DELETE 'https://hosted.doltdb.com/api/v1/deployments/{owner}/{deployment}/dolt-credentials' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

Example response 202

{
  "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#

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

Example request

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

Example response 202

{
  "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#

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

Example request

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

Responses

Example responses 200

Two lines with more history available.

{
  "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.

{
  "data": []
}

Expose or stop exposing a deployment’s remotesapi or MCP endpoint#

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

Request body

Send exactly one of these fields.

Example request

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.

{
  "remotesapi": false
}

Responses

Example response 202

{
  "data": {
    "owner": "acme",
    "name": "analytics",
    "service": "mcp",
    "requested": true
  }
}

List a deployment’s service windows#

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

Example request

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

Responses

Example responses 200

A window set for early Tuesday morning UTC.

{
  "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.

{
  "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#

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

Example request

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

Responses

Example response 202

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

List a deployment’s metrics#

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

Example request

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

Responses

Example response 200

{
  "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#

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

Example request

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

Responses

Example response 200

{
  "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#

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.

There is no per-instance state on this API, so completion is observed by the instance leaving GET /api/v1/deployments/{owner}/{deployment}/instances — that list reports only instances that have not stopped. An instance that is still present is either running or still 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

Example request

curl -X DELETE 'https://hosted.doltdb.com/api/v1/deployments/{owner}/{deployment}/instances/{id}' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

Example response 202

{
  "data": {
    "id": "2c4e6a8b-1d3f-4a5c-8e9b-0f1a2b3c4d5e",
    "state": "stopping"
  }
}

Reboot one of a deployment’s instances#

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

Example request

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

Example response 202

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