SPspice
Deployments

Create a deployment

Creates a new deployment for the specified project using its current spicepod configuration. A project connected to a GitHub repository deploys spicepod.yaml from its root directory, read when the deployment is created. It reads the head of the production branch, or the branch or commit_sha the request names. The runtime image is selected based on the project's update channel.

post/v1/projects/{projectId}/deployments

Request

  • Base URL
    https://api.spice.ai
  • Auth
    HTTP bearer

Path parameters

projectIdinteger required

The ID of the project

Headers

X-Org-Namestring

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. A portal session token is bound to none, so it must send this header on every route but GET /v1/orgs (400 org_assertion_required otherwise).

Request body

image_tagstring

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'stable' | 'preview' | 'nightly'

Update channel that determines the runtime image

expected_update_channel'stable' | 'preview' | 'nightly'

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

replicasinteger

Override the number of replicas for this deployment

branchstring

For a project connected to a GitHub repository, deploy spicepod.yaml from the head of this branch or tag of that repository instead of the production branch. The branch or tag must exist. With commit_sha, it must contain the commit. The production branch and the stored spicepod do not change, so the next deployment without a revision, and any automatic redeploy, deploy the production branch head again. A project with no connected repository refuses this field with 400 repository_not_connected. A project whose org has no GitHub App installation refuses it with 422 github_installation_missing. A request from the deploy GitHub Action (User-Agent spice-cloud-deploy-action) does not check or use this field for any project, because the Action sends the branch of its workflow run as metadata.

commit_shastring

For a project connected to a GitHub repository, deploy spicepod.yaml from this commit instead of the head of the production branch. The commit must be on branch, or on the production branch (never a tag of the same name) when branch is omitted, so a commit that only a fork holds is refused. The deployment records the full SHA. The production branch and the stored spicepod do not change. A project with no connected repository refuses this field with 400 repository_not_connected. A project whose org has no GitHub App installation refuses it with 422 github_installation_missing. A request from the deploy GitHub Action (User-Agent spice-cloud-deploy-action) does not check or use this field for any project, because the Action sends the commit of its workflow run as metadata.

commit_messagestring

Not used. A deployment from a connected repository records the message of the commit it reads.

debugboolean

Enable debug mode for this deployment

Response

Deployment created and queued for processing

idinteger

Unique identifier for the deployment

status'queued' | 'in_progress' | 'succeeded' | 'failed' | 'created'

Current status of the deployment

created_atstring date-time

Timestamp when the deployment was created

updated_atstring date-time nullable

Timestamp when the deployment was last updated

image_tagstring nullable

Runtime image tag used for this deployment

replicasinteger

Number of replicas

branchstring nullable

Git branch name

commit_shastring nullable

Git commit SHA

commit_messagestring nullable

Git commit message

error_codestring nullable

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_messagestring nullable

Catalog copy for the current error_code. Older failed rows may still have a message with a null error_code.

creation_sourcestring nullable

Source that triggered the deployment

created_byinteger nullable

User ID who created the deployment

Changes

No recorded changes to this operation across all 1 revision of this API.