# Deployments

Create and monitor app deployments

## List deployments

> Returns a list of deployments for the specified app, 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 app 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"}},"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"},"started_at":{"type":"string","format":"date-time","nullable":true,"description":"Timestamp when the deployment started"},"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_message":{"type":"string","nullable":true,"description":"Error message if the deployment failed"},"creation_source":{"type":"string","nullable":true,"description":"Source that triggered the deployment"},"created_by":{"type":"string","nullable":true,"description":"User who created the deployment"}}}}},"paths":{"/v1/apps/{appId}/deployments":{"get":{"summary":"List deployments","description":"Returns a list of deployments for the specified app, ordered by most recent first.","parameters":[{"in":"path","name":"appId","required":true,"schema":{"type":"integer"},"description":"The ID of the app"},{"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"}],"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":"App not found"}},"tags":["Deployments"]}}}}
```

## Create a deployment

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

```json
{"openapi":"3.1.0","info":{"title":"Spice Cloud Control-Plane API","version":"v1"},"tags":[{"name":"Deployments","description":"Create and monitor app 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"}},"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"},"started_at":{"type":"string","format":"date-time","nullable":true,"description":"Timestamp when the deployment started"},"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_message":{"type":"string","nullable":true,"description":"Error message if the deployment failed"},"creation_source":{"type":"string","nullable":true,"description":"Source that triggered the deployment"},"created_by":{"type":"string","nullable":true,"description":"User who created the deployment"}}}}},"paths":{"/v1/apps/{appId}/deployments":{"post":{"summary":"Create a deployment","description":"Creates a new deployment for the specified app using its current spicepod configuration. The runtime image is selected based on the app's update channel.","parameters":[{"in":"path","name":"appId","required":true,"schema":{"type":"integer"},"description":"The ID of the app"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"image_tag":{"type":"string","description":"Override the runtime image tag for this deployment"},"channel":{"type":"string","enum":["stable","preview","nightly","internal"],"description":"Update channel that determines the runtime image"},"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"}}}}}},"responses":{"202":{"description":"Deployment created and queued for processing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deployment"}}}},"400":{"description":"Invalid request body or app has no spicepod configuration"},"401":{"description":"Unauthorized"},"403":{"description":"Insufficient scope"},"404":{"description":"App not found"},"409":{"description":"A deployment is already in progress for this app"},"422":{"description":"Organization is not fully configured"},"500":{"description":"Internal server error"},"502":{"description":"Upstream service failure while provisioning the deployment"}},"tags":["Deployments"]}}}}
```


---

# Agent Instructions: 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:

```
GET https://docs.spice.ai/api/management-api/management/deployments.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.