> 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/management/deployments.md).

# Deployments

Create and monitor project deployments

## List deployments

> Returns a list of deployments for the specified project, ordered by most recent first.

```json
{"openapi":"3.1.0","info":{"title":"Spice Cloud Control-Plane API","version":"v1"},"tags":[{"name":"Deployments","description":"Create and monitor project deployments"}],"servers":[{"url":"https://api.spice.ai"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth 2.0 access token obtained from the Spice.ai authentication service"}},"parameters":{"OrgName":{"in":"header","name":"X-Org-Name","required":false,"description":"The organization to act on, by handle. Omit it to act on the organization the credential is bound to; sending it blank is a 400, not the same as omitting it. A user credential may name any organization its owner belongs to; a machine credential is pinned to its own.\n","schema":{"type":"string","pattern":"^[A-Za-z0-9._-]{1,255}$"}}},"schemas":{"Deployment":{"type":"object","properties":{"id":{"type":"integer","description":"Unique identifier for the deployment"},"status":{"type":"string","enum":["queued","in_progress","succeeded","failed","created"],"description":"Current status of the deployment"},"created_at":{"type":"string","format":"date-time","description":"Timestamp when the deployment was created"},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Timestamp when the deployment was last updated"},"image_tag":{"type":"string","nullable":true,"description":"Runtime image tag used for this deployment"},"replicas":{"type":"integer","description":"Number of replicas"},"branch":{"type":"string","nullable":true,"description":"Git branch name"},"commit_sha":{"type":"string","nullable":true,"description":"Git commit SHA"},"commit_message":{"type":"string","nullable":true,"description":"Git commit message"},"error_code":{"type":"string","nullable":true,"description":"Set with error_message on failed and on in_progress while Cloud is retrying a scheduling block. Null on succeeded, on ordinary waiting in_progress, and on writers that predated this column. Older failed rows may still have a message with a null code."},"error_message":{"type":"string","nullable":true,"description":"Catalog copy for the current error_code. Older failed rows may still have a message with a null error_code."},"creation_source":{"type":"string","nullable":true,"description":"Source that triggered the deployment"},"created_by":{"type":"integer","nullable":true,"description":"User ID who created the deployment"}}}}},"paths":{"/v1/projects/{projectId}/deployments":{"get":{"summary":"List deployments","description":"Returns a list of deployments for the specified project, ordered by most recent first.","parameters":[{"in":"path","name":"projectId","required":true,"schema":{"type":"integer"},"description":"The ID of the project"},{"in":"query","name":"limit","schema":{"type":"integer","default":20},"description":"Maximum number of deployments to return"},{"in":"query","name":"status","schema":{"type":"string","enum":["queued","in_progress","succeeded","failed","created"]},"description":"Filter by deployment status"},{"$ref":"#/components/parameters/OrgName"}],"responses":{"200":{"description":"List of deployments","content":{"application/json":{"schema":{"type":"object","properties":{"deployments":{"type":"array","items":{"$ref":"#/components/schemas/Deployment"}}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Insufficient scope"},"404":{"description":"Project not found"}},"tags":["Deployments"]}}}}
```

## Create a deployment

> Creates a new deployment for the specified project using its current spicepod configuration. The runtime image is selected based on the project's update channel.

