Models#

Shared request and response types used across the v1 API. See the error model for how failures are reported.

ErrorCode#

A stable, machine-readable error code in SCREAMING_SNAKE_CASE. Clients branch on this value, never on the human-readable title/detail prose. The baseline codes below cover the standard HTTP failure categories; endpoint-specific codes (e.g. DEPLOYMENT_NOT_FOUND) are appended to this enum alongside the endpoints that emit them, which is an additive, non-breaking change under the v1 stability policy.

Enum values

Value
`VALIDATION_FAILED`
`UNAUTHENTICATED`
`PERMISSION_DENIED`
`NOT_FOUND`
`METHOD_NOT_ALLOWED`
`CONFLICT`
`UNPROCESSABLE`
`RATE_LIMITED`
`INTERNAL`
`SERVICE_UNAVAILABLE`
`OPERATION_FAILED`

Problem#

A structured error body returned for every non-2xx response, following RFC 9457 (Problem Details for HTTP APIs). This is the single error model for the entire v1 API — there are no ad-hoc error shapes.

Field	Type	Required	Description
`type`	`string`	yes	A URI identifying the problem type; when dereferenced it points at human-readable documentation for the error.
`title`	`string`	yes	A short, human-readable summary of the problem type.
`status`	`integer`	yes	The HTTP status code, repeated in the body for convenience.
`detail`	`string`	no	A human-readable explanation specific to this occurrence of the problem.
`instance`	`string`	no	A URI reference identifying the specific occurrence (typically the request path).
`code`	`string`	yes	A stable, machine-readable error code in SCREAMING_SNAKE_CASE. Clients branch on this value, never on the human-readable `title`/`detail` prose. The baseline codes below cover the standard HTTP failure categories; endpoint-specific codes (e.g. `DEPLOYMENT_NOT_FOUND`) are appended to this enum alongside the endpoints that emit them, which is an additive, non-breaking change under the v1 stability policy.
`request_id`	`string`	yes	The request identifier, echoed on every response. Include it when contacting support so a request can be traced end-to-end.

Meta#

Response metadata carried alongside the primary data payload. All fields are optional; list endpoints populate next_page_token for cursor pagination.

Field	Type	Required	Description
`next_page_token`	`string`	no	Opaque cursor for the next page of a list response. Absent when there are no further results — never present and empty — otherwise pass it back as the `page_token` query parameter to fetch the next page.

Envelope#

The success envelope wrapping every 2xx response body: the resource or list of resources under data, with optional meta. This is the single success shape for the API — there are no unenveloped success bodies. Endpoints narrow data to a concrete resource via allOf; the base leaves data unconstrained so that composition works.

Field	Type	Required	Description
`data`	`object,array`	yes	The primary response payload — a resource, or an array of resources for list endpoints.
`meta`	`object`	no	Response metadata carried alongside the primary `data` payload. All fields are optional; list endpoints populate `next_page_token` for cursor pagination.

UserEmailAddress#

An email address belonging to a user.

Field	Type	Required	Description
`address`	`string`	yes	The email address.
`is_verified`	`boolean`	yes	Whether the address has completed email verification.
`is_primary`	`boolean`	yes	Whether this is the user’s primary address. Exactly one address is primary.

User#

A Hosted user. GET /api/v1/user returns the authenticated user’s profile. v1 returns only public-facing profile fields — the identity provider the account signs in with, session state, and credential metadata are never included.

Field	Type	Required	Description
`username`	`string`	yes	The user’s Hosted username (unique handle).
`display_name`	`string`	no	The user’s display name. May be empty.
`company`	`string`	no	The user’s stated company. May be empty.
`email_addresses`	`array`	yes	The user’s email addresses. Returned only for the authenticated user themselves; empty for any other caller.

InstanceType#

A compute instance type a deployment can run on.

Field	Type	Required	Description
`id`	`string`	yes	The identifier `POST /api/v1/deployments` accepts as `instance_type_id`.
`name`	`string`	yes	The display name. A deployment reports this as `instance_type_name`.
`cpus`	`integer`	no	Virtual CPUs.
`memory_gb`	`integer`	no	Memory, in gigabytes.
`description`	`string`	no	A human-readable summary of what the instance suits.
`hourly_cost_usd`	`number`	no	Cost per hour in US dollars. Absent when no hourly price is published for this instance type.

