Apps

Manage apps and their configurations

List apps

get

Returns all apps belonging to the authenticated organization.

Authorizations

AuthorizationstringRequired

OAuth 2.0 access token obtained from the Spice.ai authentication service

Responses

200

List of apps

application/json

401

Unauthorized

403

Insufficient scope

get/v1/apps

GET /v1/apps HTTP/1.1
Host: api.spice.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "apps": [
    {
      "id": 1,
      "name": "text",
      "description": "text",
      "visibility": "public",
      "created_at": "2026-01-01T00:00:00.000Z",
      "cname": "text",
      "cluster_id": "text",
      "tags": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ]
}

Create an app

post

Creates a new app in the authenticated organization.

Authorizations

AuthorizationstringRequired

OAuth 2.0 access token obtained from the Spice.ai authentication service

Body

namestring · min: 4Required

App name (letters, numbers, hyphens only)

Pattern: ^[a-zA-Z0-9-]+$

regionstring · enumOptional

Cloud region where the app will be deployed (e.g. us-east-1).

Possible values:

cnamestringOptional

Deprecated. Internal region CNAME (e.g. us-east-1-prod-aws-data). Use region instead. Accepted for backwards compatibility when region is omitted.

descriptionstringOptional

App description

visibilitystring · enumOptionalDefault: privatePossible values:

update_channelstring · enumOptional

Update channel for the app deployment

Possible values:

replicasintegerOptional

Number of replicas

Responses

201

App created successfully. The response may include a warning field if initial configuration could not be applied.

application/json

idintegerOptional

Unique identifier for the app

namestringOptional

Name of the app

descriptionstring · nullableOptional

Description of the app

visibilitystring · enumOptional

Visibility setting for the app

Possible values:

created_atstring · date-timeOptional

Timestamp when the app was created

cnamestringOptional

Region identifier

production_branchstring · nullableOptional

Production branch for the app

api_keystringOptionalDeprecated

Deprecated. Use the API Keys endpoints instead.

warningstring · nullableOptional

Present when the app was created but initial configuration could not be applied

400

Invalid request body or invalid region

401

Unauthorized

403

Insufficient scope, organization app limit exceeded, or private compute addon required for resource limits

409

An app with this name already exists

post/v1/apps

POST /v1/apps HTTP/1.1
Host: api.spice.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 448

{
  "name": "text",
  "region": "us-east-1",
  "cname": "text",
  "description": "text",
  "visibility": "private",
  "tags": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "update_channel": "stable",
  "replicas": 1,
  "resources": {
    "limits": {
      "cpu": "text",
      "memory": "text",
      "ephemeral-storage": "text"
    },
    "requests": {
      "cpu": "text",
      "memory": "text"
    }
  },
  "executor": {
    "replicas": 1,
    "resources": {
      "limits": {
        "cpu": "text",
        "memory": "text",
        "ephemeral-storage": "text"
      },
      "requests": {
        "cpu": "text",
        "memory": "text"
      }
    }
  }
}

{
  "id": 1,
  "name": "text",
  "description": "text",
  "visibility": "public",
  "created_at": "2026-01-01T00:00:00.000Z",
  "cname": "text",
  "production_branch": "text",
  "tags": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "warning": "text",
  "config": {
    "spicepod": {},
    "registry": "text",
    "image_tag": "text",
    "update_channel": "stable",
    "replicas": 1,
    "resources": {
      "limits": {
        "cpu": "text",
        "memory": "text",
        "ephemeral-storage": "text"
      },
      "requests": {
        "cpu": "text",
        "memory": "text"
      }
    },
    "executor": {
      "replicas": 1,
      "resources": {
        "limits": {
          "cpu": "text",
          "memory": "text",
          "ephemeral-storage": "text"
        },
        "requests": {
          "cpu": "text",
          "memory": "text"
        }
      }
    },
    "region": "text",
    "node_group": "text",
    "storage_claim_size_gb": 1
  }
}

Get an app

get

Returns details for a specific app, including its configuration.

Authorizations

AuthorizationstringRequired

OAuth 2.0 access token obtained from the Spice.ai authentication service

Path parameters

appIdintegerRequired

The ID of the app

Responses

200

App details with configuration

application/json

idintegerOptional

namestringOptional

descriptionstringOptional

visibilitystring · enumOptionalPossible values:

created_atstring · date-timeOptional

regionstringOptional

production_branchstringOptional

api_keystringOptionalDeprecated

Deprecated. Use the API Keys endpoints instead.

401

Unauthorized

403

Insufficient scope

404

App not found

500

Internal server error

get/v1/apps/{appId}

GET /v1/apps/{appId} HTTP/1.1
Host: api.spice.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": 1,
  "name": "text",
  "description": "text",
  "visibility": "public",
  "created_at": "2026-01-01T00:00:00.000Z",
  "region": "text",
  "production_branch": "text",
  "tags": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "config": {
    "spicepod": {},
    "image_tag": "text",
    "update_channel": "stable",
    "replicas": 1,
    "resources": {
      "limits": {
        "cpu": "text",
        "memory": "text",
        "ephemeral-storage": "text"
      },
      "requests": {
        "cpu": "text",
        "memory": "text"
      }
    },
    "executor": {
      "replicas": 1,
      "resources": {
        "limits": {
          "cpu": "text",
          "memory": "text",
          "ephemeral-storage": "text"
        },
        "requests": {
          "cpu": "text",
          "memory": "text"
        }
      },
      "storage_size_gb": 1
    },
    "region": "text",
    "storage_size_gb": 1
  }
}