```json
{"openapi":"3.1.0","info":{"title":"Spice Cloud Control-Plane API","version":"v1"},"tags":[{"name":"Deployments","description":"Create and monitor project deployments"}],"servers":[{"url":"https://api.spice.ai"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth 2.0 access token obtained from the Spice.ai authentication service"}},"parameters":{"OrgName":{"in":"header","name":"X-Org-Name","required":false,"description":"The organization to act on, by handle. Omit it to act on the organization the credential is bound to; sending it blank is a 400, not the same as omitting it. A user credential may name any organization its owner belongs to; a machine credential is pinned to its own.\n","schema":{"type":"string","pattern":"^[A-Za-z0-9._-]{1,255}$"}}},"schemas":{"Deployment":{"type":"object","properties":{"id":{"type":"integer","description":"Unique identifier for the deployment"},"status":{"type":"string","enum":["queued","in_progress","succeeded","failed","created"],"description":"Current status of the deployment"},"created_at":{"type":"string","format":"date-time","description":"Timestamp when the deployment was created"},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Timestamp when the deployment was last updated"},"image_tag":{"type":"string","nullable":true,"description":"Runtime image tag used for this deployment"},"replicas":{"type":"integer","description":"Number of replicas"},"branch":{"type":"string","nullable":true,"description":"Git branch name"},"commit_sha":{"type":"string","nullable":true,"description":"Git commit SHA"},"commit_message":{"type":"string","nullable":true,"description":"Git commit message"},"error_code":{"type":"string","nullable":true,"description":"Set with error_message on failed and on in_progress while Cloud is retrying a scheduling block. Null on succeeded, on ordinary waiting in_progress, and on writers that predated this column. Older failed rows may still have a message with a null code."},"error_message":{"type":"string","nullable":true,"description":"Catalog copy for the current error_code. Older failed rows may still have a message with a null error_code."},"creation_source":{"type":"string","nullable":true,"description":"Source that triggered the deployment"},"created_by":{"type":"integer","nullable":true,"description":"User ID who created the deployment"}}}}},"paths":{"/v1/projects/{projectId}/deployments":{"post":{"summary":"Create a deployment","description":"Creates a new deployment for the specified project using its current spicepod configuration. The runtime image is selected based on the project's update channel.","parameters":[{"in":"path","name":"projectId","required":true,"schema":{"type":"integer"},"description":"The ID of the project"},{"$ref":"#/components/parameters/OrgName"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"image_tag":{"type":"string","description":"Override the runtime image tag for this deployment. Requires the Enterprise plan; omit it to deploy the image the project is configured with. When the effective update channel is `stable` or `preview`, a supplied tag must be a published version for that channel. When the effective update channel is `nightly`, a supplied tag must be a published `spicehq/spiceai` `nightly-*` tag (`YYYYMMDDHHmm` plus `-` plus 7 to 40 lowercase hex characters, for example `202609081124-cadf292`)."},"channel":{"type":"string","enum":["stable","preview","nightly"],"description":"Update channel that determines the runtime image"},"expected_update_channel":{"type":"string","enum":["stable","preview","nightly"],"description":"If set, the stored project update channel must match this value or the request is refused with 409 `update_channel_mismatch`. This is a precondition, not an override (`channel` still changes the image train).\n"},"replicas":{"type":"integer","minimum":1,"maximum":10,"description":"Override the number of replicas for this deployment"},"branch":{"type":"string","description":"Git branch name"},"commit_sha":{"type":"string","description":"Git commit SHA"},"commit_message":{"type":"string","description":"Git commit message"},"debug":{"type":"boolean","description":"Enable debug mode for this deployment"},"target":{"type":"object","description":"Optional per-deployment override. Omit (or `{ kind: cloud }`) to place the deployment where the project itself runs — Spice-managed compute, its own BYOC cluster, or its attached standalone Cloud Connect instance — which is a property of the project, not of this request. Pass `{ kind: cluster, instance_id }` to override that for this deployment and route it to a BYOC cluster connection; the cluster must be owned by the token's org, not in a terminal lifecycle state (decommissioning/archived), not paused, and the operator must hold a live connection (verified by the connectivity ping, not the Supabase lifecycle status). A standalone project cannot be overridden this way and is refused with 409.\n","properties":{"kind":{"type":"string","enum":["cloud","cluster"]},"instance_id":{"type":"string","description":"Required when kind is `cluster`."}}}}}}}},"responses":{"202":{"description":"Deployment created and queued for processing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deployment"}}}},"400":{"description":"Invalid request body, project has no spicepod configuration, the spicepod has been deleted, or the spicepod is paused (`code: spicepod_paused`; resume it with POST /v1/projects/{projectId}/resume before deploying). For a standalone Cloud Connect project, also returned when the Spicepod references a `${secrets:...}` name the project does not define: the body carries `code: unknown_secret_references`, a `missing_secrets` array of `{name, path, suggestion?}`, and `secrets_url`. When the effective update channel is `stable` or `preview` and `image_tag` is supplied, the tag must be a published version for that channel or the body is `{ error: 'Invalid image_tag for stable channel', code: 'invalid_stable_image_tag' }` (or the preview analog). When the effective update channel is `nightly` and `image_tag` is supplied, the tag must be a published `spicehq/spiceai` `nightly-*` tag of the form `YYYYMMDDHHmm` plus `-` plus 7 to 40 lowercase hex characters (for example `202609081124-cadf292`) or the body is `{ error: 'Invalid image_tag for nightly channel', code: 'invalid_nightly_image_tag' }`. Nothing is dispatched and no deployment is recorded.\n"},"401":{"description":"Unauthorized"},"403":{"description":"Insufficient scope, viewer role cannot create deployments, `image_tag` was supplied outside the Enterprise plan (code: `image_tag_requires_enterprise`), or the requested runtime image is not available for the organization plan (code: `image_tag_not_allowed_for_plan`); omitting `image_tag` deploys the image the project is configured with"},"404":{"description":"Project not found — or, for a `cluster` target, the BYOC cluster connection does not exist or is not owned by the token's org.\n"},"409":{"description":"A deployment is already in progress for this project (`code: deployment_in_progress`, with optional `activeDeploymentId`) — or, for a `cluster` target, the BYOC cluster is paused, offline, or otherwise not in a deployable state. Also returned when the project's deploy target is unusable: its kind conflicts with its cluster/instance references, a `cluster` target was requested for a standalone project, a standalone project has no attached instance, or that instance has not yet enrolled the encryption key its secrets are sealed to (retrying once it is online succeeds). Also returned when `expected_update_channel` does not match the stored spicepod update channel, or when that channel changes before dispatch (`code: update_channel_mismatch`).\n"},"413":{"description":"Request body exceeds the maximum size (1 MiB), or — for a standalone Cloud Connect project — the project's resolved secrets exceed the maximum sealed-payload size. Nothing is dispatched and no deployment is recorded.\n"},"422":{"description":"Organization is not fully configured, or no runtime version in the catalog matches this project’s version range (`code: version_no_match`).\n"},"500":{"description":"Internal server error. For a standalone Cloud Connect project, also returned with `code: deployment_not_settled` when the deployment record could not be moved out of `queued`; the project's next deployment is refused until it is cleared.\n"},"502":{"description":"Upstream service failure while provisioning the deployment, or — for a standalone Cloud Connect project — the spicepod could not be handed to the instance's gateway, or the instance rejected it.\n"},"503":{"description":"The runtime version catalog is unavailable or empty (`code: version_source_unavailable`), so an unpinned stable or preview deploy cannot resolve an image tag — or catalog membership for an explicit `image_tag` override cannot be validated. Also returned when the published nightly tag list cannot be loaded to validate a nightly `image_tag` override.\n"}},"tags":["Deployments"]}}}}
```

