Projects
Manage projects and their configurations
Returns all projects belonging to the authenticated organization.
OAuth 2.0 access token obtained from the Spice.ai authentication service
The organization to act on, by handle. Omit it to act on the organization the credential is bound to; sending it blank is a 400, not the same as omitting it. A user credential may name any organization its owner belongs to; a machine credential is pinned to its own.
^[A-Za-z0-9._-]{1,255}$List of projects
Unauthorized
Insufficient scope
GET /v1/projects HTTP/1.1
Host: api.spice.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"projects": [
{
"id": 1,
"name": "text",
"kind": "managed",
"description": "text",
"visibility": "public",
"created_at": "2026-01-01T00:00:00.000Z",
"cname": "text",
"cluster_name": "text",
"endpoint": "text",
"tags": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}
]
}Creates a new project in the authenticated organization.
OAuth 2.0 access token obtained from the Spice.ai authentication service
The organization to act on, by handle. Omit it to act on the organization the credential is bound to; sending it blank is a 400, not the same as omitting it. A user credential may name any organization its owner belongs to; a machine credential is pinned to its own.
^[A-Za-z0-9._-]{1,255}$Project name (letters, numbers, hyphens only)
^[a-zA-Z0-9-]+$Cloud region where a managed project will be deployed (e.g. us-east-1). Omit this, cname, and cluster_name to create an unattached standalone project whose placement is resolved when linked.
Deprecated. Internal region CNAME (e.g. us-east-1-prod-aws-data). Use region instead. Accepted for backwards compatibility when region is omitted. Omit all region sources to create an unattached standalone project.
Name of the dedicated cluster to deploy to, as listed by GET /v1/clusters. Provide exactly one of region or cluster_name. When set, the region/routing are derived from the cluster; if region is also provided it must match the cluster's region. Omit all region sources to create an unattached standalone project.
Project description
privatePossible values: Update channel for a managed project deployment. A standalone project has no spicepod until linking, so configure its channel after linking.
Number of replicas for a managed project. Rejected for standalone projects.
Project created successfully. The response may include a warning field if initial configuration could not be applied.
Unique identifier for the project
Name of the project
Resolved project hosting model
Description of the project
Visibility setting for the project
Timestamp when the project was created
Region identifier
Resolved dedicated cluster name; null for projects not assigned to a dedicated cluster.
The data-plane endpoint the project connects to, or null before a standalone instance is attached.
Production branch for the project
Deprecated. Use the API Keys endpoints instead.
Timestamp when the project was paused; null while running
Present when the project was created but initial configuration could not be applied
Invalid request body or invalid region
Unauthorized
Insufficient scope, dedicated-cluster assignment or special-org private-compute ceilings required for resource limits, or requested resources exceed dedicated-cluster capacity
A project with this name already exists
Too many project creation requests (rate limited)
Project creation failed, including when the name-collision check could not be read
POST /v1/projects HTTP/1.1
Host: api.spice.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 470
{
"name": "text",
"region": "us-east-1",
"cname": "text",
"cluster_name": "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",
"kind": "managed",
"description": "text",
"visibility": "public",
"created_at": "2026-01-01T00:00:00.000Z",
"cname": "text",
"cluster_name": "text",
"endpoint": "text",
"production_branch": "text",
"tags": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"paused_at": "2026-01-01T00:00:00.000Z",
"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
}
}Returns details for a specific project, including its configuration.
OAuth 2.0 access token obtained from the Spice.ai authentication service
The ID of the project
The organization to act on, by handle. Omit it to act on the organization the credential is bound to; sending it blank is a 400, not the same as omitting it. A user credential may name any organization its owner belongs to; a machine credential is pinned to its own.
^[A-Za-z0-9._-]{1,255}$Project details with configuration
Resolved project hosting model
Resolved dedicated cluster name; null for projects not assigned to a dedicated cluster.
The data-plane endpoint the project connects to, or null before a standalone instance is attached.
Deprecated. Use the API Keys endpoints instead.
Timestamp when the project was paused; null while running
Unauthorized
Insufficient scope
Project not found
Internal server error
GET /v1/projects/{projectId} HTTP/1.1
Host: api.spice.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"id": 1,
"name": "text",
"kind": "managed",
"description": "text",
"visibility": "public",
"created_at": "2026-01-01T00:00:00.000Z",
"cluster_name": "text",
"endpoint": "text",
"production_branch": "text",
"tags": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"paused_at": "2026-01-01T00:00:00.000Z",
"config": {
"spicepod": {},
"image_tag": "text",
"update_channel": "stable",
"version": "text",
"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
}
}Updates a project's metadata and configuration, including description, visibility, spicepod configuration, replicas, and resource limits.
OAuth 2.0 access token obtained from the Spice.ai authentication service
The ID of the project
The organization to act on, by handle. Omit it to act on the organization the credential is bound to; sending it blank is a 400, not the same as omitting it. A user credential may name any organization its owner belongs to; a machine credential is pinned to its own.
^[A-Za-z0-9._-]{1,255}$YAML string of the spicepod configuration
JSON object of the spicepod configuration
Runtime image tag for a managed project; rejected for standalone projects. A non-empty value pins the project. On stable or preview, send null to clear a pin so deploys resolve from the channel catalog (stable - latest GA for the configured version range; preview - latest RC). null is rejected on nightly and internal channels.
Update channel for a managed runtime; rejected for standalone projects.
Semver range for a managed runtime version (e.g. 1.x, 2.x); rejected for standalone projects.
Managed runtime replica count; rejected for standalone projects.
Managed project region; standalone placement is resolved during attachment.
Reassign the project to a dedicated cluster, as listed by GET /v1/clusters. Provide at most one of region or cluster_name. When set, region/routing are derived from the cluster; if region is also provided it must match the cluster's region. Rejected for standalone projects, whose placement is resolved during attachment.
Managed runtime storage size; rejected for standalone projects.
Deprecated. Use storage_size_gb instead. Rejected for standalone projects.
Project updated successfully
Unique identifier for the project
Name of the project
Resolved project hosting model
Description of the project
Visibility setting for the project
Timestamp when the project was created
Region identifier
Resolved dedicated cluster name; null for projects not assigned to a dedicated cluster.
The data-plane endpoint the project connects to, or null before a standalone instance is attached.
Production branch for the project
Deprecated. Use the API Keys endpoints instead.
Timestamp when the project was paused; null while running
Present when the project was created but initial configuration could not be applied
Invalid request body or project ID, including placement or hosted runtime fields that do not apply to standalone projects
Unauthorized
Insufficient scope, viewer role cannot mutate projects, requested replicas or resources exceed plan limits, dedicated-cluster assignment or special-org private-compute ceilings required, requested resources exceed dedicated-cluster capacity, image_tag was supplied outside the Enterprise plan (code: image_tag_requires_enterprise), or the requested runtime image is not available for the organization plan (code: image_tag_not_allowed_for_plan); omitting image_tag leaves the configured image unchanged
Project not found
Internal server error
The configuration was stored but could not be published to the spicepod registry (code: registry_publish_failed), so the project still deploys its previously published configuration. Retry the request.
Runtime version catalog is unavailable
PUT /v1/projects/{projectId} HTTP/1.1
Host: api.spice.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 556
{
"description": "text",
"visibility": "public",
"production_branch": "text",
"tags": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"spicepod": "text",
"image_tag": "text",
"update_channel": "stable",
"version": "text",
"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",
"cluster_name": "text",
"storage_size_gb": 1
}{
"id": 1,
"name": "text",
"kind": "managed",
"description": "text",
"visibility": "public",
"created_at": "2026-01-01T00:00:00.000Z",
"cname": "text",
"cluster_name": "text",
"endpoint": "text",
"production_branch": "text",
"tags": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"paused_at": "2026-01-01T00:00:00.000Z",
"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
}
}Deletes a project and tears down its runtime resources.
OAuth 2.0 access token obtained from the Spice.ai authentication service
The ID of the project to delete
The organization to act on, by handle. Omit it to act on the organization the credential is bound to; sending it blank is a 400, not the same as omitting it. A user credential may name any organization its owner belongs to; a machine credential is pinned to its own.
^[A-Za-z0-9._-]{1,255}$Project deleted successfully
No content
Invalid project ID
Unauthorized
Insufficient scope or viewer role cannot mutate projects
Project not found
Internal server error
DELETE /v1/projects/{projectId} HTTP/1.1
Host: api.spice.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
No content
Pauses the project's running spicepod. The runtime is torn down and the spicepod record is marked as paused. Settings and configuration are preserved. Resume with POST /v1/projects/{projectId}/resume. Requires apps:write.
OAuth 2.0 access token obtained from the Spice.ai authentication service
The ID of the project to pause
The organization to act on, by handle. Omit it to act on the organization the credential is bound to; sending it blank is a 400, not the same as omitting it. A user credential may name any organization its owner belongs to; a machine credential is pinned to its own.
^[A-Za-z0-9._-]{1,255}$Project paused
The project ID
The project name
Timestamp when the project was paused
Invalid project ID, missing API key, no spicepod configured, or spicepod has been deleted
Unauthorized
Insufficient scope
Project not found
Project is already paused
Internal server error
POST /v1/projects/{projectId}/pause HTTP/1.1
Host: api.spice.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"id": 1,
"name": "text",
"paused_at": "2026-01-01T00:00:00.000Z"
}Clears the paused state on the project's spicepod and creates a new deployment to bring the runtime back up. Requires apps:write.
OAuth 2.0 access token obtained from the Spice.ai authentication service
The ID of the project to resume
The organization to act on, by handle. Omit it to act on the organization the credential is bound to; sending it blank is a 400, not the same as omitting it. A user credential may name any organization its owner belongs to; a machine credential is pinned to its own.
^[A-Za-z0-9._-]{1,255}$Project resumed, deployment created
The project ID
The project name
Always null after a successful resume
ID of the deployment created to bring the runtime back up
Invalid project ID, missing API key, missing project organization, no spicepod configured, spicepod has been deleted, or spicepod configuration is invalid
Unauthorized
Insufficient scope
Project not found
Project is not paused
No runtime version in the catalog matches this project’s version range (code: version_no_match).
Internal server error
The runtime version catalog (Edge Config) is unavailable or empty (code: version_source_unavailable), so an unpinned stable or preview resume cannot resolve an image tag.
POST /v1/projects/{projectId}/resume HTTP/1.1
Host: api.spice.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"id": 1,
"name": "text",
"paused_at": "2026-01-01T00:00:00.000Z",
"deployment_id": 1
}Returns current resource utilization metrics (CPU, memory, disk I/O) and data ingestion metrics for a project.
OAuth 2.0 access token obtained from the Spice.ai authentication service
The ID of the project
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.
The organization to act on, by handle. Omit it to act on the organization the credential is bound to; sending it blank is a 400, not the same as omitting it. A user credential may name any organization its owner belongs to; a machine credential is pinned to its own.
^[A-Za-z0-9._-]{1,255}$Resource and ingestion metrics. Missing fields indicate no data is currently available. Individual metric queries may fail independently; partial results are returned when possible.
Invalid project ID
Unauthorized
Insufficient scope
Project or organization not found
Organization is not fully configured
Internal server error
Metrics service unavailable
GET /v1/projects/{projectId}/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
}
}
}Legacy alias of /v1/projects — projects were previously called apps. Returns all projects belonging to the authenticated organization.
OAuth 2.0 access token obtained from the Spice.ai authentication service
The organization to act on, by handle. Omit it to act on the organization the credential is bound to; sending it blank is a 400, not the same as omitting it. A user credential may name any organization its owner belongs to; a machine credential is pinned to its own.
^[A-Za-z0-9._-]{1,255}$List of projects
Unauthorized
Insufficient scope
GET /v1/apps HTTP/1.1
Host: api.spice.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"apps": [
{
"id": 1,
"name": "text",
"kind": "managed",
"description": "text",
"visibility": "public",
"created_at": "2026-01-01T00:00:00.000Z",
"cname": "text",
"cluster_name": "text",
"endpoint": "text",
"tags": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}
]
}Legacy alias of /v1/projects — projects were previously called apps. Creates a new project in the authenticated organization.
OAuth 2.0 access token obtained from the Spice.ai authentication service
The organization to act on, by handle. Omit it to act on the organization the credential is bound to; sending it blank is a 400, not the same as omitting it. A user credential may name any organization its owner belongs to; a machine credential is pinned to its own.
^[A-Za-z0-9._-]{1,255}$Project name (letters, numbers, hyphens only)
^[a-zA-Z0-9-]+$Cloud region where a managed project will be deployed (e.g. us-east-1). Omit this, cname, and cluster_name to create an unattached standalone project whose placement is resolved when linked.
Deprecated. Internal region CNAME (e.g. us-east-1-prod-aws-data). Use region instead. Accepted for backwards compatibility when region is omitted. Omit all region sources to create an unattached standalone project.
Name of the dedicated cluster to deploy to, as listed by GET /v1/clusters. Provide exactly one of region or cluster_name. When set, the region/routing are derived from the cluster; if region is also provided it must match the cluster's region. Omit all region sources to create an unattached standalone project.
Project description
privatePossible values: Update channel for a managed project deployment. A standalone project has no spicepod until linking, so configure its channel after linking.
Number of replicas for a managed project. Rejected for standalone projects.
Project created successfully. The response may include a warning field if initial configuration could not be applied.
Unique identifier for the project
Name of the project
Resolved project hosting model
Description of the project
Visibility setting for the project
Timestamp when the project was created
Region identifier
Resolved dedicated cluster name; null for projects not assigned to a dedicated cluster.
The data-plane endpoint the project connects to, or null before a standalone instance is attached.
Production branch for the project
Deprecated. Use the API Keys endpoints instead.
Timestamp when the project was paused; null while running
Present when the project was created but initial configuration could not be applied
Invalid request body or invalid region
Unauthorized
Insufficient scope, dedicated-cluster assignment or special-org private-compute ceilings required for resource limits, or requested resources exceed dedicated-cluster capacity
A project with this name already exists
Too many project creation requests (rate limited)
Project creation failed, including when the name-collision check could not be read
POST /v1/apps HTTP/1.1
Host: api.spice.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 470
{
"name": "text",
"region": "us-east-1",
"cname": "text",
"cluster_name": "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",
"kind": "managed",
"description": "text",
"visibility": "public",
"created_at": "2026-01-01T00:00:00.000Z",
"cname": "text",
"cluster_name": "text",
"endpoint": "text",
"production_branch": "text",
"tags": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"paused_at": "2026-01-01T00:00:00.000Z",
"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
}
}Legacy alias of /v1/projects/{projectId} — projects were previously called apps. Returns details for a specific project, including its configuration.
OAuth 2.0 access token obtained from the Spice.ai authentication service
The ID of the project
The organization to act on, by handle. Omit it to act on the organization the credential is bound to; sending it blank is a 400, not the same as omitting it. A user credential may name any organization its owner belongs to; a machine credential is pinned to its own.
^[A-Za-z0-9._-]{1,255}$Project details with configuration
Resolved project hosting model
Resolved dedicated cluster name; null for projects not assigned to a dedicated cluster.
The data-plane endpoint the project connects to, or null before a standalone instance is attached.
Deprecated. Use the API Keys endpoints instead.
Timestamp when the project was paused; null while running
Unauthorized
Insufficient scope
Project not found
Internal server error
GET /v1/apps/{appId} HTTP/1.1
Host: api.spice.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"id": 1,
"name": "text",
"kind": "managed",
"description": "text",
"visibility": "public",
"created_at": "2026-01-01T00:00:00.000Z",
"cluster_name": "text",
"endpoint": "text",
"production_branch": "text",
"tags": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"paused_at": "2026-01-01T00:00:00.000Z",
"config": {
"spicepod": {},
"image_tag": "text",
"update_channel": "stable",
"version": "text",
"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
}
}Legacy alias of /v1/projects/{projectId} — projects were previously called apps. Updates a project's metadata and configuration, including description, visibility, spicepod configuration, replicas, and resource limits.
OAuth 2.0 access token obtained from the Spice.ai authentication service
The ID of the project
The organization to act on, by handle. Omit it to act on the organization the credential is bound to; sending it blank is a 400, not the same as omitting it. A user credential may name any organization its owner belongs to; a machine credential is pinned to its own.
^[A-Za-z0-9._-]{1,255}$YAML string of the spicepod configuration
JSON object of the spicepod configuration
Runtime image tag for a managed project; rejected for standalone projects. A non-empty value pins the project. On stable or preview, send null to clear a pin so deploys resolve from the channel catalog (stable - latest GA for the configured version range; preview - latest RC). null is rejected on nightly and internal channels.
Update channel for a managed runtime; rejected for standalone projects.
Semver range for a managed runtime version (e.g. 1.x, 2.x); rejected for standalone projects.
Managed runtime replica count; rejected for standalone projects.
Managed project region; standalone placement is resolved during attachment.
Reassign the project to a dedicated cluster, as listed by GET /v1/clusters. Provide at most one of region or cluster_name. When set, region/routing are derived from the cluster; if region is also provided it must match the cluster's region. Rejected for standalone projects, whose placement is resolved during attachment.
Managed runtime storage size; rejected for standalone projects.
Deprecated. Use storage_size_gb instead. Rejected for standalone projects.
Project updated successfully
Unique identifier for the project
Name of the project
Resolved project hosting model
Description of the project
Visibility setting for the project
Timestamp when the project was created
Region identifier
Resolved dedicated cluster name; null for projects not assigned to a dedicated cluster.
The data-plane endpoint the project connects to, or null before a standalone instance is attached.
Production branch for the project
Deprecated. Use the API Keys endpoints instead.
Timestamp when the project was paused; null while running
Present when the project was created but initial configuration could not be applied
Invalid request body or project ID, including placement or hosted runtime fields that do not apply to standalone projects
Unauthorized
Insufficient scope, viewer role cannot mutate projects, requested replicas or resources exceed plan limits, dedicated-cluster assignment or special-org private-compute ceilings required, requested resources exceed dedicated-cluster capacity, image_tag was supplied outside the Enterprise plan (code: image_tag_requires_enterprise), or the requested runtime image is not available for the organization plan (code: image_tag_not_allowed_for_plan); omitting image_tag leaves the configured image unchanged
Project not found
Internal server error
The configuration was stored but could not be published to the spicepod registry (code: registry_publish_failed), so the project still deploys its previously published configuration. Retry the request.
Runtime version catalog is unavailable
PUT /v1/apps/{appId} HTTP/1.1
Host: api.spice.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 556
{
"description": "text",
"visibility": "public",
"production_branch": "text",
"tags": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"spicepod": "text",
"image_tag": "text",
"update_channel": "stable",
"version": "text",
"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",
"cluster_name": "text",
"storage_size_gb": 1
}{
"id": 1,
"name": "text",
"kind": "managed",
"description": "text",
"visibility": "public",
"created_at": "2026-01-01T00:00:00.000Z",
"cname": "text",
"cluster_name": "text",
"endpoint": "text",
"production_branch": "text",
"tags": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"paused_at": "2026-01-01T00:00:00.000Z",
"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
}
}Legacy alias of /v1/projects/{projectId} — projects were previously called apps. Deletes a project and tears down its runtime resources.
OAuth 2.0 access token obtained from the Spice.ai authentication service
The ID of the project to delete
The organization to act on, by handle. Omit it to act on the organization the credential is bound to; sending it blank is a 400, not the same as omitting it. A user credential may name any organization its owner belongs to; a machine credential is pinned to its own.
^[A-Za-z0-9._-]{1,255}$Project deleted successfully
No content
Invalid project ID
Unauthorized
Insufficient scope or viewer role cannot mutate projects
Project not found
Internal server error
DELETE /v1/apps/{appId} HTTP/1.1
Host: api.spice.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
No content
Legacy alias of /v1/projects/{projectId}/pause — projects were previously called apps. Pauses the project's running spicepod. The runtime is torn down and the spicepod record is marked as paused. Settings and configuration are preserved. Resume with POST /v1/projects/{projectId}/resume. Requires apps:write.
OAuth 2.0 access token obtained from the Spice.ai authentication service
The ID of the project to pause
The organization to act on, by handle. Omit it to act on the organization the credential is bound to; sending it blank is a 400, not the same as omitting it. A user credential may name any organization its owner belongs to; a machine credential is pinned to its own.
^[A-Za-z0-9._-]{1,255}$Project paused
The project ID
The project name
Timestamp when the project was paused
Invalid project ID, missing API key, no spicepod configured, or spicepod has been deleted
Unauthorized
Insufficient scope
Project not found
Project is already paused
Internal server error
POST /v1/apps/{appId}/pause HTTP/1.1
Host: api.spice.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"id": 1,
"name": "text",
"paused_at": "2026-01-01T00:00:00.000Z"
}Legacy alias of /v1/projects/{projectId}/resume — projects were previously called apps. Clears the paused state on the project's spicepod and creates a new deployment to bring the runtime back up. Requires apps:write.
OAuth 2.0 access token obtained from the Spice.ai authentication service
The ID of the project to resume
The organization to act on, by handle. Omit it to act on the organization the credential is bound to; sending it blank is a 400, not the same as omitting it. A user credential may name any organization its owner belongs to; a machine credential is pinned to its own.
^[A-Za-z0-9._-]{1,255}$Project resumed, deployment created
The project ID
The project name
Always null after a successful resume
ID of the deployment created to bring the runtime back up
Invalid project ID, missing API key, missing project organization, no spicepod configured, spicepod has been deleted, or spicepod configuration is invalid
Unauthorized
Insufficient scope
Project not found
Project is not paused
No runtime version in the catalog matches this project’s version range (code: version_no_match).
Internal server error
The runtime version catalog (Edge Config) is unavailable or empty (code: version_source_unavailable), so an unpinned stable or preview resume cannot resolve an image tag.
POST /v1/apps/{appId}/resume HTTP/1.1
Host: api.spice.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"id": 1,
"name": "text",
"paused_at": "2026-01-01T00:00:00.000Z",
"deployment_id": 1
}Legacy alias of /v1/projects/{projectId}/metrics — projects were previously called apps. Returns current resource utilization metrics (CPU, memory, disk I/O) and data ingestion metrics for a project.
OAuth 2.0 access token obtained from the Spice.ai authentication service
The ID of the project
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.
The organization to act on, by handle. Omit it to act on the organization the credential is bound to; sending it blank is a 400, not the same as omitting it. A user credential may name any organization its owner belongs to; a machine credential is pinned to its own.
^[A-Za-z0-9._-]{1,255}$Resource and ingestion metrics. Missing fields indicate no data is currently available. Individual metric queries may fail independently; partial results are returned when possible.
Invalid project ID
Unauthorized
Insufficient scope
Project or organization not found
Organization is not fully configured
Internal server error
Metrics service unavailable
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
}
}
}Last updated
Was this helpful?