StorageOption#

A storage type a deployment’s volume can use.

Field	Type	Required	Description
`id`	`string`	yes	The identifier `POST /api/v1/deployments` accepts as `volume_type_id`.
`name`	`string`	yes	The display name. A deployment reports this as `volume_type_name`.
`description`	`string`	no	A human-readable summary of the storage type.
`min_size_gb`	`integer`	no	Smallest volume size this type supports, in gigabytes. `volume_size_gb` on a create request must be at least this.
`max_size_gb`	`integer`	no	Largest volume size this type supports, in gigabytes.
`monthly_cost_usd_per_gb`	`number`	no	Cost per gigabyte per month, in US dollars.

DeploymentInstance#

One instance backing a deployment. A deployment has a primary and, when it has read replicas, one instance per replica.

Field	Type	Required	Description
`id`	`string`	yes	The instance’s identifier, unique within the deployment.
`index`	`integer`	yes	The instance’s position in the deployment. `0` is the first instance; replicas take the following indices.
`is_primary`	`boolean`	yes	Whether this instance is currently the primary. Exactly one instance of a started deployment is primary, and which one can change over the deployment’s life.
`host`	`string`	no	The hostname for this specific instance. Connect to the deployment’s own `host` unless you mean to address one instance directly.
`instance_type_name`	`string`	no	The display name of this instance’s type.
`volume_type_name`	`string`	no	The display name of this instance’s storage type.
`volume_size_gb`	`integer`	no	The size of this instance’s storage volume, in gigabytes.
`hourly_cost_usd`	`number`	no	This instance’s cost per hour, in US dollars. A deployment’s total is the sum across its instances.

DeploymentOptions#

The options available for creating a deployment, narrowed by the query parameters supplied. instance_types and storage_options are absent until enough of the chain has been supplied to determine them.

Field	Type	Required	Description
`cloud`	`string`	yes	The cloud the deployment runs in.
`zones`	`array`	yes	The zones this cloud supports.
`instance_types`	`array`	no	Instance types available in the requested `zone`. Absent when `zone` wasn’t supplied.
`storage_options`	`array`	no	Storage types compatible with the requested `instance_type_id`. Absent when `zone` and `instance_type_id` weren’t both supplied.

CreateDeploymentRequest#

The provisioning parameters for a new deployment.