## Get a deployment

> Returns a single deployment for the specified project. The body matches one item from GET /v1/projects/{projectId}/deployments. Not cacheable. Poll this path for stored status after POST create.

```json
{"openapi":"3.1.0","info":{"title":"Spice Cloud Control-Plane API","version":"v1"},"tags":[{"name":"Deployments","description":"Create and monitor project deployments"}],"servers":[{"url":"https://api.spice.ai"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth 2.0 access token obtained from the Spice.ai authentication service"}},"parameters":{"OrgName":{"in":"header","name":"X-Org-Name","required":false,"description":"The organization to act on, by handle. Omit it to act on the organization the credential is bound to; sending it blank is a 400, not the same as omitting it. A user credential may name any organization its owner belongs to; a machine credential is pinned to its own.\n","schema":{"type":"string","pattern":"^[A-Za-z0-9._-]{1,255}$"}}},"schemas":{"Deployment":{"type":"object","properties":{"id":{"type":"integer","description":"Unique identifier for the deployment"},"status":{"type":"string","enum":["queued","in_progress","succeeded","failed","created"],"description":"Current status of the deployment"},"created_at":{"type":"string","format":"date-time","description":"Timestamp when the deployment was created"},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Timestamp when the deployment was last updated"},"image_tag":{"type":"string","nullable":true,"description":"Runtime image tag used for this deployment"},"replicas":{"type":"integer","description":"Number of replicas"},"branch":{"type":"string","nullable":true,"description":"Git branch name"},"commit_sha":{"type":"string","nullable":true,"description":"Git commit SHA"},"commit_message":{"type":"string","nullable":true,"description":"Git commit message"},"error_code":{"type":"string","nullable":true,"description":"Set with error_message on failed and on in_progress while Cloud is retrying a scheduling block. Null on succeeded, on ordinary waiting in_progress, and on writers that predated this column. Older failed rows may still have a message with a null code."},"error_message":{"type":"string","nullable":true,"description":"Catalog copy for the current error_code. Older failed rows may still have a message with a null error_code."},"creation_source":{"type":"string","nullable":true,"description":"Source that triggered the deployment"},"created_by":{"type":"integer","nullable":true,"description":"User ID who created the deployment"}}}}},"paths":{"/v1/projects/{projectId}/deployments/{deploymentId}":{"get":{"summary":"Get a deployment","description":"Returns a single deployment for the specified project. The body matches one item from GET /v1/projects/{projectId}/deployments. Not cacheable. Poll this path for stored status after POST create.","parameters":[{"in":"path","name":"projectId","required":true,"schema":{"type":"integer"},"description":"The ID of the project"},{"in":"path","name":"deploymentId","required":true,"schema":{"type":"integer"},"description":"The ID of the deployment"},{"$ref":"#/components/parameters/OrgName"}],"responses":{"200":{"description":"Deployment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deployment"}}}},"400":{"description":"Invalid project ID or deployment ID"},"401":{"description":"Unauthorized"},"403":{"description":"Insufficient scope"},"404":{"description":"Project or deployment not found"},"500":{"description":"Internal server error"}},"tags":["Deployments"]}}}}
```

