Create a deployment

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). Also returned when the spicepod name, kind or version is missing or not valid: the body is { error: 'Invalid spicepod configuration' } with an issues array of {path, message}. The runtime checks all other spicepod fields when it loads the spicepod. 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' }. For a project connected to a GitHub repository, also returned when the root directory has no spicepod.yaml or it is invalid or too large (code: spicepod_not_found, spicepod_invalid or spicepod_too_large), when commit_sha is not on branch (or on the production branch when branch is omitted) (code: commit_not_on_branch), or when commit_sha comes without branch and the project has no production branch (code: branch_required). Nothing is dispatched and no deployment is recorded. Also returned when branch or commit_sha is sent for a project with no connected repository (code: repository_not_connected), except from the deploy GitHub Action. Nothing is dispatched.

Insufficient scope, viewer role cannot create deployments, image_tag was supplied outside the Enterprise plan (code: image_tag_requires_enterprise), the requested runtime image is not available for the organization plan (code: image_tag_not_allowed_for_plan), or the organization's GitHub App installation cannot read the connected repository (code: github_unauthorized or github_forbidden); omitting image_tag deploys the image the project is configured with

Project not found. For a cluster target, also returned when the BYOC cluster connection does not exist or is not owned by the token's org. Also returned when the connected GitHub repository, its production branch, or the requested branch or commit_sha was not found (code: github_not_found). With commit_sha and no branch, this includes a production branch that no longer exists.

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

Organization is not fully configured, no runtime version in the catalog matches this project’s version range (code: version_no_match), or the spicepod uses version v1beta1, which the Spice 2 runtime cannot load (code: spicepod_version_unsupported). Also returned when the Spicepod uses a connection credential that holds a secret reference deploy cannot resolve: the body carries code: connection_credentials_unresolved and an unresolved_credentials array of {connection, field}. Nothing is deployed. Also returned when branch or commit_sha is sent for a project with a connected repository whose org has no GitHub App installation to read it (code: github_installation_missing), except from the deploy GitHub Action. Nothing is dispatched.

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.

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. Also returned when GitHub did not answer while the connected repository was read (code: github_unavailable).

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.

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). Also returned when the spicepod name, kind or version is missing or not valid: the body is { error: 'Invalid spicepod configuration' } with an issues array of {path, message}. The runtime checks all other spicepod fields when it loads the spicepod. 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' }. For a project connected to a GitHub repository, also returned when the root directory has no spicepod.yaml or it is invalid or too large (code: spicepod_not_found, spicepod_invalid or spicepod_too_large), when commit_sha is not on branch (or on the production branch when branch is omitted) (code: commit_not_on_branch), or when commit_sha comes without branch and the project has no production branch (code: branch_required). Nothing is dispatched and no deployment is recorded. Also returned when branch or commit_sha is sent for a project with no connected repository (code: repository_not_connected), except from the deploy GitHub Action. Nothing is dispatched. orgId is not a valid org id (invalid_org_id), or X-Org-Name does not name that org (org_path_mismatch).

Insufficient scope, viewer role cannot create deployments, image_tag was supplied outside the Enterprise plan (code: image_tag_requires_enterprise), the requested runtime image is not available for the organization plan (code: image_tag_not_allowed_for_plan), or the organization's GitHub App installation cannot read the connected repository (code: github_unauthorized or github_forbidden); omitting image_tag deploys the image the project is configured with. The caller is not a member of the org (org_forbidden). A machine credential named a different org (org_assertion_mismatch). The org is deleted (org_deleted).

Project not found. For a cluster target, also returned when the BYOC cluster connection does not exist or is not owned by the token's org. Also returned when the connected GitHub repository, its production branch, or the requested branch or commit_sha was not found (code: github_not_found). With commit_sha and no branch, this includes a production branch that no longer exists.

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

Organization is not fully configured, no runtime version in the catalog matches this project’s version range (code: version_no_match), or the spicepod uses version v1beta1, which the Spice 2 runtime cannot load (code: spicepod_version_unsupported). Also returned when the Spicepod uses a connection credential that holds a secret reference deploy cannot resolve: the body carries code: connection_credentials_unresolved and an unresolved_credentials array of {connection, field}. Nothing is deployed. Also returned when branch or commit_sha is sent for a project with a connected repository whose org has no GitHub App installation to read it (code: github_installation_missing), except from the deploy GitHub Action. Nothing is dispatched.

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.

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. Also returned when GitHub did not answer while the connected repository was read (code: github_unavailable).

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.

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). Also returned when the spicepod name, kind or version is missing or not valid: the body is { error: 'Invalid spicepod configuration' } with an issues array of {path, message}. The runtime checks all other spicepod fields when it loads the spicepod. 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' }. For a project connected to a GitHub repository, also returned when the root directory has no spicepod.yaml or it is invalid or too large (code: spicepod_not_found, spicepod_invalid or spicepod_too_large), when commit_sha is not on branch (or on the production branch when branch is omitted) (code: commit_not_on_branch), or when commit_sha comes without branch and the project has no production branch (code: branch_required). Nothing is dispatched and no deployment is recorded. Also returned when branch or commit_sha is sent for a project with no connected repository (code: repository_not_connected), except from the deploy GitHub Action. Nothing is dispatched.

Insufficient scope, viewer role cannot create deployments, image_tag was supplied outside the Enterprise plan (code: image_tag_requires_enterprise), the requested runtime image is not available for the organization plan (code: image_tag_not_allowed_for_plan), or the organization's GitHub App installation cannot read the connected repository (code: github_unauthorized or github_forbidden); omitting image_tag deploys the image the project is configured with

Project not found. For a cluster target, also returned when the BYOC cluster connection does not exist or is not owned by the token's org. Also returned when the connected GitHub repository, its production branch, or the requested branch or commit_sha was not found (code: github_not_found). With commit_sha and no branch, this includes a production branch that no longer exists.

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

Organization is not fully configured, no runtime version in the catalog matches this project’s version range (code: version_no_match), or the spicepod uses version v1beta1, which the Spice 2 runtime cannot load (code: spicepod_version_unsupported). Also returned when the Spicepod uses a connection credential that holds a secret reference deploy cannot resolve: the body carries code: connection_credentials_unresolved and an unresolved_credentials array of {connection, field}. Nothing is deployed. Also returned when branch or commit_sha is sent for a project with a connected repository whose org has no GitHub App installation to read it (code: github_installation_missing), except from the deploy GitHub Action. Nothing is dispatched.

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.

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. Also returned when GitHub did not answer while the connected repository was read (code: github_unavailable).

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.