v1.0 exposes the core parameters only. Restoring from a backup, cloning an existing deployment, workbench user settings, and private networking are all settable on the internal API but are not part of this request; each is its own feature with its own contract, and adding them is additive. The internal deployment test flag is deliberately not exposed at all.

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`	`string`	yes	The cloud the deployment runs in.
`zone`	`string`	yes	The cloud region to provision in, as listed by the deployment options.
`cluster_type`	`string`	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.

DeploymentState#

The deployment’s lifecycle state. starting covers both initial provisioning and a restart; poll this field to observe a create or a resize reaching started.

Enum values

Value
`starting`
`started`
`stopping`
`stopped`

CloudProvider#

The cloud the deployment runs in.

Enum values

Value
`aws`
`gcp`
`azure`

ClusterType#

The database engine the deployment runs. mysql_with_dolt_replicas is a MySQL primary with Dolt read replicas.

Enum values

Value
`dolt`
`doltgres`
`mysql_with_dolt_replicas`

DeploymentRole#

The authenticated caller’s role on this deployment. Always present on a read, since a caller without at least read access cannot retrieve the deployment at all.

Enum values

Value
`admin`
`writer`
`reader`
`reader_and_pulls`

DeploymentSummary#

A deployment as it appears in a list.

This is deliberately not the same shape as Deployment. The list RPC returns a narrower record — it omits connection details, the caller’s role, and the creation audit fields, and it adds the last-backup figures shown in fleet views. Read the deployment itself for the full resource. As with Deployment, database credentials are never included.

Field	Type	Required	Description
`owner`	`string`	yes	The user or organization that owns the deployment.
`name`	`string`	yes	The deployment name, unique within the owner.
`state`	`string`	yes	The deployment’s lifecycle state. `starting` covers both initial provisioning and a restart; poll this field to observe a create or a resize reaching `started`.
`cloud`	`string`	yes	The cloud the deployment runs in.
`zone`	`string`	yes	The cloud region the deployment runs in.
`cluster_type`	`string`	yes	The database engine the deployment runs. `mysql_with_dolt_replicas` is a MySQL primary with Dolt read replicas.
`instance_type_name`	`string`	no	The display name of the deployment’s instance type.
`volume_type_name`	`string`	no	The display name of the deployment’s storage type.
`volume_size_gb`	`integer`	no	The size of the deployment’s storage volume, in gigabytes.
`replicas`	`integer`	no	The number of read replicas. `0` for a single-instance deployment.
`database_version`	`string`	no	The version of the database engine the deployment is running — a Dolt version for a `dolt` cluster, a Doltgres version for a `doltgres` one.
`hourly_cost_usd`	`number`	no	The deployment’s current cost per hour, in US dollars.
`webpki_cert`	`boolean`	no	Whether the deployment serves a publicly-trusted (WebPKI) TLS certificate.
`last_backup_size_bytes`	`integer`	no	Size of the most recent backup, in bytes. Absent when no backup has been taken or its size has not been computed yet.
`last_backup_time`	`string`	no	When the most recent backup was taken. Absent when no backup has been taken.

Deployment#

A Hosted Dolt deployment.

v1 returns configuration and lifecycle state only. The deployment’s database credentials are deliberately not part of this resource — they are issued and rotated through the deployment credentials endpoints, so that reading a deployment is never a credential-disclosing operation.

Provider-specific private-networking configuration (AWS PrivateLink, GCP Private Service Connect, Azure Private Link) is not included in v1.0. Each carries its own endpoint collection and provisioning state, and will land as its own sub-resource; adding it is additive under the stability policy.

Field	Type	Required	Description
`owner`	`string`	yes	The user or organization that owns the deployment.
`name`	`string`	yes	The deployment name, unique within the owner.
`state`	`string`	yes	The deployment’s lifecycle state. `starting` covers both initial provisioning and a restart; poll this field to observe a create or a resize reaching `started`.
`cloud`	`string`	yes	The cloud the deployment runs in.
`zone`	`string`	yes	The cloud region the deployment runs in.
`cluster_type`	`string`	yes	The database engine the deployment runs. `mysql_with_dolt_replicas` is a MySQL primary with Dolt read replicas.
`instance_type_name`	`string`	no	The display name of the deployment’s instance type. Note this is the name, not the id that `POST /api/v1/deployments` accepts; both are listed by the deployment options endpoint.
`volume_type_name`	`string`	no	The display name of the deployment’s storage type. As with `instance_type_name`, this is the name rather than the id used to create a deployment.
`volume_size_gb`	`integer`	no	The size of the deployment’s storage volume, in gigabytes.
`replicas`	`integer`	no	The number of read replicas. `0` for a single-instance deployment.
`database_version`	`string`	no	The version of the database engine the deployment is running — a Dolt version for a `dolt` cluster, a Doltgres version for a `doltgres` one.
`host`	`string`	no	The hostname clients connect to. Empty until the deployment reaches `started`.
`port`	`integer`	no	The port clients connect to.
`hourly_cost_usd`	`number`	no	The deployment’s current cost per hour, in US dollars.
`webpki_cert`	`boolean`	no	Whether the deployment serves a publicly-trusted (WebPKI) TLS certificate rather than a Hosted-issued one.
`expose_remotesapi_endpoint`	`boolean`	no	Whether the deployment exposes a Dolt remotes API endpoint.
`expose_mcp`	`boolean`	no	Whether the deployment exposes an MCP endpoint.
`expose_stats`	`boolean`	no	Whether the deployment exposes a statistics endpoint.
`disable_automatic_dolt_updates`	`boolean`	no	Whether automatic Dolt version updates are disabled for this deployment.
`caller_role`	`string`	yes	The authenticated caller’s role on this deployment. Always present on a read, since a caller without at least read access cannot retrieve the deployment at all.
`created_by`	`string`	no	The username of the user who created the deployment.
`created_at`	`string`	yes	When the deployment was created.
`destroy_at`	`string`	no	When the deployment is scheduled to be destroyed. Absent unless a destroy has been scheduled.
`destroyed_by`	`string`	no	The username of the user who destroyed the deployment. Absent unless it has been destroyed.