# Apps

Manage apps and their configurations

## List apps

> Returns all apps belonging to the authenticated organization.

```json
{"openapi":"3.1.0","info":{"title":"Spice Cloud Control-Plane API","version":"v1"},"tags":[{"name":"Apps","description":"Manage apps and their configurations"}],"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":{"App":{"type":"object","properties":{"id":{"type":"integer","description":"Unique identifier for the app"},"name":{"type":"string","description":"Name of the app"},"description":{"type":"string","nullable":true,"description":"Description of the app"},"visibility":{"type":"string","enum":["public","private"],"description":"Visibility setting for the app"},"created_at":{"type":"string","format":"date-time","description":"Timestamp when the app was created"},"cname":{"type":"string","description":"Region identifier"},"cluster_id":{"type":"string","nullable":true,"description":"Cluster ID where the app is deployed"},"tags":{"type":"object","additionalProperties":{"type":"string"},"nullable":true,"description":"Key-value tags for the app"}}}}},"paths":{"/v1/apps":{"get":{"summary":"List apps","description":"Returns all apps belonging to the authenticated organization.","responses":{"200":{"description":"List of apps","content":{"application/json":{"schema":{"type":"object","properties":{"apps":{"type":"array","items":{"$ref":"#/components/schemas/App"}}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Insufficient scope"}},"tags":["Apps"]}}}}
```

## Create an app

> Creates a new app in the authenticated organization.

```json
{"openapi":"3.1.0","info":{"title":"Spice Cloud Control-Plane API","version":"v1"},"tags":[{"name":"Apps","description":"Manage apps and their configurations"}],"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":{"AppWithConfig":{"type":"object","properties":{"id":{"type":"integer","description":"Unique identifier for the app"},"name":{"type":"string","description":"Name of the app"},"description":{"type":"string","nullable":true,"description":"Description of the app"},"visibility":{"type":"string","enum":["public","private"],"description":"Visibility setting for the app"},"created_at":{"type":"string","format":"date-time","description":"Timestamp when the app was created"},"cname":{"type":"string","description":"Region identifier"},"production_branch":{"type":"string","nullable":true,"description":"Production branch for the app"},"api_key":{"type":"string","deprecated":true,"description":"Deprecated. Use the API Keys endpoints instead."},"tags":{"type":"object","additionalProperties":{"type":"string"},"nullable":true,"description":"Key-value tags for the app"},"warning":{"type":"string","nullable":true,"description":"Present when the app was created but initial configuration could not be applied"},"config":{"type":"object","properties":{"spicepod":{"type":"object","nullable":true,"description":"Spicepod configuration"},"registry":{"type":"string","nullable":true,"description":"Container registry for the runtime image"},"image_tag":{"type":"string","nullable":true,"description":"Runtime image tag"},"update_channel":{"type":"string","enum":["stable","preview","nightly","internal"],"nullable":true,"description":"Update channel for the runtime"},"replicas":{"type":"integer","description":"Number of replicas"},"resources":{"type":"object","nullable":true,"description":"Resource requests and limits for the app container","properties":{"limits":{"type":"object","properties":{"cpu":{"type":"string","description":"Whole-number vCPU limit, or '-' for no CPU limit"},"memory":{"type":"string","description":"Memory limit in Gi (for example, 16Gi)"},"ephemeral-storage":{"type":"string"}}},"requests":{"type":"object","properties":{"cpu":{"type":"string"},"memory":{"type":"string"}}}}},"executor":{"type":"object","nullable":true,"description":"Executor container configuration","properties":{"replicas":{"type":"integer","description":"Number of executor replicas"},"resources":{"type":"object","description":"Resource requests and limits for the executor container","properties":{"limits":{"type":"object","properties":{"cpu":{"type":"string","description":"Whole-number vCPU limit, or '-' for no CPU limit"},"memory":{"type":"string","description":"Memory limit in Gi (for example, 16Gi)"},"ephemeral-storage":{"type":"string"}}},"requests":{"type":"object","properties":{"cpu":{"type":"string"},"memory":{"type":"string"}}}}}}},"region":{"type":"string","nullable":true,"description":"Cloud region code (e.g., us-east-1)"},"node_group":{"type":"string","nullable":true,"description":"Node group for scheduling the app runtime"},"storage_claim_size_gb":{"type":"number","nullable":true,"description":"Storage claim size in GB"}}}}}}},"paths":{"/v1/apps":{"post":{"summary":"Create an app","description":"Creates a new app in the authenticated organization.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":4,"pattern":"^[a-zA-Z0-9-]+$","description":"App name (letters, numbers, hyphens only)"},"region":{"type":"string","enum":["us-east-1","us-west-2"],"description":"Cloud region where the app will be deployed (e.g. `us-east-1`).\n"},"cname":{"type":"string","description":"**Deprecated.** Internal region CNAME (e.g. `us-east-1-prod-aws-data`). Use `region` instead. Accepted for backwards compatibility when `region` is omitted.\n"},"description":{"type":"string","description":"App description"},"visibility":{"type":"string","enum":["public","private"],"default":"private"},"tags":{"type":"object","additionalProperties":{"type":"string"},"description":"Key-value tags for the app"},"update_channel":{"type":"string","enum":["stable","preview","nightly","internal"],"description":"Update channel for the app deployment"},"replicas":{"type":"integer","minimum":0,"description":"Number of replicas"},"resources":{"type":"object","description":"Resource requests and limits for the app container","properties":{"limits":{"type":"object","properties":{"cpu":{"type":"string","description":"Whole-number vCPU limit, or '-' for no CPU limit"},"memory":{"type":"string","description":"Memory limit in Gi (for example, 16Gi)"},"ephemeral-storage":{"type":"string","description":"Ephemeral storage limit in Gi (for example, 8Gi)"}}},"requests":{"type":"object","properties":{"cpu":{"type":"string"},"memory":{"type":"string"}}}}},"executor":{"type":"object","description":"Executor container configuration","properties":{"replicas":{"type":"integer","minimum":0,"description":"Number of executor replicas"},"resources":{"type":"object","description":"Resource requests and limits for the executor container","properties":{"limits":{"type":"object","properties":{"cpu":{"type":"string","description":"Whole-number vCPU limit, or '-' for no CPU limit"},"memory":{"type":"string","description":"Memory limit in Gi (for example, 16Gi)"},"ephemeral-storage":{"type":"string","description":"Ephemeral storage limit in Gi (for example, 8Gi)"}}},"requests":{"type":"object","properties":{"cpu":{"type":"string"},"memory":{"type":"string"}}}}}}}}}}}},"responses":{"201":{"description":"App created successfully. The response may include a `warning` field if initial configuration could not be applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppWithConfig"}}}},"400":{"description":"Invalid request body or invalid region"},"401":{"description":"Unauthorized"},"403":{"description":"Insufficient scope, organization app limit exceeded, or private compute addon required for resource limits"},"409":{"description":"An app with this name already exists"}},"tags":["Apps"]}}}}
```

