Apps

Manage Spice apps via API

Apps are the primary resource in Spice.ai Cloud. Each app represents a deployed Spice runtime with its own configuration, datasets, models, and endpoints.

List Apps

GET https://api.spice.ai/v1/apps

Returns a list of apps for the authenticated organization.

Required scope: apps:read

Response

200: OK

{
  "apps": [
    {
      "id": 123,
      "name": "my-app",
      "description": "My Spice app",
      "visibility": "private",
      "created_at": "2024-01-15T10:00:00.000Z",
      "cname": "us-east-2.spice.cloud",
      "api_key": "abc123...",
      "tags": {
        "environment": "production",
        "team": "data"
      }
    }
  ]
}

Response Fields:

Field	Type	Description
id	integer	Unique app identifier
name	string	App name
description	string | null	App description
visibility	string	public or private
created_at	string	ISO 8601 timestamp
cname	string	Region identifier
api_key	string | null	Primary API key (for runtime authentication)
tags	object | null	Key-value tags

401: Unauthorized

403: Forbidden

Example

curl -H "Authorization: Bearer <token>" \
  https://api.spice.ai/v1/apps

Create App

POST https://api.spice.ai/v1/apps

Creates a new app in the authenticated organization.

Required scope: apps:write

Request Body

{
  "name": "my-app",
  "cname": "us-east-2.spice.cloud",
  "description": "My Spice app",
  "visibility": "private",
  "tags": {
    "environment": "production"
  }
}

Request Fields:

Field	Type	Required	Description
name	string	Yes	App name (min 4 chars, alphanumeric and hyphens only)
cname	string	Yes	Region identifier (get from /v1/regions)
description	string	No	App description
visibility	string	No	public or private (default: private)
tags	object	No	Key-value tags for organization

Response

201: Created

{
  "id": 123,
  "name": "my-app",
  "description": "My Spice app",
  "visibility": "private",
  "created_at": "2024-01-15T10:00:00.000Z",
  "production_branch": null,
  "api_key": "abc123...",
  "tags": {
    "environment": "production"
  },
  "config": {
    "spicepod": null,
    "registry": "ghcr.io",
    "image": null,
    "image_tag": null,
    "update_channel": "stable",
    "replicas": 1,
    "region": null,
    "node_group": null,
    "storage_claim_size_gb": null
  }
}

Response Fields:

Field	Type	Description
id	integer	Unique app identifier
name	string	App name
description	string | null	App description
visibility	string	public or private
created_at	string	ISO 8601 timestamp
production_branch	string | null	Git branch for production deployments
api_key	string	Primary API key
tags	object | null	Key-value tags
config	object	App configuration (see Config Object below)

Config Object:

Field	Type	Description
spicepod	object | null	Spicepod YAML configuration
registry	string	Container registry (e.g., ghcr.io)
image	string | null	Container image name
image_tag	string | null	Spice runtime version tag
update_channel	string	stable, nightly, internal, or internal-sandbox
replicas	integer	Number of replicas (1-10)
region	string | null	AWS region code
node_group	string | null	Kubernetes node group
storage_claim_size_gb	number | null	Persistent volume size

400: Bad Request

403: Forbidden

409: Conflict

Examples

cURL:

curl -X POST https://api.spice.ai/v1/apps \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-app",
    "cname": "us-east-2.spice.cloud",
    "description": "My production app",
    "visibility": "private",
    "tags": {
      "environment": "production",
      "team": "data"
    }
  }'

Python:

import requests

response = requests.post(
    "https://api.spice.ai/v1/apps",
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json"
    },
    json={
        "name": "my-app",
        "cname": "us-east-2.spice.cloud",
        "description": "My production app"
    }
)

app = response.json()
print(f"Created app {app['name']} with ID {app['id']}")

Node.js:

const response = await fetch('https://api.spice.ai/v1/apps', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'my-app',
    cname: 'us-east-2.spice.cloud',
    description: 'My production app'
  })
});

const app = await response.json();
console.log(`Created app ${app.name} with ID ${app.id}`);

Get App

GET https://api.spice.ai/v1/apps/{appId}

Returns details for a specific app, including its configuration.

Required scope: apps:read

Path Parameters

Parameter	Type	Description
appId	integer	The app ID

Response

200: OK

{
  "id": 123,
  "name": "my-app",
  "description": "My Spice app",
  "visibility": "private",
  "created_at": "2024-01-15T10:00:00.000Z",
  "production_branch": "main",
  "api_key": "abc123...",
  "tags": {
    "environment": "production"
  },
  "config": {
    "spicepod": {
      "version": "v1beta1",
      "kind": "Spicepod",
      "name": "my-app",
      "datasets": [
        {
          "from": "s3://bucket/data.parquet",
          "name": "my_dataset",
          "acceleration": {
            "enabled": true
          }
        }
      ]
    },
    "registry": "ghcr.io",
    "image": "spiceai/spiceai",
    "image_tag": "v0.17.0",
    "update_channel": "stable",
    "replicas": 2,
    "region": "us-east-2",
    "node_group": null,
    "storage_claim_size_gb": 10
  }
}

