> For the complete documentation index, see [llms.txt](https://docs.spice.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.spice.ai/api/management-api/dedicated-clusters.md). # Dedicated Clusters An organization on an enterprise plan can have one or more **dedicated clusters**: Spice-managed, single-tenant infrastructure where an organization's apps run only alongside other apps from the same organization — never on shared infrastructure. Each cluster has its own `cluster_name`, isolated network, and connection endpoint. Dedicated clusters are provisioned by Spice.ai and requested through [support](https://spice.ai/support). Once a cluster is provisioned and registered to an organization, it is available to the Management API and in the Portal's app-creation picker. ## Listing clusters `GET /v1/clusters` returns the dedicated clusters registered to the organization bound to the access token. It requires the `apps:read` scope. ```bash curl -H "Authorization: Bearer " \ https://api.spice.ai/v1/clusters ``` ```json { "clusters": [ { "cluster_name": "acme-prod-sandbox", "region": "us-west-2", "cloud_provider": "aws", "endpoint": "https://private-acme-prod-sandbox-us-west-2-prod-data.spiceai.io", "created_at": "2026-06-11T00:00:00Z", "updated_at": "2026-06-11T00:00:00Z" } ] } ``` * **`cluster_name`** — the cluster's identifier, used when creating or reassigning apps. * **`endpoint`** — the cluster's data-plane endpoint (an `https://` URL); apps running on the cluster are reached at this URL. ## Creating an app on a dedicated cluster A create request specifies `cluster_name` instead of `region`, set to a `cluster_name` returned by `GET /v1/clusters`. Exactly one of the two is provided; the app's region is derived from the cluster. The request requires the `apps:write` scope. ```bash curl -X POST https://api.spice.ai/v1/apps \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "name": "my-app", "cluster_name": "acme-prod-sandbox", "description": "An app on a dedicated cluster" }' ``` The response includes the resolved assignment and the cluster's endpoint: ```json { "id": 123, "name": "my-app", "cluster_name": "acme-prod-sandbox", "endpoint": "https://private-acme-prod-sandbox-us-west-2-prod-data.spiceai.io", "...": "..." } ``` An app created without `cluster_name` deploys to the shared regional infrastructure as usual; `cluster_name: null` is equivalent to omitting it. {% hint style="info" %} If `region` is also provided it must match the cluster's region. {% endhint %} ### Errors | Status | Cause | | --------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | `400` `Cluster '' not found` | The cluster does not exist or is not registered to the organization | | `400` `'' is not a deployable cluster` | The name is not a deployable cluster — a `cluster_name` from `GET /v1/clusters` is required | | `400` `region '' does not match cluster region ''` | An explicit `region` was provided that differs from the cluster's region | ## Moving an existing app to a dedicated cluster `PUT /v1/apps/{appId}` with `cluster_name` reassigns the app. Subsequent deployments land on the cluster, and the app's endpoint changes to the cluster's host. ```bash curl -X PUT https://api.spice.ai/v1/apps/123 \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"cluster_name": "acme-prod-sandbox"}' ``` {% hint style="warning" %} Reassigning an app changes its data and Flight endpoints. Clients that pin the old hostnames must be updated, and a new [deployment](/api/management-api/management.md#create-a-deployment) created so the app's runtime is placed on the cluster. {% endhint %} ## Querying apps on a dedicated cluster The app and `GET /v1/clusters` responses return the cluster's `endpoint` — the URL clients connect to. It serves the same APIs (SQL, search, and LLM over HTTP, plus Apache Arrow Flight), and authentication is unchanged — the app's [API key](https://github.com/spicehq/docs/blob/trunk/cloud/portal/apps/api-keys.md) or platform credentials work exactly as on shared infrastructure. For Apache Arrow Flight, the endpoint's host is used with `-data` replaced by `-flight`, over `grpc+tls://:443`. With the [SDKs](https://github.com/spicehq/docs/blob/trunk/sdks/README.md), the endpoint replaces the `data.spiceai.io` / `flight.spiceai.io` defaults. For example, with the [Python SDK](https://github.com/spicehq/docs/blob/trunk/sdks/python-sdk/README.md) over Flight: ```python from spicepy import Client client = Client( api_key="", url="grpc+tls://private-acme-prod-sandbox-us-west-2-prod-flight.spiceai.io:443", ) ``` Everything else — deployments, secrets, API keys, spicepod configuration — works identically to apps on shared infrastructure. The [Management APIs](/api/management-api/management.md) reference documents the full endpoint set. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.spice.ai/api/management-api/dedicated-clusters.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.