Spice.ai Cloud Management

Manage Spice.ai Cloud resources through the Management API at https://api.spice.ai. Create apps, trigger deployments, manage secrets and API keys, and administer organization members.

Authentication

All endpoints (except /v1/health) require a Bearer token:

curl -H "Authorization: Bearer $SPICE_API_TOKEN" https://api.spice.ai/v1/apps

Get your token from spice.ai/account. Required scopes vary by endpoint (see tables below).

Base URL

https://api.spice.ai

Health Check

curl https://api.spice.ai/v1/health
# {"status":"ok","timestamp":"2024-01-15T10:30:00.000Z"}

No authentication required.

Regions

List available deployment regions. Use the cname value when creating apps.

curl -H "Authorization: Bearer $SPICE_API_TOKEN" \
  https://api.spice.ai/v1/regions

Scope: apps:read

Response:

{
  "regions": [
    {
      "name": "US West",
      "region": "us-west-2",
      "cname": "us-west-2",
      "provider": "aws",
      "providerName": "Amazon Web Services"
    }
  ],
  "default": "us-west-2"
}

Apps

Manage Spice.ai Cloud applications.

Create App

curl -X POST https://api.spice.ai/v1/apps \
  -H "Authorization: Bearer $SPICE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-app",
    "cname": "us-west-2",
    "description": "Production analytics app",
    "visibility": "private"
  }'

Status codes: 201 created, 400 validation error, 409 name conflict

Update App

curl -X PUT https://api.spice.ai/v1/apps/{appId} \
  -H "Authorization: Bearer $SPICE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description",
    "replicas": 3,
    "image_tag": "1.5.0-models"
  }'

Updatable fields: description, visibility, production_branch, tags, spicepod, image_tag, image, registry, update_channel, replicas (1-10), region, node_group, storage_claim_size_gb

Delete App

curl -X DELETE https://api.spice.ai/v1/apps/{appId} \
  -H "Authorization: Bearer $SPICE_API_TOKEN"

Soft-deletes the app and stops all running deployments. Returns 204.

Deployments

Deploy and manage app instances.

List Deployments

curl -H "Authorization: Bearer $SPICE_API_TOKEN" \
  "https://api.spice.ai/v1/apps/{appId}/deployments?limit=10&status=succeeded"

Create Deployment

curl -X POST https://api.spice.ai/v1/apps/{appId}/deployments \
  -H "Authorization: Bearer $SPICE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "branch": "main",
    "commit_sha": "abc123",
    "commit_message": "Add sales dataset"
  }'

Returns 202 with status queued. Returns 409 if a deployment is already in progress.

Secrets

Manage app secrets (AES-256 encrypted at rest, TLS 1.3 in transit). Values are always masked in API responses.

Create or Update Secret

curl -X POST https://api.spice.ai/v1/apps/{appId}/secrets \
  -H "Authorization: Bearer $SPICE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "OPENAI_API_KEY", "value": "sk-..."}'

Upsert operation — creates if new, updates if exists. Name must start with a letter or underscore; alphanumeric and underscores only.

Delete Secret

curl -X DELETE https://api.spice.ai/v1/apps/{appId}/secrets/OPENAI_API_KEY \
  -H "Authorization: Bearer $SPICE_API_TOKEN"

API Keys

Each app has two API keys (primary and secondary) for zero-downtime rotation.

Regenerate API Key

# Regenerate primary key (default)
curl -X POST https://api.spice.ai/v1/apps/{appId}/api-keys \
  -H "Authorization: Bearer $SPICE_API_TOKEN"

# Regenerate secondary key
curl -X POST https://api.spice.ai/v1/apps/{appId}/api-keys \
  -H "Authorization: Bearer $SPICE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key_number": 2}'

# Regenerate both
curl -X POST https://api.spice.ai/v1/apps/{appId}/api-keys \
  -H "Authorization: Bearer $SPICE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key_number": 0}'

key_number: 0 (both), 1 (primary, default), 2 (secondary)

Using API Keys with Runtime

# SQL query
curl -H "x-api-key: <api-key>" https://data.spiceai.io/v1/sql \
  -d "SELECT * FROM my_dataset LIMIT 10"

# Chat (OpenAI-compatible)
curl https://data.spiceai.io/v1/chat/completions \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4", "messages": [{"role":"user","content":"Hello"}]}'