Update an app

put

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

Authorizations

AuthorizationstringRequired

OAuth 2.0 access token obtained from the Spice.ai authentication service

Path parameters

appIdintegerRequired

The ID of the app

Body

descriptionstringOptional

visibilitystring · enumOptionalPossible values:

production_branchstringOptional

spicepodone ofOptional

stringOptional

YAML string of the spicepod configuration

or

objectOptional

JSON object of the spicepod configuration

image_tagstringOptional

Runtime image tag

update_channelstring · enumOptional

Update channel for the runtime

Possible values:

replicasintegerOptional

regionstringOptional

storage_size_gbnumberOptional

storage_claim_size_gbnumberOptionalDeprecated

Deprecated. Use storage_size_gb instead.

Responses

200

App updated successfully

application/json

idintegerOptional

Unique identifier for the app

namestringOptional

Name of the app

descriptionstring · nullableOptional

Description of the app

visibilitystring · enumOptional

Visibility setting for the app

Possible values:

created_atstring · date-timeOptional

Timestamp when the app was created

cnamestringOptional

Region identifier

production_branchstring · nullableOptional

Production branch for the app

api_keystringOptionalDeprecated

Deprecated. Use the API Keys endpoints instead.

warningstring · nullableOptional

Present when the app was created but initial configuration could not be applied

400

Invalid request body or app ID

401

Unauthorized

403

Insufficient scope, requested replicas or resources exceed plan limits, or private compute addon is required

404

App not found

500

Internal server error

put/v1/apps/{appId}

PUT /v1/apps/{appId} HTTP/1.1
Host: api.spice.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 517

{
  "description": "text",
  "visibility": "public",
  "production_branch": "text",
  "tags": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "spicepod": "text",
  "image_tag": "text",
  "update_channel": "stable",
  "replicas": 1,
  "resources": {
    "limits": {
      "cpu": "text",
      "memory": "text",
      "ephemeral-storage": "text"
    },
    "requests": {
      "cpu": "text",
      "memory": "text"
    }
  },
  "executor": {
    "replicas": 1,
    "resources": {
      "limits": {
        "cpu": "text",
        "memory": "text",
        "ephemeral-storage": "text"
      },
      "requests": {
        "cpu": "text",
        "memory": "text"
      }
    },
    "storage_size_gb": 1
  },
  "region": "text",
  "storage_size_gb": 1
}

{
  "id": 1,
  "name": "text",
  "description": "text",
  "visibility": "public",
  "created_at": "2026-01-01T00:00:00.000Z",
  "cname": "text",
  "production_branch": "text",
  "tags": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "warning": "text",
  "config": {
    "spicepod": {},
    "registry": "text",
    "image_tag": "text",
    "update_channel": "stable",
    "replicas": 1,
    "resources": {
      "limits": {
        "cpu": "text",
        "memory": "text",
        "ephemeral-storage": "text"
      },
      "requests": {
        "cpu": "text",
        "memory": "text"
      }
    },
    "executor": {
      "replicas": 1,
      "resources": {
        "limits": {
          "cpu": "text",
          "memory": "text",
          "ephemeral-storage": "text"
        },
        "requests": {
          "cpu": "text",
          "memory": "text"
        }
      }
    },
    "region": "text",
    "node_group": "text",
    "storage_claim_size_gb": 1
  }
}

Delete an app

delete

Deletes an app and tears down its runtime resources.

Authorizations

AuthorizationstringRequired

OAuth 2.0 access token obtained from the Spice.ai authentication service

Path parameters

appIdintegerRequired

The ID of the app to delete

Responses

204

App deleted successfully

No content

400

Invalid app ID

401

Unauthorized

403

Insufficient scope

404

App not found

500

Internal server error

delete/v1/apps/{appId}

DELETE /v1/apps/{appId} HTTP/1.1
Host: api.spice.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Get app metrics

get

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

Authorizations

AuthorizationstringRequired

OAuth 2.0 access token obtained from the Spice.ai authentication service

Path parameters

appIdintegerRequired

The ID of the app

Query parameters

windowstringOptional

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

Resource and ingestion metrics. Missing fields indicate no data is currently available. Individual metric queries may fail independently; partial results are returned when possible.

application/json

400

Invalid app ID

401

Unauthorized

403

Insufficient scope

404

App or organization not found

422

Organization is not fully configured

500

Internal server error

503

Metrics service unavailable

get/v1/apps/{appId}/metrics

GET /v1/apps/{appId}/metrics HTTP/1.1
Host: api.spice.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "ingestion": {
    "rows_ingested": 1,
    "bytes_ingested": 1
  },
  "cluster": {
    "active_executors_count": 1
  },
  "metrics": {
    "ANY_ADDITIONAL_PROPERTY": {
      "cpu_usage_percent": 1,
      "memory_usage_bytes": 1,
      "disk_read_bytes": 1,
      "disk_read_operations": 1,
      "disk_write_bytes": 1,
      "disk_write_operations": 1
    }
  }
}