## Get an app

> Returns details for a specific app, including its configuration.

```json
{"openapi":"3.1.0","info":{"title":"Spice Cloud Control-Plane API","version":"v1"},"tags":[{"name":"Apps","description":"Manage apps and their configurations"}],"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"}}},"paths":{"/v1/apps/{appId}":{"get":{"summary":"Get an app","description":"Returns details for a specific app, including its configuration.","parameters":[{"in":"path","name":"appId","required":true,"schema":{"type":"integer"},"description":"The ID of the app"}],"responses":{"200":{"description":"App details with configuration","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"visibility":{"type":"string","enum":["public","private"]},"created_at":{"type":"string","format":"date-time"},"region":{"type":"string"},"production_branch":{"type":"string"},"api_key":{"type":"string","deprecated":true,"description":"Deprecated. Use the API Keys endpoints instead."},"tags":{"type":"object","additionalProperties":{"type":"string"}},"config":{"type":"object","properties":{"spicepod":{"type":"object"},"image_tag":{"type":"string","description":"Runtime image tag"},"update_channel":{"type":"string","enum":["stable","preview","nightly","internal"],"description":"Update channel for the runtime"},"replicas":{"type":"integer"},"resources":{"type":"object","nullable":true,"description":"Resource requests and limits for the app container","properties":{"limits":{"type":"object","properties":{"cpu":{"type":"string","description":"Whole-number vCPU limit, or '-' for no CPU limit"},"memory":{"type":"string","description":"Memory limit in Gi (for example, 16Gi)"},"ephemeral-storage":{"type":"string"}}},"requests":{"type":"object","properties":{"cpu":{"type":"string"},"memory":{"type":"string"}}}}},"executor":{"type":"object","nullable":true,"description":"Executor container configuration","properties":{"replicas":{"type":"integer","description":"Number of executor replicas"},"resources":{"type":"object","description":"Resource requests and limits for the executor container","properties":{"limits":{"type":"object","properties":{"cpu":{"type":"string","description":"Whole-number vCPU limit, or '-' for no CPU limit"},"memory":{"type":"string","description":"Memory limit in Gi (for example, 16Gi)"},"ephemeral-storage":{"type":"string"}}},"requests":{"type":"object","properties":{"cpu":{"type":"string"},"memory":{"type":"string"}}}}},"storage_size_gb":{"type":"number","nullable":true}}},"region":{"type":"string"},"storage_size_gb":{"type":"number","nullable":true},"storage_claim_size_gb":{"type":"number","deprecated":true,"description":"Deprecated. Use storage_size_gb instead."}}}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Insufficient scope"},"404":{"description":"App not found"},"500":{"description":"Internal server error"}},"tags":["Apps"]}}}}
```