## List deployments

> Legacy alias of \`/v1/projects/{projectId}/deployments\` — projects were previously called apps. Returns a list of deployments for the specified project, ordered by most recent first.

```json
{"openapi":"3.1.0","info":{"title":"Spice Cloud Control-Plane API","version":"v1"},"tags":[{"name":"Deployments","description":"Create and monitor project deployments"}],"servers":[{"url":"https://api.spice.ai"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth 2.0 access token obtained from the Spice.ai authentication service"}},"parameters":{"OrgName":{"in":"header","name":"X-Org-Name","required":false,"description":"The organization to act on, by handle. Omit it to act on the organization the credential is bound to; sending it blank is a 400, not the same as omitting it. A user credential may name any organization its owner belongs to; a machine credential is pinned to its own.\n","schema":{"type":"string","pattern":"^[A-Za-z0-9._-]{1,255}$"}}},"schemas":{"Deployment":{"type":"object","properties":{"id":{"type":"integer","description":"Unique identifier for the deployment"},"status":{"type":"string","enum":["queued","in_progress","succeeded","failed","created"],"description":"Current status of the deployment"},"created_at":{"type":"string","format":"date-time","description":"Timestamp when the deployment was created"},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Timestamp when the deployment was last updated"},"image_tag":{"type":"string","nullable":true,"description":"Runtime image tag used for this deployment"},"replicas":{"type":"integer","description":"Number of replicas"},"branch":{"type":"string","nullable":true,"description":"Git branch name"},"commit_sha":{"type":"string","nullable":true,"description":"Git commit SHA"},"commit_message":{"type":"string","nullable":true,"description":"Git commit message"},"error_code":{"type":"string","nullable":true,"description":"Set with error_message on failed and on in_progress while Cloud is retrying a scheduling block. Null on succeeded, on ordinary waiting in_progress, and on writers that predated this column. Older failed rows may still have a message with a null code."},"error_message":{"type":"string","nullable":true,"description":"Catalog copy for the current error_code. Older failed rows may still have a message with a null error_code."},"creation_source":{"type":"string","nullable":true,"description":"Source that triggered the deployment"},"created_by":{"type":"integer","nullable":true,"description":"User ID who created the deployment"}}}}},"paths":{"/v1/apps/{appId}/deployments":{"get":{"summary":"List deployments","description":"Legacy alias of `/v1/projects/{projectId}/deployments` — projects were previously called apps. Returns a list of deployments for the specified project, ordered by most recent first.","parameters":[{"in":"path","name":"appId","required":true,"schema":{"type":"integer"},"description":"The ID of the project"},{"in":"query","name":"limit","schema":{"type":"integer","default":20},"description":"Maximum number of deployments to return"},{"in":"query","name":"status","schema":{"type":"string","enum":["queued","in_progress","succeeded","failed","created"]},"description":"Filter by deployment status"},{"$ref":"#/components/parameters/OrgName"}],"responses":{"200":{"description":"List of deployments","content":{"application/json":{"schema":{"type":"object","properties":{"deployments":{"type":"array","items":{"$ref":"#/components/schemas/Deployment"}}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Insufficient scope"},"404":{"description":"Project not found"}},"tags":["Deployments"],"deprecated":true}}}}
```

## Create a deployment

> Legacy alias of \`/v1/projects/{projectId}/deployments\` — projects were previously called apps. Creates a new deployment for the specified project using its current spicepod configuration. The runtime image is selected based on the project's update channel.

```json
{"openapi":"3.1.0","info":{"title":"Spice Cloud Control-Plane API","version":"v1"},"tags":[{"name":"Deployments","description":"Create and monitor project deployments"}],"servers":[{"url":"https://api.spice.ai"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth 2.0 access token obtained from the Spice.ai authentication service"}},"parameters":{"OrgName":{"in":"header","name":"X-Org-Name","required":false,"description":"The organization to act on, by handle. Omit it to act on the organization the credential is bound to; sending it blank is a 400, not the same as omitting it. A user credential may name any organization its owner belongs to; a machine credential is pinned to its own.\n","schema":{"type":"string","pattern":"^[A-Za-z0-9._-]{1,255}$"}}},"schemas":{"Deployment":{"type":"object","properties":{"id":{"type":"integer","description":"Unique identifier for the deployment"},"status":{"type":"string","enum":["queued","in_progress","succeeded","failed","created"],"description":"Current status of the deployment"},"created_at":{"type":"string","format":"date-time","description":"Timestamp when the deployment was created"},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Timestamp when the deployment was last updated"},"image_tag":{"type":"string","nullable":true,"description":"Runtime image tag used for this deployment"},"replicas":{"type":"integer","description":"Number of replicas"},"branch":{"type":"string","nullable":true,"description":"Git branch name"},"commit_sha":{"type":"string","nullable":true,"description":"Git commit SHA"},"commit_message":{"type":"string","nullable":true,"description":"Git commit message"},"error_code":{"type":"string","nullable":true,"description":"Set with error_message on failed and on in_progress while Cloud is retrying a scheduling block. Null on succeeded, on ordinary waiting in_progress, and on writers that predated this column. Older failed rows may still have a message with a null code."},"error_message":{"type":"string","nullable":true,"description":"Catalog copy for the current error_code. Older failed rows may still have a message with a null error_code."},"creation_source":{"type":"string","nullable":true,"description":"Source that triggered the deployment"},"created_by":{"type":"integer","nullable":true,"description":"User ID who created the deployment"}}}}},"paths":{"/v1/apps/{appId}/deployments":{"post":{"summary":"Create a deployment","description":"Legacy alias of `/v1/projects/{projectId}/deployments` — projects were previously called apps. Creates a new deployment for the specified project using its current spicepod configuration. The runtime image is selected based on the project's update channel.","parameters":[{"in":"path","name":"appId","required":true,"schema":{"type":"integer"},"description":"The ID of the project"},{"$ref":"#/components/parameters/OrgName"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"image_tag":{"type":"string","description":"Override the runtime image tag for this deployment. Requires the Enterprise plan; omit it to deploy the image the project is configured with. When the effective update channel is `stable` or `preview`, a supplied tag must be a published version for that channel. When the effective update channel is `nightly`, a supplied tag must be a published `spicehq/spiceai` `nightly-*` tag (`YYYYMMDDHHmm` plus `-` plus 7 to 40 lowercase hex characters, for example `202609081124-cadf292`)."},"channel":{"type":"string","enum":["stable","preview","nightly"],"description":"Update channel that determines the runtime image"},"expected_update_channel":{"type":"string","enum":["stable","preview","nightly"],"description":"If set, the stored project update channel must match this value or the request is refused with 409 `update_channel_mismatch`. This is a precondition, not an override (`channel` still changes the image train).\n"},"replicas":{"type":"integer","minimum":1,"maximum":10,"description":"Override the number of replicas for this deployment"},"branch":{"type":"string","description":"Git branch name"},"commit_sha":{"type":"string","description":"Git commit SHA"},"commit_message":{"type":"string","description":"Git commit message"},"debug":{"type":"boolean","description":"Enable debug mode for this deployment"},"target":{"type":"object","description":"Optional per-deployment override. Omit (or `{ kind: cloud }`) to place the deployment where the project itself runs — Spice-managed compute, its own BYOC cluster, or its attached standalone Cloud Connect instance — which is a property of the project, not of this request. Pass `{ kind: cluster, instance_id }` to override that for this deployment and route it to a BYOC cluster connection; the cluster must be owned by the token's org, not in a terminal lifecycle state (decommissioning/archived), not paused, and the operator must hold a live connection (verified by the connectivity ping, not the Supabase lifecycle status). A standalone project cannot be overridden this way and is refused with 409.\n","properties":{"kind":{"type":"string","enum":["cloud","cluster"]},"instance_id":{"type":"string","description":"Required when kind is `cluster`."}}}}}}}},"responses":{"202":{"description":"Deployment created and queued for processing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deployment"}}}},"400":{"description":"Invalid request body, project has no spicepod configuration, the spicepod has been deleted, or the spicepod is paused (`code: spicepod_paused`; resume it with POST /v1/projects/{projectId}/resume before deploying). For a standalone Cloud Connect project, also returned when the Spicepod references a `${secrets:...}` name the project does not define: the body carries `code: unknown_secret_references`, a `missing_secrets` array of `{name, path, suggestion?}`, and `secrets_url`. When the effective update channel is `stable` or `preview` and `image_tag` is supplied, the tag must be a published version for that channel or the body is `{ error: 'Invalid image_tag for stable channel', code: 'invalid_stable_image_tag' }` (or the preview analog). When the effective update channel is `nightly` and `image_tag` is supplied, the tag must be a published `spicehq/spiceai` `nightly-*` tag of the form `YYYYMMDDHHmm` plus `-` plus 7 to 40 lowercase hex characters (for example `202609081124-cadf292`) or the body is `{ error: 'Invalid image_tag for nightly channel', code: 'invalid_nightly_image_tag' }`. Nothing is dispatched and no deployment is recorded.\n"},"401":{"description":"Unauthorized"},"403":{"description":"Insufficient scope, viewer role cannot create deployments, `image_tag` was supplied outside the Enterprise plan (code: `image_tag_requires_enterprise`), or the requested runtime image is not available for the organization plan (code: `image_tag_not_allowed_for_plan`); omitting `image_tag` deploys the image the project is configured with"},"404":{"description":"Project not found — or, for a `cluster` target, the BYOC cluster connection does not exist or is not owned by the token's org.\n"},"409":{"description":"A deployment is already in progress for this project (`code: deployment_in_progress`, with optional `activeDeploymentId`) — or, for a `cluster` target, the BYOC cluster is paused, offline, or otherwise not in a deployable state. Also returned when the project's deploy target is unusable: its kind conflicts with its cluster/instance references, a `cluster` target was requested for a standalone project, a standalone project has no attached instance, or that instance has not yet enrolled the encryption key its secrets are sealed to (retrying once it is online succeeds). Also returned when `expected_update_channel` does not match the stored spicepod update channel, or when that channel changes before dispatch (`code: update_channel_mismatch`).\n"},"413":{"description":"Request body exceeds the maximum size (1 MiB), or — for a standalone Cloud Connect project — the project's resolved secrets exceed the maximum sealed-payload size. Nothing is dispatched and no deployment is recorded.\n"},"422":{"description":"Organization is not fully configured, or no runtime version in the catalog matches this project’s version range (`code: version_no_match`).\n"},"500":{"description":"Internal server error. For a standalone Cloud Connect project, also returned with `code: deployment_not_settled` when the deployment record could not be moved out of `queued`; the project's next deployment is refused until it is cleared.\n"},"502":{"description":"Upstream service failure while provisioning the deployment, or — for a standalone Cloud Connect project — the spicepod could not be handed to the instance's gateway, or the instance rejected it.\n"},"503":{"description":"The runtime version catalog is unavailable or empty (`code: version_source_unavailable`), so an unpinned stable or preview deploy cannot resolve an image tag — or catalog membership for an explicit `image_tag` override cannot be validated. Also returned when the published nightly tag list cannot be loaded to validate a nightly `image_tag` override.\n"}},"tags":["Deployments"],"deprecated":true}}}}
```

## Get a deployment

> Legacy alias of \`/v1/projects/{projectId}/deployments/{deploymentId}\` — projects were previously called apps. Returns a single deployment for the specified project. The body matches one item from GET /v1/projects/{projectId}/deployments. Not cacheable. Poll this path for stored status after POST create.

```json
{"openapi":"3.1.0","info":{"title":"Spice Cloud Control-Plane API","version":"v1"},"tags":[{"name":"Deployments","description":"Create and monitor project deployments"}],"servers":[{"url":"https://api.spice.ai"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth 2.0 access token obtained from the Spice.ai authentication service"}},"parameters":{"OrgName":{"in":"header","name":"X-Org-Name","required":false,"description":"The organization to act on, by handle. Omit it to act on the organization the credential is bound to; sending it blank is a 400, not the same as omitting it. A user credential may name any organization its owner belongs to; a machine credential is pinned to its own.\n","schema":{"type":"string","pattern":"^[A-Za-z0-9._-]{1,255}$"}}},"schemas":{"Deployment":{"type":"object","properties":{"id":{"type":"integer","description":"Unique identifier for the deployment"},"status":{"type":"string","enum":["queued","in_progress","succeeded","failed","created"],"description":"Current status of the deployment"},"created_at":{"type":"string","format":"date-time","description":"Timestamp when the deployment was created"},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Timestamp when the deployment was last updated"},"image_tag":{"type":"string","nullable":true,"description":"Runtime image tag used for this deployment"},"replicas":{"type":"integer","description":"Number of replicas"},"branch":{"type":"string","nullable":true,"description":"Git branch name"},"commit_sha":{"type":"string","nullable":true,"description":"Git commit SHA"},"commit_message":{"type":"string","nullable":true,"description":"Git commit message"},"error_code":{"type":"string","nullable":true,"description":"Set with error_message on failed and on in_progress while Cloud is retrying a scheduling block. Null on succeeded, on ordinary waiting in_progress, and on writers that predated this column. Older failed rows may still have a message with a null code."},"error_message":{"type":"string","nullable":true,"description":"Catalog copy for the current error_code. Older failed rows may still have a message with a null error_code."},"creation_source":{"type":"string","nullable":true,"description":"Source that triggered the deployment"},"created_by":{"type":"integer","nullable":true,"description":"User ID who created the deployment"}}}}},"paths":{"/v1/apps/{appId}/deployments/{deploymentId}":{"get":{"summary":"Get a deployment","description":"Legacy alias of `/v1/projects/{projectId}/deployments/{deploymentId}` — projects were previously called apps. Returns a single deployment for the specified project. The body matches one item from GET /v1/projects/{projectId}/deployments. Not cacheable. Poll this path for stored status after POST create.","parameters":[{"in":"path","name":"appId","required":true,"schema":{"type":"integer"},"description":"The ID of the project"},{"in":"path","name":"deploymentId","required":true,"schema":{"type":"integer"},"description":"The ID of the deployment"},{"$ref":"#/components/parameters/OrgName"}],"responses":{"200":{"description":"Deployment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deployment"}}}},"400":{"description":"Invalid project ID or deployment ID"},"401":{"description":"Unauthorized"},"403":{"description":"Insufficient scope"},"404":{"description":"Project or deployment not found"},"500":{"description":"Internal server error"}},"tags":["Deployments"],"deprecated":true}}}}
```


---

# 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/management/deployments.md?ask=<question>&goal=<endgoal>
```

`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.