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"
  }
}

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
    }
  ]
}