## Update an app

> Updates an app's metadata and configuration, including description, visibility, spicepod configuration, replicas, and resource limits.

```json
{"openapi":"3.1.0","info":{"title":"Spice Cloud Control-Plane API","version":"v1"},"tags":[{"name":"Apps","description":"Manage apps and their configurations"}],"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":{"AppWithConfig":{"type":"object","properties":{"id":{"type":"integer","description":"Unique identifier for the app"},"name":{"type":"string","description":"Name of the app"},"description":{"type":"string","nullable":true,"description":"Description of the app"},"visibility":{"type":"string","enum":["public","private"],"description":"Visibility setting for the app"},"created_at":{"type":"string","format":"date-time","description":"Timestamp when the app was created"},"cname":{"type":"string","description":"Region identifier"},"production_branch":{"type":"string","nullable":true,"description":"Production branch for the app"},"api_key":{"type":"string","deprecated":true,"description":"Deprecated. Use the API Keys endpoints instead."},"tags":{"type":"object","additionalProperties":{"type":"string"},"nullable":true,"description":"Key-value tags for the app"},"warning":{"type":"string","nullable":true,"description":"Present when the app was created but initial configuration could not be applied"},"config":{"type":"object","properties":{"spicepod":{"type":"object","nullable":true,"description":"Spicepod configuration"},"registry":{"type":"string","nullable":true,"description":"Container registry for the runtime image"},"image_tag":{"type":"string","nullable":true,"description":"Runtime image tag"},"update_channel":{"type":"string","enum":["stable","preview","nightly","internal"],"nullable":true,"description":"Update channel for the runtime"},"replicas":{"type":"integer","description":"Number of replicas"},"resources":{"type":"object","nullable":true,"description":"Resource requests and limits for the app container","properties":{"limits":{"type":"object","properties":{"cpu":{"type":"string","description":"Whole-number vCPU limit, or '-' for no CPU limit"},"memory":{"type":"string","description":"Memory limit in Gi (for example, 16Gi)"},"ephemeral-storage":{"type":"string"}}},"requests":{"type":"object","properties":{"cpu":{"type":"string"},"memory":{"type":"string"}}}}},"executor":{"type":"object","nullable":true,"description":"Executor container configuration","properties":{"replicas":{"type":"integer","description":"Number of executor replicas"},"resources":{"type":"object","description":"Resource requests and limits for the executor container","properties":{"limits":{"type":"object","properties":{"cpu":{"type":"string","description":"Whole-number vCPU limit, or '-' for no CPU limit"},"memory":{"type":"string","description":"Memory limit in Gi (for example, 16Gi)"},"ephemeral-storage":{"type":"string"}}},"requests":{"type":"object","properties":{"cpu":{"type":"string"},"memory":{"type":"string"}}}}}}},"region":{"type":"string","nullable":true,"description":"Cloud region code (e.g., us-east-1)"},"node_group":{"type":"string","nullable":true,"description":"Node group for scheduling the app runtime"},"storage_claim_size_gb":{"type":"number","nullable":true,"description":"Storage claim size in GB"}}}}}}},"paths":{"/v1/apps/{appId}":{"put":{"summary":"Update an app","description":"Updates an app's metadata and configuration, including description, visibility, spicepod configuration, replicas, and resource limits.","parameters":[{"in":"path","name":"appId","required":true,"schema":{"type":"integer"},"description":"The ID of the app"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"description":{"type":"string"},"visibility":{"type":"string","enum":["public","private"]},"production_branch":{"type":"string"},"tags":{"type":"object","additionalProperties":{"type":"string"},"description":"Key-value tags for the app"},"spicepod":{"oneOf":[{"type":"string","description":"YAML string of the spicepod configuration"},{"type":"object","description":"JSON object of the spicepod configuration"}]},"image_tag":{"type":"string","description":"Runtime image tag"},"update_channel":{"type":"string","enum":["stable","preview","nightly","internal"],"description":"Update channel for the runtime"},"replicas":{"type":"integer","minimum":0},"resources":{"type":"object","description":"Resource requests and limits for the app container","properties":{"limits":{"type":"object","properties":{"cpu":{"type":"string","description":"Whole-number vCPU limit, or '-' for no CPU limit"},"memory":{"type":"string","description":"Memory limit in Gi (for example, 16Gi)"},"ephemeral-storage":{"type":"string","description":"Ephemeral storage limit in Gi (for example, 8Gi)"}}},"requests":{"type":"object","properties":{"cpu":{"type":"string"},"memory":{"type":"string"}}}}},"executor":{"type":"object","description":"Executor container configuration","properties":{"replicas":{"type":"integer","minimum":0,"description":"Number of executor replicas"},"resources":{"type":"object","description":"Resource requests and limits for the executor container","properties":{"limits":{"type":"object","properties":{"cpu":{"type":"string","description":"Whole-number vCPU limit, or '-' for no CPU limit"},"memory":{"type":"string","description":"Memory limit in Gi (for example, 16Gi)"},"ephemeral-storage":{"type":"string","description":"Ephemeral storage limit in Gi (for example, 8Gi)"}}},"requests":{"type":"object","properties":{"cpu":{"type":"string"},"memory":{"type":"string"}}}}},"storage_size_gb":{"type":"number"}}},"region":{"type":"string"},"storage_size_gb":{"type":"number"},"storage_claim_size_gb":{"type":"number","deprecated":true,"description":"Deprecated. Use storage_size_gb instead."}}}}}},"responses":{"200":{"description":"App updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppWithConfig"}}}},"400":{"description":"Invalid request body or app ID"},"401":{"description":"Unauthorized"},"403":{"description":"Insufficient scope, requested replicas or resources exceed plan limits, or private compute addon is required"},"404":{"description":"App not found"},"500":{"description":"Internal server error"}},"tags":["Apps"]}}}}
```