# Search
curl https://data.spiceai.io/v1/search \
  -H "x-api-key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{"datasets": ["my_dataset"], "text": "search query"}'

Members

Manage organization members. Currently all members have full access; role-based access control is planned.

Add Member

curl -X POST https://api.spice.ai/v1/members \
  -H "Authorization: Bearer $SPICE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"username": "jdoe", "roles": ["member"]}'

Roles: owner, member, billing. User must have signed in to Spice.ai at least once. Returns 404 if user not found, 409 if already a member.

Remove Member

curl -X DELETE https://api.spice.ai/v1/members/{memberId} \
  -H "Authorization: Bearer $SPICE_API_TOKEN"

Cannot remove the organization owner (403).

Container Images

List available Spice runtime versions for deployments.

# Stable channel (default)
curl -H "Authorization: Bearer $SPICE_API_TOKEN" \
  https://api.spice.ai/v1/container-images

# Enterprise channel
curl -H "Authorization: Bearer $SPICE_API_TOKEN" \
  "https://api.spice.ai/v1/container-images?channel=enterprise"

Scope: apps:read

Response:

{
  "images": [
    {"name": "spiceai/spiceai:1.5.0-models", "tag": "1.5.0-models", "channel": "stable"}
  ],
  "default": "1.5.0-models"
}

Use the tag value in app image_tag configuration or deployment requests.

Common Workflows

Create and Deploy an App

# 1. List regions
curl -H "Authorization: Bearer $SPICE_API_TOKEN" \
  https://api.spice.ai/v1/regions

# 2. Create app
curl -X POST https://api.spice.ai/v1/apps \
  -H "Authorization: Bearer $SPICE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "analytics-app", "cname": "us-west-2"}'

# 3. Add secrets (use the app ID from step 2)
curl -X POST https://api.spice.ai/v1/apps/123/secrets \
  -H "Authorization: Bearer $SPICE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "PG_PASS", "value": "secret123"}'

# 4. Deploy
curl -X POST https://api.spice.ai/v1/apps/123/deployments \
  -H "Authorization: Bearer $SPICE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"branch": "main", "commit_message": "Initial deployment"}'

# 5. Check deployment status
curl -H "Authorization: Bearer $SPICE_API_TOKEN" \
  "https://api.spice.ai/v1/apps/123/deployments?limit=1"

Rotate API Keys (Zero Downtime)

# 1. Get current keys
curl -H "Authorization: Bearer $SPICE_API_TOKEN" \
  https://api.spice.ai/v1/apps/123/api-keys

# 2. Regenerate secondary key
curl -X POST https://api.spice.ai/v1/apps/123/api-keys \
  -H "Authorization: Bearer $SPICE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key_number": 2}'

# 3. Update clients to use new secondary key
# 4. Regenerate primary key
curl -X POST https://api.spice.ai/v1/apps/123/api-keys \
  -H "Authorization: Bearer $SPICE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key_number": 1}'

Using the Helper Script

A helper script is available at /mnt/skills/spice-cloud-management/scripts/spice-cloud.sh for common operations.

# Set your API token
export SPICE_API_TOKEN="your-token"

# List apps
bash /mnt/skills/spice-cloud-management/scripts/spice-cloud.sh list-apps

# Create app
bash /mnt/skills/spice-cloud-management/scripts/spice-cloud.sh create-app my-app us-west-2

# Deploy app
bash /mnt/skills/spice-cloud-management/scripts/spice-cloud.sh deploy 123

# Add secret
bash /mnt/skills/spice-cloud-management/scripts/spice-cloud.sh add-secret 123 DB_PASSWORD secret123

# List deployments
bash /mnt/skills/spice-cloud-management/scripts/spice-cloud.sh list-deployments 123

# Get API keys
bash /mnt/skills/spice-cloud-management/scripts/spice-cloud.sh get-api-keys 123

Present Results to User

When presenting management API results:

• Show app IDs and names in a table for list operations
• Show deployment status clearly (queued/in_progress/succeeded/failed)
• Never display secret values — confirm creation/update only
• Show API keys with a warning about secure storage
• Include the app URL format: https://<app-name>.spice.ai

Troubleshooting

Documentation

• Management API Reference
• Interactive API Docs
• Spice.ai Cloud