404: Not Found

Example

curl -H "Authorization: Bearer <token>" \
  https://api.spice.ai/v1/apps/123

Update App

PUT https://api.spice.ai/v1/apps/{appId}

Updates an app's metadata and configuration. All fields are optional.

Required scope: apps:write

Path Parameters

Parameter	Type	Description
appId	integer	The app ID

Request Body

{
  "description": "Updated description",
  "visibility": "public",
  "production_branch": "main",
  "tags": {
    "environment": "staging"
  },
  "spicepod": {
    "version": "v1beta1",
    "kind": "Spicepod",
    "name": "my-app",
    "datasets": []
  },
  "image_tag": "v0.17.1",
  "replicas": 3,
  "region": "us-west-2",
  "storage_claim_size_gb": 20
}

Request Fields:

Field	Type	Description
description	string	App description
visibility	string	public or private
production_branch	string	Git branch for production
tags	object	Key-value tags
spicepod	string | object	Spicepod YAML string or JSON object
image_tag	string	Spice runtime version
image	string	Container image name
registry	string	Container registry
update_channel	string	stable, nightly, internal, or internal-sandbox
replicas	integer	Number of replicas (1-10)
region	string	AWS region code
node_group	string	Kubernetes node group
storage_claim_size_gb	number	Persistent volume size

Response

200: OK

{
  "id": 123,
  "name": "my-app",
  "description": "Updated description",
  "visibility": "public",
  "created_at": "2024-01-15T10:00:00.000Z",
  "production_branch": "main",
  "api_key": "abc123...",
  "tags": {
    "environment": "staging"
  },
  "config": {
    "spicepod": {
      "version": "v1beta1",
      "kind": "Spicepod",
      "name": "my-app",
      "datasets": []
    },
    "registry": "ghcr.io",
    "image": "spiceai/spiceai",
    "image_tag": "v0.17.1",
    "update_channel": "stable",
    "replicas": 3,
    "region": "us-west-2",
    "node_group": null,
    "storage_claim_size_gb": 20
  }
}

400: Bad Request

404: Not Found

Examples

Update spicepod configuration:

curl -X PUT https://api.spice.ai/v1/apps/123 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "spicepod": {
      "version": "v1beta1",
      "kind": "Spicepod",
      "name": "my-app",
      "datasets": [
        {
          "from": "s3://my-bucket/data.parquet",
          "name": "sales_data",
          "acceleration": {
            "enabled": true,
            "engine": "arrow"
          }
        }
      ]
    }
  }'

Scale replicas:

curl -X PUT https://api.spice.ai/v1/apps/123 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"replicas": 5}'

Update tags:

curl -X PUT https://api.spice.ai/v1/apps/123 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": {
      "environment": "production",
      "version": "2.0",
      "team": "analytics"
    }
  }'

Delete App

DELETE https://api.spice.ai/v1/apps/{appId}

Soft deletes an app (sets deleted_at timestamp). The app will be stopped and its resources released.

Required scope: apps:delete

Path Parameters

Parameter	Type	Description
appId	integer	The app ID

Response

204: No Content

App deleted successfully. No response body.

404: Not Found

Example

curl -X DELETE https://api.spice.ai/v1/apps/123 \
  -H "Authorization: Bearer <token>"

Deleting an app will stop all running deployments and delete associated resources. This action cannot be undone.

App Lifecycle

1. Create - Create an app with basic metadata

2. Configure - Update the spicepod configuration

3. Deploy - Create a deployment (see Deployments API)

4. Monitor - Check deployment status and logs

5. Update - Modify configuration and redeploy

6. Delete - Remove the app when no longer needed

Best Practices

Naming Conventions

• Use descriptive, lowercase names with hyphens

• Include environment in name or tags: my-app-prod, my-app-staging

• Keep names under 32 characters

Configuration Management

• Store spicepod configurations in version control

• Use tags to track versions and metadata

• Test configuration changes in a staging app first

Scaling

• Start with 1 replica and scale based on load

• Monitor resource usage before increasing replicas

• Use appropriate replica counts for your plan tier

Terraform

Use the spiceai_app resource to manage apps. See Terraform Provider for full documentation.

resource "spiceai_app" "example" {
  name       = "my-app"
  cname      = "us-east-2.spice.cloud"
  visibility = "private"

  spicepod = <<-YAML
    version: v1beta1
    kind: Spicepod
    name: my-app
    datasets:
      - name: taxi_trips
        from: s3://spiceai-demo-datasets/taxi_trips/2024/
        params:
          file_format: parquet
  YAML

  image_tag = "latest"
  replicas  = 2
}

See also:

• Deployments API - Deploy your app

• Secrets API - Manage app secrets

• API Keys - Manage app API keys