## Delete an app

> Deletes an app and tears down its runtime resources.

```json
{"openapi":"3.1.0","info":{"title":"Spice Cloud Control-Plane API","version":"v1"},"tags":[{"name":"Apps","description":"Manage apps and their configurations"}],"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"}}},"paths":{"/v1/apps/{appId}":{"delete":{"summary":"Delete an app","description":"Deletes an app and tears down its runtime resources.","parameters":[{"in":"path","name":"appId","required":true,"schema":{"type":"integer"},"description":"The ID of the app to delete"}],"responses":{"204":{"description":"App deleted successfully"},"400":{"description":"Invalid app ID"},"401":{"description":"Unauthorized"},"403":{"description":"Insufficient scope"},"404":{"description":"App not found"},"500":{"description":"Internal server error"}},"tags":["Apps"]}}}}
```

## Get app metrics

> Returns current resource utilization metrics (CPU, memory, disk I/O) and data ingestion metrics for an app.

```json
{"openapi":"3.1.0","info":{"title":"Spice Cloud Control-Plane API","version":"v1"},"tags":[{"name":"Apps","description":"Manage apps and their configurations"}],"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"}}},"paths":{"/v1/apps/{appId}/metrics":{"get":{"summary":"Get app metrics","description":"Returns current resource utilization metrics (CPU, memory, disk I/O) and data ingestion metrics for an app.","parameters":[{"in":"path","name":"appId","required":true,"schema":{"type":"integer"},"description":"The ID of the app"},{"in":"query","name":"window","required":false,"schema":{"type":"string"},"description":"Prometheus-style duration (e.g. `5m`, `1h`, `30s`). When provided, counter metrics are returned as rates over the window instead of raw cumulative values. For example, `rows_ingested` returns average rows per second with a window, or total cumulative rows without one."}],"responses":{"200":{"description":"Resource and ingestion metrics. Missing fields indicate no data is currently available. Individual metric queries may fail independently; partial results are returned when possible.","content":{"application/json":{"schema":{"type":"object","properties":{"ingestion":{"type":"object","description":"Aggregated data ingestion metrics","properties":{"rows_ingested":{"type":"number","description":"Total rows ingested (without window) or rows per second (with window)"},"bytes_ingested":{"type":"number","description":"Total bytes ingested (without window) or bytes per second (with window)"}}},"cluster":{"type":"object","description":"Cluster metrics for the app","properties":{"active_executors_count":{"type":"number","description":"Number of active executors registered with the scheduler"}}},"metrics":{"type":"object","description":"Resource metrics keyed by pod name","additionalProperties":{"type":"object","properties":{"cpu_usage_percent":{"type":"number","description":"CPU usage as a percentage (0-100)"},"memory_usage_bytes":{"type":"number","description":"Memory usage in bytes"},"disk_read_bytes":{"type":"number","description":"Disk bytes read per second (with window) or cumulative (without window)"},"disk_read_operations":{"type":"number","description":"Disk read operations per second (with window) or cumulative count (without window)"},"disk_write_bytes":{"type":"number","description":"Disk bytes written per second (with window) or cumulative (without window)"},"disk_write_operations":{"type":"number","description":"Disk write operations per second (with window) or cumulative count (without window)"}}}}}}}}},"400":{"description":"Invalid app ID"},"401":{"description":"Unauthorized"},"403":{"description":"Insufficient scope"},"404":{"description":"App or organization not found"},"422":{"description":"Organization is not fully configured"},"500":{"description":"Internal server error"},"503":{"description":"Metrics service unavailable"}},"tags":["Apps"]}}}}
```


---

# 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/apps.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.