Projects

Manage projects and their configurations

OpenAPIapi.spice.ai/openapi.json

List projects

GET/v1/projects

Returns projects belonging to the authenticated organization. Page with limit (default 1000, max 1000). Prefer after_id for a stable keyset (descending id). offset is accepted for compatibility. PostgREST also caps a page at 1000 rows.

Query parameters

Name	Type	Required	Description
`limit`	integer	No	Maximum number of projects to return Default: `1000` Minimum: `1` Maximum: `1000`
`offset`	integer	No	Number of projects to skip when a cursor is not supplied Default: `0` Minimum: `0`
`after_id`	integer	No	Return projects with a strictly smaller id than this value. Minimum: `1`

Header parameters

Name	Type	Required	Description
`Authorization`	string	Yes	`Bearer <token>`. Authentication lists the tokens it accepts.
`X-Org-Name`	string	No	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 portal session token is bound to none, so it must send this header on every route but `GET /v1/orgs` (400 `org_assertion_required` otherwise). Pattern: `^[A-Za-z0-9._-]{1,255}$`

Example request

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

Responses

200OK
List of projects
application/json
- projectsarray of object
  10 properties
  idinteger
  Unique identifier for the project
  namestring
  Name of the project
  kindstring
  Resolved project hosting model
  Allowed values: managed, standalone, byoc
  descriptionstring | null
  Description of the project
  visibilitystring
  Visibility setting for the project
  Allowed values: public, private
  created_atstring (date-time)
  Timestamp when the project was created
  cnamestring | null
  Region identifier
  cluster_namestring | null
  Resolved dedicated cluster name; null for projects not assigned to a dedicated cluster.
  endpointstring | null
  The data-plane endpoint the project connects to, or null before a standalone instance is attached.
  tagsmap of string | null
  Key-value tags for the project
400Bad Request
Invalid limit, offset, or after_id
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope

Create a project

POST/v1/projects

Creates a new project in the authenticated organization.

Header parameters

Name	Type	Required	Description
`Authorization`	string	Yes	`Bearer <token>`. Authentication lists the tokens it accepts.
`X-Org-Name`	string	No	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 portal session token is bound to none, so it must send this header on every route but `GET /v1/orgs` (400 `org_assertion_required` otherwise). Pattern: `^[A-Za-z0-9._-]{1,255}$`

Request body

Required

application/json

namestringRequired
Project name (letters, numbers, hyphens only)
- Minimum length: 4
- Pattern: ^[a-zA-Z0-9-]+$
regionstring
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.
- Allowed values: us-east-1, us-west-2
cnamestring
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.
cluster_namestring
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.
descriptionstring
Project description
visibilitystring
- Allowed values: public, private
- Default: private
default_alertsboolean
Create default monitoring alerts for the new managed project. False skips initial setup. Manual alert creation remains available.
- Default: true
tagsmap of string
Key-value tags for the project
update_channelstring
Update channel for a managed project deployment. A standalone project has no spicepod until linking, so configure its channel after linking.
- Allowed values: stable, preview, nightly
replicasinteger
Number of replicas for a managed project. Rejected for standalone projects.
- Minimum: 0
resourcesobject
Resource requests and limits for a managed project container. Rejected for standalone projects.
2 properties
- limitsobject
  3 properties
  - cpustring
    Whole-number vCPU limit, or '-' for no CPU limit
  - memorystring
    Memory limit in Gi (for example, 16Gi)
  - ephemeral-storagestring
    Ephemeral storage limit in Gi (for example, 8Gi)
- requestsobject
  2 properties
  - cpustring
    CPU request. Minimum 100 millicores (for example, 100m or 0.1).
  - memorystring
    Memory request. Minimum 192Mi.
executorobject
Executor container configuration for a managed project. Rejected for standalone projects.
2 properties
- replicasinteger
  Number of executor replicas
  - Minimum: 0
- resourcesobject
  Resource requests and limits for the executor container
  2 properties
  - limitsobject
    3 properties
    cpustring
    Whole-number vCPU limit, or '-' for no CPU limit
    memorystring
    Memory limit in Gi (for example, 16Gi)
    ephemeral-storagestring
    Ephemeral storage limit in Gi (for example, 8Gi)
  - requestsobject
    2 properties
    cpustring
    CPU request. Minimum 100 millicores (for example, 100m or 0.1).
    memorystring
    Memory request. Minimum 192Mi.

Example request

curl -X POST "https://api.spice.ai/v1/projects" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string"
  }'

Responses

201Created
Project created successfully. The response may include a warning field if initial configuration could not be applied.
application/json
- idinteger
  Unique identifier for the project
- namestring
  Name of the project
- kindstring
  Resolved project hosting model
  - Allowed values: managed, standalone, byoc
- descriptionstring | null
  Description of the project
- visibilitystring
  Visibility setting for the project
  - Allowed values: public, private
- created_atstring (date-time)
  Timestamp when the project was created
- cnamestring | null
  Region identifier
- cluster_namestring | null
  Resolved dedicated cluster name; null for projects not assigned to a dedicated cluster.
- endpointstring | null
  The data-plane endpoint the project connects to, or null before a standalone instance is attached.
- production_branchstring | null
  Production branch for the project
- api_keystringDeprecated
  Deprecated. Use the API Keys endpoints instead.
- tagsmap of string | null
  Key-value tags for the project
- forked_fromobject | null
  The project this project was forked from, while that project is live in the same organization. Null for a project that was not created as a fork.
  2 properties
  idintegerRequired
  ID of the source project
  namestringRequired
  Name of the source project
- paused_atstring (date-time) | null
  Timestamp when the project was paused; null while running
- warningstring | null
  Present when the project was created but initial configuration could not be applied
- configobject | null
  Runtime configuration; null for an unattached standalone project.
  10 properties
  spicepodobject | null
  Spicepod configuration
  registrystring | null
  Container registry for the runtime image
  image_tagstring | null
  Runtime image tag
  update_channelstring | null
  Update channel for the runtime
  Allowed values: stable, preview, nightly
  replicasinteger
  Number of replicas
  resourcesobject | null
  Resource requests and limits for the project container
  2 properties
  limitsobject
  3 properties
  cpustring
  Whole-number vCPU limit, or '-' for no CPU limit
  memorystring
  Memory limit in Gi (for example, 16Gi)
  ephemeral-storagestring
  requestsobject
  2 properties
  cpustring
  CPU request. Minimum 100 millicores (for example, 100m or 0.1).
  memorystring
  Memory request. Minimum 192Mi.
  executorobject | null
  Executor container configuration
  2 properties
  replicasinteger
  Number of executor replicas
  resourcesobject
  Resource requests and limits for the executor container
  2 properties
  limitsobject
  3 properties
  cpustring
  Whole-number vCPU limit, or '-' for no CPU limit
  memorystring
  Memory limit in Gi (for example, 16Gi)
  ephemeral-storagestring
  requestsobject
  2 properties
  cpustring
  CPU request. Minimum 100 millicores (for example, 100m or 0.1).
  memorystring
  Memory request. Minimum 192Mi.
  regionstring | null
  Cloud region code (e.g., us-east-1)
  node_groupstring | null
  Node group for scheduling the project runtime
  storage_claim_size_gbnumber | null
  Storage claim size in GB
400Bad Request
Invalid request body or invalid region
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope, dedicated-cluster assignment or special-org private-compute ceilings required for resource limits, or requested resources exceed dedicated-cluster capacity
409Conflict
A project with this name already exists, or the project was deleted while its initial configuration was being written (code is project_deleted)
429Too Many Requests
Too many project creation requests (rate limited)
500Internal Server Error
Project creation failed, including when the name-collision check could not be read
application/json
- errorstringRequired
  Generic failure reason; the underlying cause stays in the server logs
  - Example: Failed to create project

Get a project

GET/v1/projects/{projectId}

Returns details for a specific project, including its configuration.

Path parameters

Name	Type	Required	Description
`projectId`	integer	Yes	The ID of the project

Header parameters

Name	Type	Required	Description
`Authorization`	string	Yes	`Bearer <token>`. Authentication lists the tokens it accepts.
`X-Org-Name`	string	No	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 portal session token is bound to none, so it must send this header on every route but `GET /v1/orgs` (400 `org_assertion_required` otherwise). Pattern: `^[A-Za-z0-9._-]{1,255}$`

Example request

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

Responses

200OK
Project details with configuration
application/json
- idinteger
- namestring
- kindstring
  Resolved project hosting model
  - Allowed values: managed, standalone, byoc
- descriptionstring
- visibilitystring
  - Allowed values: public, private
- created_atstring (date-time)
- cluster_namestring | null
  Resolved dedicated cluster name; null for projects not assigned to a dedicated cluster.
- endpointstring | null
  The data-plane endpoint the project connects to, or null before a standalone instance is attached.
- production_branchstring
- api_keystringDeprecated
  Deprecated. Use the API Keys endpoints instead.
- tagsmap of string
- forked_fromobject | null
  The project this project was forked from, while that project is live in the same organization. Null for a project that was not created as a fork.
  2 properties
  idintegerRequired
  ID of the source project
  namestringRequired
  Name of the source project
- paused_atstring (date-time) | null
  Timestamp when the project was paused; null while running
- configobject
  10 properties
  spicepodobject
  image_tagstring
  Runtime image tag
  update_channelstring | null
  Update channel for the runtime, or null when Spice operates this project's runtime updates.
  Allowed values: stable, preview, nightly
  versionstring
  Semver range for the runtime version (e.g. 1.x, 2.x)
  replicasinteger
  resourcesobject | null
  Resource requests and limits for the project container
  2 properties
  limitsobject
  3 properties
  cpustring
  Whole-number vCPU limit, or '-' for no CPU limit
  memorystring
  Memory limit in Gi (for example, 16Gi)
  ephemeral-storagestring
  requestsobject
  2 properties
  cpustring
  CPU request. Minimum 100 millicores (for example, 100m or 0.1).
  memorystring
  Memory request. Minimum 192Mi.
  executorobject | null
  Executor container configuration
  3 properties
  replicasinteger
  Number of executor replicas
  resourcesobject
  Resource requests and limits for the executor container
  2 properties
  limitsobject
  3 properties
  cpustring
  Whole-number vCPU limit, or '-' for no CPU limit
  memorystring
  Memory limit in Gi (for example, 16Gi)
  ephemeral-storagestring
  requestsobject
  2 properties
  cpustring
  CPU request. Minimum 100 millicores (for example, 100m or 0.1).
  memorystring
  Memory request. Minimum 192Mi.
  storage_size_gbnumber | null
  regionstring | null
  Server-resolved region; null before a standalone instance is attached.
  storage_size_gbnumber | null
  storage_claim_size_gbnumberDeprecated
  Deprecated. Use storage_size_gb instead.
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope
404Not Found
Project not found
500Internal Server Error
Internal server error

Update a project

PUT/v1/projects/{projectId}

Updates a project's metadata and configuration, including description, visibility, spicepod configuration, replicas, and resource limits.

Path parameters

Name	Type	Required	Description
`projectId`	integer	Yes	The ID of the project

Header parameters

Name	Type	Required	Description
`Authorization`	string	Yes	`Bearer <token>`. Authentication lists the tokens it accepts.
`X-Org-Name`	string	No	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 portal session token is bound to none, so it must send this header on every route but `GET /v1/orgs` (400 `org_assertion_required` otherwise). Pattern: `^[A-Za-z0-9._-]{1,255}$`

Request body

Required

application/json

descriptionstring
visibilitystring
- Allowed values: public, private
production_branchstring
tagsmap of string
Key-value tags for the project. The map replaces the stored tags. System tags the project already has stay on the project when the map omits them.
spicepodstring | object
The project's Spicepod. A project connected to a GitHub repository takes its Spicepod from the repository's spicepod.yaml, so for such a project only the stored Spicepod, sent back unchanged, is accepted.
image_tagstring | null
Runtime image tag for a managed project; rejected for standalone projects. A non-empty value pins the project. On stable, the pin must be a published stable runtime version. On preview, it must be a published preview or stable runtime version. 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_channelstring
Update channel for a managed runtime; rejected for standalone projects.
- Allowed values: stable, preview, nightly
versionstring
Semver range for a managed runtime version (e.g. 1.x, 2.x); rejected for standalone projects.
replicasinteger
Managed runtime replica count; rejected for standalone projects.
- Minimum: 0
resourcesobject
Resource requests and limits for a managed project container; rejected for standalone projects.
2 properties
- limitsobject
  3 properties
  - cpustring
    Whole-number vCPU limit, or '-' for no CPU limit
  - memorystring
    Memory limit in Gi (for example, 16Gi)
  - ephemeral-storagestring
    Ephemeral storage limit in Gi (for example, 8Gi)
- requestsobject
  2 properties
  - cpustring
    CPU request. Minimum 100 millicores (for example, 100m or 0.1).
  - memorystring
    Memory request. Minimum 192Mi.
executorobject
Executor container configuration for a managed project; rejected for standalone projects.
3 properties
- replicasinteger
  Number of executor replicas
  - Minimum: 0
- resourcesobject
  Resource requests and limits for the executor container
  2 properties
  - limitsobject
    3 properties
    cpustring
    Whole-number vCPU limit, or '-' for no CPU limit
    memorystring
    Memory limit in Gi (for example, 16Gi)
    ephemeral-storagestring
    Ephemeral storage limit in Gi (for example, 8Gi)
  - requestsobject
    2 properties
    cpustring
    CPU request. Minimum 100 millicores (for example, 100m or 0.1).
    memorystring
    Memory request. Minimum 192Mi.
- storage_size_gbnumber
regionstring
Managed project region; standalone placement is resolved during attachment.
cluster_namestring
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.
storage_size_gbnumber
Managed runtime storage size; rejected for standalone projects.
storage_claim_size_gbnumberDeprecated
Deprecated. Use storage_size_gb instead. Rejected for standalone projects.

Example request

curl -X PUT "https://api.spice.ai/v1/projects/<projectId>" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "string",
    "visibility": "public",
    "production_branch": "string",
    "tags": {},
    "spicepod": "string",
    "image_tag": "string",
    "update_channel": "stable",
    "version": "string",
    "replicas": 0,
    "resources": {},
    "executor": {},
    "region": "string",
    "cluster_name": "string",
    "storage_size_gb": 0,
    "storage_claim_size_gb": 0
  }'

Responses

200OK
Project updated successfully
application/json
- idinteger
  Unique identifier for the project
- namestring
  Name of the project
- kindstring
  Resolved project hosting model
  - Allowed values: managed, standalone, byoc
- descriptionstring | null
  Description of the project
- visibilitystring
  Visibility setting for the project
  - Allowed values: public, private
- created_atstring (date-time)
  Timestamp when the project was created
- cnamestring | null
  Region identifier
- cluster_namestring | null
  Resolved dedicated cluster name; null for projects not assigned to a dedicated cluster.
- endpointstring | null
  The data-plane endpoint the project connects to, or null before a standalone instance is attached.
- production_branchstring | null
  Production branch for the project
- api_keystringDeprecated
  Deprecated. Use the API Keys endpoints instead.
- tagsmap of string | null
  Key-value tags for the project
- forked_fromobject | null
  The project this project was forked from, while that project is live in the same organization. Null for a project that was not created as a fork.
  2 properties
  idintegerRequired
  ID of the source project
  namestringRequired
  Name of the source project
- paused_atstring (date-time) | null
  Timestamp when the project was paused; null while running
- warningstring | null
  Present when the project was created but initial configuration could not be applied
- configobject | null
  Runtime configuration; null for an unattached standalone project.
  10 properties
  spicepodobject | null
  Spicepod configuration
  registrystring | null
  Container registry for the runtime image
  image_tagstring | null
  Runtime image tag
  update_channelstring | null
  Update channel for the runtime
  Allowed values: stable, preview, nightly
  replicasinteger
  Number of replicas
  resourcesobject | null
  Resource requests and limits for the project container
  2 properties
  limitsobject
  3 properties
  cpustring
  Whole-number vCPU limit, or '-' for no CPU limit
  memorystring
  Memory limit in Gi (for example, 16Gi)
  ephemeral-storagestring
  requestsobject
  2 properties
  cpustring
  CPU request. Minimum 100 millicores (for example, 100m or 0.1).
  memorystring
  Memory request. Minimum 192Mi.
  executorobject | null
  Executor container configuration
  2 properties
  replicasinteger
  Number of executor replicas
  resourcesobject
  Resource requests and limits for the executor container
  2 properties
  limitsobject
  3 properties
  cpustring
  Whole-number vCPU limit, or '-' for no CPU limit
  memorystring
  Memory limit in Gi (for example, 16Gi)
  ephemeral-storagestring
  requestsobject
  2 properties
  cpustring
  CPU request. Minimum 100 millicores (for example, 100m or 0.1).
  memorystring
  Memory request. Minimum 192Mi.
  regionstring | null
  Cloud region code (e.g., us-east-1)
  node_groupstring | null
  Node group for scheduling the project runtime
  storage_claim_size_gbnumber | null
  Storage claim size in GB
400Bad Request
Invalid request body or project ID, including placement or hosted runtime fields that do not apply to standalone projects. When image_tag is supplied on stable or preview, a tag that is not a published version for that channel returns { error: 'Invalid image_tag for stable channel', code: 'invalid_stable_image_tag' } (or the preview analog). A spicepod that adds a component on a source the Spice runtime no longer loads returns code retired_component_source; components the project already stores on such a source may be kept, edited and renamed, and a project backed by a GitHub repository is not checked.
401Unauthorized
Unauthorized
403Forbidden
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
404Not Found
Project not found
409Conflict
The project's lifecycle state changed while the update was in flight — a pause, resume or restore landing concurrently — so the configuration was not saved (code: project_state_changed). Re-read the project before retrying: a configuration update clears paused_at, so repeating this request against a project that has since been paused also resumes it. Or a spicepod that differs from the stored one was sent for a project connected to a GitHub repository (code: github_connected); change spicepod.yaml in the repository instead, since nothing in that request is applied.
500Internal Server Error
Internal server error
502Bad Gateway
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.
503Service Unavailable
Runtime version catalog is unavailable

Delete a project

DELETE/v1/projects/{projectId}

Deletes a project and tears down its runtime resources.

Path parameters

Name	Type	Required	Description
`projectId`	integer	Yes	The ID of the project to delete

Header parameters

Name	Type	Required	Description
`Authorization`	string	Yes	`Bearer <token>`. Authentication lists the tokens it accepts.
`X-Org-Name`	string	No	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 portal session token is bound to none, so it must send this header on every route but `GET /v1/orgs` (400 `org_assertion_required` otherwise). Pattern: `^[A-Za-z0-9._-]{1,255}$`

Example request

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

Responses

204No Content
Project deleted successfully
400Bad Request
Invalid project ID
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope or viewer role cannot mutate projects
404Not Found
Project not found
500Internal Server Error
Internal server error

List forks of a project

GET/v1/projects/{projectId}/forks

Returns the live projects in the organization that were forked from this project, ordered by name. Requires apps:read.

Path parameters

Name	Type	Required	Description
`projectId`	integer	Yes	The ID of the source project

Header parameters

Name	Type	Required	Description
`Authorization`	string	Yes	`Bearer <token>`. Authentication lists the tokens it accepts.
`X-Org-Name`	string	No	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 portal session token is bound to none, so it must send this header on every route but `GET /v1/orgs` (400 `org_assertion_required` otherwise). Pattern: `^[A-Za-z0-9._-]{1,255}$`

Example request

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

Responses

200OK
Forks of the project
application/json
- forksarray of objectRequired
  10 properties
  idinteger
  Unique identifier for the project
  namestring
  Name of the project
  kindstring
  Resolved project hosting model
  Allowed values: managed, standalone, byoc
  descriptionstring | null
  Description of the project
  visibilitystring
  Visibility setting for the project
  Allowed values: public, private
  created_atstring (date-time)
  Timestamp when the project was created
  cnamestring | null
  Region identifier
  cluster_namestring | null
  Resolved dedicated cluster name; null for projects not assigned to a dedicated cluster.
  endpointstring | null
  The data-plane endpoint the project connects to, or null before a standalone instance is attached.
  tagsmap of string | null
  Key-value tags for the project
400Bad Request
Invalid project ID
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope
404Not Found
Project not found
500Internal Server Error
Internal server error

Fork a project

POST/v1/projects/{projectId}/forks

Creates a new project from this project's configuration and records this project as its source. The fork copies the spicepod the project deploys, its linked connections, project secrets, linked organization secrets, update channel, version range, replica and executor counts, storage size, description, and tags. It does not copy API keys (new ones are generated), deployments, the GitHub repository link, the instance size, or visibility (forks are private). The fork is not deployed: deploy it with POST /v1/projects/{projectId}/deployments. Requires apps:write. The server copies secret values without returning them, so no secrets scope is needed. A source connected to a GitHub repository is read from that repository, and its spicepod is copied only when it loads no other file from the repository; to deploy a fork from a fork of the repository, fork the project in the Spice portal.

Path parameters

Name	Type	Required	Description
`projectId`	integer	Yes	The ID of the project to fork

Header parameters

Name	Type	Required	Description
`Authorization`	string	Yes	`Bearer <token>`. Authentication lists the tokens it accepts.
`X-Org-Name`	string	No	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 portal session token is bound to none, so it must send this header on every route but `GET /v1/orgs` (400 `org_assertion_required` otherwise). Pattern: `^[A-Za-z0-9._-]{1,255}$`

Request body

Optional

application/json

namestring
Name of the fork. Defaults to the source name with -fork, then -fork-2 and so on, whichever is free.
- Minimum length: 4
- Maximum length: 38
- Pattern: ^[a-zA-Z0-9-]+$
regionstring
Region to place the fork in. Omit it and cluster_name to place the fork where the source runs.
- Allowed values: us-east-1, us-west-2
cluster_namestring
Dedicated cluster to place the fork on, as listed by GET /v1/clusters. If region is also set, it must match the cluster's region.
scheduler_state_locationstring
s3:// URI for the fork's scheduler state. Required when the source spicepod sets runtime.scheduler.state_location, and must not overlap it: two schedulers cannot share a location.
- Maximum length: 2048
default_alertsboolean
Create default monitoring alerts for the new managed fork. False skips initial setup. Manual alert creation remains available.
- Default: true

Example request

curl -X POST "https://api.spice.ai/v1/projects/<projectId>/forks" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "region": "us-east-1",
    "cluster_name": "string",
    "scheduler_state_location": "string",
    "default_alerts": true
  }'

Responses

201Created
Project forked. It has not been deployed yet.
application/json
- idinteger
  Unique identifier for the project
- namestring
  Name of the project
- kindstring
  Resolved project hosting model
  - Allowed values: managed, standalone, byoc
- descriptionstring | null
  Description of the project
- visibilitystring
  Visibility setting for the project
  - Allowed values: public, private
- created_atstring (date-time)
  Timestamp when the project was created
- cnamestring | null
  Region identifier
- cluster_namestring | null
  Resolved dedicated cluster name; null for projects not assigned to a dedicated cluster.
- endpointstring | null
  The data-plane endpoint the project connects to, or null before a standalone instance is attached.
- production_branchstring | null
  Production branch for the project
- api_keystringDeprecated
  Deprecated. Use the API Keys endpoints instead.
- tagsmap of string | null
  Key-value tags for the project
- forked_fromobject | null
  The project this project was forked from, while that project is live in the same organization. Null for a project that was not created as a fork.
  2 properties
  idintegerRequired
  ID of the source project
  namestringRequired
  Name of the source project
- paused_atstring (date-time) | null
  Timestamp when the project was paused; null while running
- warningstring | null
  Present when the project was created but initial configuration could not be applied
- configobject | null
  Runtime configuration; null for an unattached standalone project.
  10 properties
  spicepodobject | null
  Spicepod configuration
  registrystring | null
  Container registry for the runtime image
  image_tagstring | null
  Runtime image tag
  update_channelstring | null
  Update channel for the runtime
  Allowed values: stable, preview, nightly
  replicasinteger
  Number of replicas
  resourcesobject | null
  Resource requests and limits for the project container
  2 properties
  limitsobject
  3 properties
  cpustring
  Whole-number vCPU limit, or '-' for no CPU limit
  memorystring
  Memory limit in Gi (for example, 16Gi)
  ephemeral-storagestring
  requestsobject
  2 properties
  cpustring
  CPU request. Minimum 100 millicores (for example, 100m or 0.1).
  memorystring
  Memory request. Minimum 192Mi.
  executorobject | null
  Executor container configuration
  2 properties
  replicasinteger
  Number of executor replicas
  resourcesobject
  Resource requests and limits for the executor container
  2 properties
  limitsobject
  3 properties
  cpustring
  Whole-number vCPU limit, or '-' for no CPU limit
  memorystring
  Memory limit in Gi (for example, 16Gi)
  ephemeral-storagestring
  requestsobject
  2 properties
  cpustring
  CPU request. Minimum 100 millicores (for example, 100m or 0.1).
  memorystring
  Memory request. Minimum 192Mi.
  regionstring | null
  Cloud region code (e.g., us-east-1)
  node_groupstring | null
  Node group for scheduling the project runtime
  storage_claim_size_gbnumber | null
  Storage claim size in GB
- shared_statearray of objectRequired
  Settings copied as they are that name external state the source also uses: a replication slot or Kafka consumer group the spicepod names, or a snapshot location. Change them in the fork's spicepod before deploying it if the two projects should not share that state.
  3 properties
  componentstringRequired
  The dataset, or snapshots
  settingstringRequired
  Example: pg_replication_slot
  valuestringRequired
400Bad Request
Invalid project ID or request body, an unknown region or cluster, no region or cluster_name set for a source whose placement a fork cannot reuse (a BYOC cluster, a self-hosted runtime, or a region or cluster that is no longer available; code: fork_placement_required), or a missing or unusable scheduler_state_location (code: scheduler_state_location_required, scheduler_state_location_unsupported, scheduler_state_location_overlaps_source, or scheduler_state_location_not_applicable).
401Unauthorized
Unauthorized
402Payment Required
The source runs models on hosted AI credits, which the organization has used up (code: ai_credits_exhausted).
403Forbidden
Insufficient scope, a viewer role, or the source runs more replicas or executors than the plan or the dedicated cluster allows
404Not Found
Project or organization not found
409Conflict
A project with the requested name already exists, another project creation is in progress, or every default name is taken (code: fork_name_unavailable)
413Content Too Large
Request body too large
422Unprocessable Content
The source has no spicepod (code: fork_source_has_no_spicepod), its spicepod is not valid (code: fork_source_spicepod_invalid), or its spicepod loads files from its GitHub repository besides spicepod.yaml (code: fork_source_loads_repository_files)
429Too Many Requests
Too many project creation requests (rate limited)
500Internal Server Error
The fork could not be created. When the failure comes after the project row is created, the fork is deleted again with its spicepod, secrets, and organization secret links. If the project itself cannot be deleted, the response has code: fork_rollback_failed and names the partially created project in project (id and name). Delete that project, by project.id, before reusing its name.
502Bad Gateway
The source is connected to a GitHub repository, and its spicepod could not be read from it (code: fork_source_repository_unreadable)

Pause a project

POST/v1/projects/{projectId}/pause

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.

Path parameters

Name	Type	Required	Description
`projectId`	integer	Yes	The ID of the project to pause

Header parameters

Name	Type	Required	Description
`Authorization`	string	Yes	`Bearer <token>`. Authentication lists the tokens it accepts.
`X-Org-Name`	string	No	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 portal session token is bound to none, so it must send this header on every route but `GET /v1/orgs` (400 `org_assertion_required` otherwise). Pattern: `^[A-Za-z0-9._-]{1,255}$`

Example request

curl -X POST "https://api.spice.ai/v1/projects/<projectId>/pause" \
  -H "Authorization: Bearer <token>"

Responses

200OK
Project paused
application/json
- idintegerRequired
  The project ID
- namestringRequired
  The project name
- paused_atstring (date-time)Required
  Timestamp when the project was paused
400Bad Request
Invalid project ID, missing API key, no spicepod configured, or spicepod has been deleted
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope
404Not Found
Project not found
409Conflict
Project is already paused
application/json
- errorstringRequired
- paused_atstring (date-time)Required
  Timestamp of the existing pause
500Internal Server Error
Internal server error

Resume a paused project

POST/v1/projects/{projectId}/resume

Clears the paused state on the project's spicepod and creates a new deployment to bring the runtime back up. A project connected to a GitHub repository deploys spicepod.yaml from its root directory on its production branch, read when the project resumes. Requires apps:write.

Path parameters

Name	Type	Required	Description
`projectId`	integer	Yes	The ID of the project to resume

Header parameters

Name	Type	Required	Description
`Authorization`	string	Yes	`Bearer <token>`. Authentication lists the tokens it accepts.
`X-Org-Name`	string	No	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 portal session token is bound to none, so it must send this header on every route but `GET /v1/orgs` (400 `org_assertion_required` otherwise). Pattern: `^[A-Za-z0-9._-]{1,255}$`

Example request

curl -X POST "https://api.spice.ai/v1/projects/<projectId>/resume" \
  -H "Authorization: Bearer <token>"

Responses

200OK
Project resumed, deployment created
application/json
- idintegerRequired
  The project ID
- namestringRequired
  The project name
- paused_atstring (date-time) | nullRequired
  Always null after a successful resume
- deployment_idintegerRequired
  ID of the deployment created to bring the runtime back up
400Bad Request
Invalid project ID, missing API key, missing project organization, no spicepod configured, spicepod has been deleted, or the spicepod name, kind or version is missing or not valid (the body carries an issues array of {path, message}). For a project connected to a GitHub repository, also returned when the root directory has no spicepod.yaml or it is invalid or too large (code: spicepod_not_found, spicepod_invalid or spicepod_too_large). The project stays paused.
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope, or the org's GitHub App installation cannot read the connected repository (code: github_unauthorized or github_forbidden). The project stays paused.
404Not Found
Project not found, or the connected GitHub repository or its production branch was not found (code: github_not_found). The project stays paused.
409Conflict
Project is not paused
422Unprocessable Content
No runtime version in the catalog matches this project’s version range (code: version_no_match), or the spicepod uses version v1beta1, which the Spice 2 runtime cannot load (code: spicepod_version_unsupported). Also returned when the spicepod uses a connection credential that holds a secret reference deploy cannot resolve (code: connection_credentials_unresolved, with an unresolved_credentials array of {connection, field}). The project stays paused.
429Too Many Requests
GitHub rate-limited the read of the connected repository (code: github_rate_limited). The project stays paused.
500Internal Server Error
Internal server error
502Bad Gateway
GitHub did not answer while the connected repository was read (code: github_unavailable). The project stays paused.
503Service Unavailable
The runtime version catalog is unavailable or empty (code: version_source_unavailable), so an unpinned stable or preview resume cannot resolve an image tag.

Connect a project to a GitHub repository

PUT/v1/projects/{projectId}/repository

Connects the project to a repository in the organization's GitHub account, through the organization's Spice Cloud GitHub App installation. The next deployment reads spicepod.yaml (or spicepod.yml) from root_directory on production_branch. Connecting sets the project description to the repository description. Connecting again replaces the repository, root directory and production branch. Requires apps:write.

Path parameters

Name	Type	Required	Description
`projectId`	integer	Yes	The ID of the project to connect

Header parameters

Name	Type	Required	Description
`Authorization`	string	Yes	`Bearer <token>`. Authentication lists the tokens it accepts.
`X-Org-Name`	string	No	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 portal session token is bound to none, so it must send this header on every route but `GET /v1/orgs` (400 `org_assertion_required` otherwise). Pattern: `^[A-Za-z0-9._-]{1,255}$`

Request body

Required

application/json

repositorystringRequired
Repository in the organization's GitHub account, as name or owner/name. The owner must be the organization's GitHub account.
- Example: cookbook
root_directorystring | null
Directory inside the repository that contains spicepod.yaml. Omit it, or send null or an empty string, for the repository root.
- Maximum length: 512
- Example: cayenne
production_branchstring
Branch that deployments read. Defaults to the repository's default branch. A branch that GitHub renamed is stored under its new name.
- Maximum length: 255
- Example: trunk

Example request

curl -X PUT "https://api.spice.ai/v1/projects/<projectId>/repository" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "repository": "cookbook"
  }'

Responses

200OK
Project connected
application/json
- project_idintegerRequired
  The project ID
- repositorystringRequired
  The repository as owner/name
- repository_idintegerRequired
  The GitHub repository ID
- root_directorystring | nullRequired
  The stored root directory. Null is the repository root.
- production_branchstringRequired
  The branch that deployments read
- connected_atstring (date-time)Required
  When the project was connected
- has_spicepodbooleanRequired
  True when spicepod.yaml or spicepod.yml exists in the root directory on the production branch. A deployment fails until it does.
400Bad Request
Invalid project ID or request body, a repository outside the organization's GitHub account (code: invalid_repository), or a root directory outside the repository (code: invalid_root_directory)
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope, or viewer role cannot mutate projects
404Not Found
Project not found, or the organization's GitHub App installation cannot read the repository (code: repository_not_found)
409Conflict
The organization has no usable GitHub App installation (code: github_not_connected), or another project already deploys this repository and root directory (code: root_directory_conflict)
413Content Too Large
Request body too large
422Unprocessable Content
The repository has no branch named production_branch (code: branch_not_found), the project has no spicepod configuration (code: spicepod_missing), or the organization is not fully configured
500Internal Server Error
Internal server error
503Service Unavailable
GitHub did not answer (code: github_unavailable)

Get project metrics

GET/v1/projects/{projectId}/metrics

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

Path parameters

Name	Type	Required	Description
`projectId`	integer	Yes	The ID of the project

Query parameters

Name	Type	Required	Description
`window`	string	No	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.

Header parameters

Name	Type	Required	Description
`Authorization`	string	Yes	`Bearer <token>`. Authentication lists the tokens it accepts.
`X-Org-Name`	string	No	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 portal session token is bound to none, so it must send this header on every route but `GET /v1/orgs` (400 `org_assertion_required` otherwise). Pattern: `^[A-Za-z0-9._-]{1,255}$`

Example request

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

Responses

200OK
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
- ingestionobject
  Aggregated data ingestion metrics
  2 properties
  rows_ingestednumber
  Total rows ingested (without window) or rows per second (with window)
  bytes_ingestednumber
  Total bytes ingested (without window) or bytes per second (with window)
- clusterobject
  Cluster metrics for the project
  1 property
  active_executors_countnumber
  Number of active executors registered with the scheduler
- metricsmap of object
  Resource metrics keyed by pod name
  6 properties
  cpu_usage_percentnumber
  CPU usage as a percentage (0-100)
  memory_usage_bytesnumber
  Memory usage in bytes
  disk_read_bytesnumber
  Disk bytes read per second (with window) or cumulative (without window)
  disk_read_operationsnumber
  Disk read operations per second (with window) or cumulative count (without window)
  disk_write_bytesnumber
  Disk bytes written per second (with window) or cumulative (without window)
  disk_write_operationsnumber
  Disk write operations per second (with window) or cumulative count (without window)
400Bad Request
Invalid project ID
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope
404Not Found
Project or organization not found
422Unprocessable Content
Organization is not fully configured
500Internal Server Error
Internal server error
503Service Unavailable
Metrics service unavailable

List project instances

GET/v1/projects/{projectId}/instances

Lists the runtime instances of a deployed project, newest first. A managed or BYOC project lists its Spicepod instances. A standalone project lists its Cloud Connect runtime. Read the logs of an instance with GET /v1/projects/{projectId}/instances/{instanceName}/logs.

Path parameters

Name	Type	Required	Description
`projectId`	integer	Yes	The ID of the project

Header parameters

Name	Type	Required	Description
`Authorization`	string	Yes	`Bearer <token>`. Authentication lists the tokens it accepts.
`X-Org-Name`	string	No	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 portal session token is bound to none, so it must send this header on every route but `GET /v1/orgs` (400 `org_assertion_required` otherwise). Pattern: `^[A-Za-z0-9._-]{1,255}$`

Example request

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

Responses

200OK
The project's instances
application/json
- instancesarray of objectRequired
  3 properties
  namestringRequired
  The instance name: a Spicepod instance (pod) name, or a Cloud Connect runtime id. Pass it as instanceName to read its logs.
  statusstringRequired
  A Spicepod instance is deploying, loading, ready, unhealthy, terminating, failed, or failed_to_start. A Cloud Connect runtime is online or offline.
  Allowed values: deploying, loading, ready, unhealthy, terminating, failed, failed_to_start, online, offline
  started_atstring (date-time) | nullRequired
  When the Spicepod instance started, or when the Cloud Connect runtime enrolled.
400Bad Request
Invalid project ID
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope
404Not Found
Project not found
409Conflict
The project has no running instances. code is project_not_deployed when a managed or BYOC project was never deployed, or project_paused when the project is paused.
application/json
- errorstringRequired
- codestringRequired
  - Allowed values: project_not_deployed, project_paused
422Unprocessable Content
The project is not fully configured
500Internal Server Error
Internal server error
503Service Unavailable
The project runtime did not answer

Get project instance logs

GET/v1/projects/{projectId}/instances/{instanceName}/logs

Returns the most recent log lines of one instance of a deployed project, oldest first, without color codes. The org's plan sets the largest tail. List the instance names with GET /v1/projects/{projectId}/instances.

Path parameters

Name	Type	Required	Description
`projectId`	integer	Yes	The ID of the project
`instanceName`	string	Yes	The instance name from `GET /v1/projects/{projectId}/instances`

Query parameters

Name	Type	Required	Description
`tail`	integer	No	How many of the most recent lines to return Default: `100` Minimum: `1`

Header parameters

Name	Type	Required	Description
`Authorization`	string	Yes	`Bearer <token>`. Authentication lists the tokens it accepts.
`X-Org-Name`	string	No	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 portal session token is bound to none, so it must send this header on every route but `GET /v1/orgs` (400 `org_assertion_required` otherwise). Pattern: `^[A-Za-z0-9._-]{1,255}$`

Example request

curl "https://api.spice.ai/v1/projects/<projectId>/instances/<instanceName>/logs" \
  -H "Authorization: Bearer <token>"

Responses

200OK
The instance's most recent log lines
application/json
- instancestringRequired
  The instance name
- tailintegerRequired
  The number of lines asked for
- linesarray of stringRequired
  Log lines, oldest first
400Bad Request
Invalid project ID or tail
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope (code is insufficient_scope), or tail is larger than the org's plan allows (code is plan_limit, and max_tail is the largest allowed tail).
application/json
- errorstringRequired
- codestringRequired
- max_tailinteger
404Not Found
The project was not found, or the instance is not one of the project's instances (code is instance_not_found).
409Conflict
The logs cannot be read in the project's current state. code is project_not_deployed when the project was never deployed, project_paused when it is paused, or instance_offline when the Cloud Connect runtime is offline and does not answer.
application/json
- errorstringRequired
- codestringRequired
  - Allowed values: project_not_deployed, project_paused, instance_offline
422Unprocessable Content
The project is not fully configured
500Internal Server Error
Internal server error
503Service Unavailable
The project runtime did not answer

List projects

GET/v1/orgs/{orgId}/projects

The org is orgId in the path. Returns projects belonging to the authenticated organization. Page with limit (default 1000, max 1000). Prefer after_id for a stable keyset (descending id). offset is accepted for compatibility. PostgREST also caps a page at 1000 rows.

Path parameters

Name	Type	Required	Description
`orgId`	integer	Yes	The org id from GET /v1/orgs Minimum: `1`

Query parameters

Name	Type	Required	Description
`limit`	integer	No	Maximum number of projects to return Default: `1000` Minimum: `1` Maximum: `1000`
`offset`	integer	No	Number of projects to skip when a cursor is not supplied Default: `0` Minimum: `0`
`after_id`	integer	No	Return projects with a strictly smaller id than this value. Minimum: `1`

Header parameters

Name	Type	Required	Description
`Authorization`	string	Yes	`Bearer <token>`. Authentication lists the tokens it accepts.
`X-Org-Name`	string	No	When present, X-Org-Name must name the same org as orgId. Otherwise the request returns org_path_mismatch (400). Pattern: `^[A-Za-z0-9._-]{1,255}$`

Example request

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

Responses

200OK
List of projects
application/json
- projectsarray of object
  10 properties
  idinteger
  Unique identifier for the project
  namestring
  Name of the project
  kindstring
  Resolved project hosting model
  Allowed values: managed, standalone, byoc
  descriptionstring | null
  Description of the project
  visibilitystring
  Visibility setting for the project
  Allowed values: public, private
  created_atstring (date-time)
  Timestamp when the project was created
  cnamestring | null
  Region identifier
  cluster_namestring | null
  Resolved dedicated cluster name; null for projects not assigned to a dedicated cluster.
  endpointstring | null
  The data-plane endpoint the project connects to, or null before a standalone instance is attached.
  tagsmap of string | null
  Key-value tags for the project
400Bad Request
Invalid limit, offset, or after_id. orgId is not a valid org id (invalid_org_id), or X-Org-Name does not name that org (org_path_mismatch).
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope. The caller is not a member of the org (org_forbidden). A machine credential named a different org (org_assertion_mismatch). The org is deleted (org_deleted).

Create a project

POST/v1/orgs/{orgId}/projects

The org is orgId in the path. Creates a new project in the authenticated organization.

Path parameters

Name	Type	Required	Description
`orgId`	integer	Yes	The org id from GET /v1/orgs Minimum: `1`

Header parameters

Name	Type	Required	Description
`Authorization`	string	Yes	`Bearer <token>`. Authentication lists the tokens it accepts.
`X-Org-Name`	string	No	When present, X-Org-Name must name the same org as orgId. Otherwise the request returns org_path_mismatch (400). Pattern: `^[A-Za-z0-9._-]{1,255}$`

Request body

Required

application/json

namestringRequired
Project name (letters, numbers, hyphens only)
- Minimum length: 4
- Pattern: ^[a-zA-Z0-9-]+$
regionstring
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.
- Allowed values: us-east-1, us-west-2
cnamestring
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.
cluster_namestring
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.
descriptionstring
Project description
visibilitystring
- Allowed values: public, private
- Default: private
default_alertsboolean
Create default monitoring alerts for the new managed project. False skips initial setup. Manual alert creation remains available.
- Default: true
tagsmap of string
Key-value tags for the project
update_channelstring
Update channel for a managed project deployment. A standalone project has no spicepod until linking, so configure its channel after linking.
- Allowed values: stable, preview, nightly
replicasinteger
Number of replicas for a managed project. Rejected for standalone projects.
- Minimum: 0
resourcesobject
Resource requests and limits for a managed project container. Rejected for standalone projects.
2 properties
- limitsobject
  3 properties
  - cpustring
    Whole-number vCPU limit, or '-' for no CPU limit
  - memorystring
    Memory limit in Gi (for example, 16Gi)
  - ephemeral-storagestring
    Ephemeral storage limit in Gi (for example, 8Gi)
- requestsobject
  2 properties
  - cpustring
    CPU request. Minimum 100 millicores (for example, 100m or 0.1).
  - memorystring
    Memory request. Minimum 192Mi.
executorobject
Executor container configuration for a managed project. Rejected for standalone projects.
2 properties
- replicasinteger
  Number of executor replicas
  - Minimum: 0
- resourcesobject
  Resource requests and limits for the executor container
  2 properties
  - limitsobject
    3 properties
    cpustring
    Whole-number vCPU limit, or '-' for no CPU limit
    memorystring
    Memory limit in Gi (for example, 16Gi)
    ephemeral-storagestring
    Ephemeral storage limit in Gi (for example, 8Gi)
  - requestsobject
    2 properties
    cpustring
    CPU request. Minimum 100 millicores (for example, 100m or 0.1).
    memorystring
    Memory request. Minimum 192Mi.

Example request

curl -X POST "https://api.spice.ai/v1/orgs/<orgId>/projects" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string"
  }'

Responses

201Created
Project created successfully. The response may include a warning field if initial configuration could not be applied.
application/json
- idinteger
  Unique identifier for the project
- namestring
  Name of the project
- kindstring
  Resolved project hosting model
  - Allowed values: managed, standalone, byoc
- descriptionstring | null
  Description of the project
- visibilitystring
  Visibility setting for the project
  - Allowed values: public, private
- created_atstring (date-time)
  Timestamp when the project was created
- cnamestring | null
  Region identifier
- cluster_namestring | null
  Resolved dedicated cluster name; null for projects not assigned to a dedicated cluster.
- endpointstring | null
  The data-plane endpoint the project connects to, or null before a standalone instance is attached.
- production_branchstring | null
  Production branch for the project
- api_keystringDeprecated
  Deprecated. Use the API Keys endpoints instead.
- tagsmap of string | null
  Key-value tags for the project
- forked_fromobject | null
  The project this project was forked from, while that project is live in the same organization. Null for a project that was not created as a fork.
  2 properties
  idintegerRequired
  ID of the source project
  namestringRequired
  Name of the source project
- paused_atstring (date-time) | null
  Timestamp when the project was paused; null while running
- warningstring | null
  Present when the project was created but initial configuration could not be applied
- configobject | null
  Runtime configuration; null for an unattached standalone project.
  10 properties
  spicepodobject | null
  Spicepod configuration
  registrystring | null
  Container registry for the runtime image
  image_tagstring | null
  Runtime image tag
  update_channelstring | null
  Update channel for the runtime
  Allowed values: stable, preview, nightly
  replicasinteger
  Number of replicas
  resourcesobject | null
  Resource requests and limits for the project container
  2 properties
  limitsobject
  3 properties
  cpustring
  Whole-number vCPU limit, or '-' for no CPU limit
  memorystring
  Memory limit in Gi (for example, 16Gi)
  ephemeral-storagestring
  requestsobject
  2 properties
  cpustring
  CPU request. Minimum 100 millicores (for example, 100m or 0.1).
  memorystring
  Memory request. Minimum 192Mi.
  executorobject | null
  Executor container configuration
  2 properties
  replicasinteger
  Number of executor replicas
  resourcesobject
  Resource requests and limits for the executor container
  2 properties
  limitsobject
  3 properties
  cpustring
  Whole-number vCPU limit, or '-' for no CPU limit
  memorystring
  Memory limit in Gi (for example, 16Gi)
  ephemeral-storagestring
  requestsobject
  2 properties
  cpustring
  CPU request. Minimum 100 millicores (for example, 100m or 0.1).
  memorystring
  Memory request. Minimum 192Mi.
  regionstring | null
  Cloud region code (e.g., us-east-1)
  node_groupstring | null
  Node group for scheduling the project runtime
  storage_claim_size_gbnumber | null
  Storage claim size in GB
400Bad Request
Invalid request body or invalid region. orgId is not a valid org id (invalid_org_id), or X-Org-Name does not name that org (org_path_mismatch).
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope, dedicated-cluster assignment or special-org private-compute ceilings required for resource limits, or requested resources exceed dedicated-cluster capacity. The caller is not a member of the org (org_forbidden). A machine credential named a different org (org_assertion_mismatch). The org is deleted (org_deleted).
409Conflict
A project with this name already exists, or the project was deleted while its initial configuration was being written (code is project_deleted)
429Too Many Requests
Too many project creation requests (rate limited)
500Internal Server Error
Project creation failed, including when the name-collision check could not be read
application/json
- errorstringRequired
  Generic failure reason; the underlying cause stays in the server logs
  - Example: Failed to create project

Get a project

GET/v1/orgs/{orgId}/projects/{projectId}

The org is orgId in the path. Returns details for a specific project, including its configuration.

Path parameters

Name	Type	Required	Description
`orgId`	integer	Yes	The org id from GET /v1/orgs Minimum: `1`
`projectId`	integer	Yes	The ID of the project

Header parameters

Name	Type	Required	Description
`Authorization`	string	Yes	`Bearer <token>`. Authentication lists the tokens it accepts.
`X-Org-Name`	string	No	When present, X-Org-Name must name the same org as orgId. Otherwise the request returns org_path_mismatch (400). Pattern: `^[A-Za-z0-9._-]{1,255}$`

Example request

curl "https://api.spice.ai/v1/orgs/<orgId>/projects/<projectId>" \
  -H "Authorization: Bearer <token>"

Responses

200OK
Project details with configuration
application/json
- idinteger
- namestring
- kindstring
  Resolved project hosting model
  - Allowed values: managed, standalone, byoc
- descriptionstring
- visibilitystring
  - Allowed values: public, private
- created_atstring (date-time)
- cluster_namestring | null
  Resolved dedicated cluster name; null for projects not assigned to a dedicated cluster.
- endpointstring | null
  The data-plane endpoint the project connects to, or null before a standalone instance is attached.
- production_branchstring
- api_keystringDeprecated
  Deprecated. Use the API Keys endpoints instead.
- tagsmap of string
- forked_fromobject | null
  The project this project was forked from, while that project is live in the same organization. Null for a project that was not created as a fork.
  2 properties
  idintegerRequired
  ID of the source project
  namestringRequired
  Name of the source project
- paused_atstring (date-time) | null
  Timestamp when the project was paused; null while running
- configobject
  10 properties
  spicepodobject
  image_tagstring
  Runtime image tag
  update_channelstring | null
  Update channel for the runtime, or null when Spice operates this project's runtime updates.
  Allowed values: stable, preview, nightly
  versionstring
  Semver range for the runtime version (e.g. 1.x, 2.x)
  replicasinteger
  resourcesobject | null
  Resource requests and limits for the project container
  2 properties
  limitsobject
  3 properties
  cpustring
  Whole-number vCPU limit, or '-' for no CPU limit
  memorystring
  Memory limit in Gi (for example, 16Gi)
  ephemeral-storagestring
  requestsobject
  2 properties
  cpustring
  CPU request. Minimum 100 millicores (for example, 100m or 0.1).
  memorystring
  Memory request. Minimum 192Mi.
  executorobject | null
  Executor container configuration
  3 properties
  replicasinteger
  Number of executor replicas
  resourcesobject
  Resource requests and limits for the executor container
  2 properties
  limitsobject
  3 properties
  cpustring
  Whole-number vCPU limit, or '-' for no CPU limit
  memorystring
  Memory limit in Gi (for example, 16Gi)
  ephemeral-storagestring
  requestsobject
  2 properties
  cpustring
  CPU request. Minimum 100 millicores (for example, 100m or 0.1).
  memorystring
  Memory request. Minimum 192Mi.
  storage_size_gbnumber | null
  regionstring | null
  Server-resolved region; null before a standalone instance is attached.
  storage_size_gbnumber | null
  storage_claim_size_gbnumberDeprecated
  Deprecated. Use storage_size_gb instead.
400Bad Request
orgId is not a valid org id (invalid_org_id), or X-Org-Name does not name that org (org_path_mismatch).
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope. The caller is not a member of the org (org_forbidden). A machine credential named a different org (org_assertion_mismatch). The org is deleted (org_deleted).
404Not Found
Project not found
500Internal Server Error
Internal server error

Update a project

PUT/v1/orgs/{orgId}/projects/{projectId}

The org is orgId in the path. Updates a project's metadata and configuration, including description, visibility, spicepod configuration, replicas, and resource limits.

Path parameters

Name	Type	Required	Description
`orgId`	integer	Yes	The org id from GET /v1/orgs Minimum: `1`
`projectId`	integer	Yes	The ID of the project

Header parameters

Name	Type	Required	Description
`Authorization`	string	Yes	`Bearer <token>`. Authentication lists the tokens it accepts.
`X-Org-Name`	string	No	When present, X-Org-Name must name the same org as orgId. Otherwise the request returns org_path_mismatch (400). Pattern: `^[A-Za-z0-9._-]{1,255}$`

Request body

Required

application/json

descriptionstring
visibilitystring
- Allowed values: public, private
production_branchstring
tagsmap of string
Key-value tags for the project. The map replaces the stored tags. System tags the project already has stay on the project when the map omits them.
spicepodstring | object
The project's Spicepod. A project connected to a GitHub repository takes its Spicepod from the repository's spicepod.yaml, so for such a project only the stored Spicepod, sent back unchanged, is accepted.
image_tagstring | null
Runtime image tag for a managed project; rejected for standalone projects. A non-empty value pins the project. On stable, the pin must be a published stable runtime version. On preview, it must be a published preview or stable runtime version. 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_channelstring
Update channel for a managed runtime; rejected for standalone projects.
- Allowed values: stable, preview, nightly
versionstring
Semver range for a managed runtime version (e.g. 1.x, 2.x); rejected for standalone projects.
replicasinteger
Managed runtime replica count; rejected for standalone projects.
- Minimum: 0
resourcesobject
Resource requests and limits for a managed project container; rejected for standalone projects.
2 properties
- limitsobject
  3 properties
  - cpustring
    Whole-number vCPU limit, or '-' for no CPU limit
  - memorystring
    Memory limit in Gi (for example, 16Gi)
  - ephemeral-storagestring
    Ephemeral storage limit in Gi (for example, 8Gi)
- requestsobject
  2 properties
  - cpustring
    CPU request. Minimum 100 millicores (for example, 100m or 0.1).
  - memorystring
    Memory request. Minimum 192Mi.
executorobject
Executor container configuration for a managed project; rejected for standalone projects.
3 properties
- replicasinteger
  Number of executor replicas
  - Minimum: 0
- resourcesobject
  Resource requests and limits for the executor container
  2 properties
  - limitsobject
    3 properties
    cpustring
    Whole-number vCPU limit, or '-' for no CPU limit
    memorystring
    Memory limit in Gi (for example, 16Gi)
    ephemeral-storagestring
    Ephemeral storage limit in Gi (for example, 8Gi)
  - requestsobject
    2 properties
    cpustring
    CPU request. Minimum 100 millicores (for example, 100m or 0.1).
    memorystring
    Memory request. Minimum 192Mi.
- storage_size_gbnumber
regionstring
Managed project region; standalone placement is resolved during attachment.
cluster_namestring
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.
storage_size_gbnumber
Managed runtime storage size; rejected for standalone projects.
storage_claim_size_gbnumberDeprecated
Deprecated. Use storage_size_gb instead. Rejected for standalone projects.

Example request

curl -X PUT "https://api.spice.ai/v1/orgs/<orgId>/projects/<projectId>" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "string",
    "visibility": "public",
    "production_branch": "string",
    "tags": {},
    "spicepod": "string",
    "image_tag": "string",
    "update_channel": "stable",
    "version": "string",
    "replicas": 0,
    "resources": {},
    "executor": {},
    "region": "string",
    "cluster_name": "string",
    "storage_size_gb": 0,
    "storage_claim_size_gb": 0
  }'

Responses

200OK
Project updated successfully
application/json
- idinteger
  Unique identifier for the project
- namestring
  Name of the project
- kindstring
  Resolved project hosting model
  - Allowed values: managed, standalone, byoc
- descriptionstring | null
  Description of the project
- visibilitystring
  Visibility setting for the project
  - Allowed values: public, private
- created_atstring (date-time)
  Timestamp when the project was created
- cnamestring | null
  Region identifier
- cluster_namestring | null
  Resolved dedicated cluster name; null for projects not assigned to a dedicated cluster.
- endpointstring | null
  The data-plane endpoint the project connects to, or null before a standalone instance is attached.
- production_branchstring | null
  Production branch for the project
- api_keystringDeprecated
  Deprecated. Use the API Keys endpoints instead.
- tagsmap of string | null
  Key-value tags for the project
- forked_fromobject | null
  The project this project was forked from, while that project is live in the same organization. Null for a project that was not created as a fork.
  2 properties
  idintegerRequired
  ID of the source project
  namestringRequired
  Name of the source project
- paused_atstring (date-time) | null
  Timestamp when the project was paused; null while running
- warningstring | null
  Present when the project was created but initial configuration could not be applied
- configobject | null
  Runtime configuration; null for an unattached standalone project.
  10 properties
  spicepodobject | null
  Spicepod configuration
  registrystring | null
  Container registry for the runtime image
  image_tagstring | null
  Runtime image tag
  update_channelstring | null
  Update channel for the runtime
  Allowed values: stable, preview, nightly
  replicasinteger
  Number of replicas
  resourcesobject | null
  Resource requests and limits for the project container
  2 properties
  limitsobject
  3 properties
  cpustring
  Whole-number vCPU limit, or '-' for no CPU limit
  memorystring
  Memory limit in Gi (for example, 16Gi)
  ephemeral-storagestring
  requestsobject
  2 properties
  cpustring
  CPU request. Minimum 100 millicores (for example, 100m or 0.1).
  memorystring
  Memory request. Minimum 192Mi.
  executorobject | null
  Executor container configuration
  2 properties
  replicasinteger
  Number of executor replicas
  resourcesobject
  Resource requests and limits for the executor container
  2 properties
  limitsobject
  3 properties
  cpustring
  Whole-number vCPU limit, or '-' for no CPU limit
  memorystring
  Memory limit in Gi (for example, 16Gi)
  ephemeral-storagestring
  requestsobject
  2 properties
  cpustring
  CPU request. Minimum 100 millicores (for example, 100m or 0.1).
  memorystring
  Memory request. Minimum 192Mi.
  regionstring | null
  Cloud region code (e.g., us-east-1)
  node_groupstring | null
  Node group for scheduling the project runtime
  storage_claim_size_gbnumber | null
  Storage claim size in GB
400Bad Request
Invalid request body or project ID, including placement or hosted runtime fields that do not apply to standalone projects. When image_tag is supplied on stable or preview, a tag that is not a published version for that channel returns { error: 'Invalid image_tag for stable channel', code: 'invalid_stable_image_tag' } (or the preview analog). A spicepod that adds a component on a source the Spice runtime no longer loads returns code retired_component_source; components the project already stores on such a source may be kept, edited and renamed, and a project backed by a GitHub repository is not checked. orgId is not a valid org id (invalid_org_id), or X-Org-Name does not name that org (org_path_mismatch).
401Unauthorized
Unauthorized
403Forbidden
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. The caller is not a member of the org (org_forbidden). A machine credential named a different org (org_assertion_mismatch). The org is deleted (org_deleted).
404Not Found
Project not found
409Conflict
The project's lifecycle state changed while the update was in flight — a pause, resume or restore landing concurrently — so the configuration was not saved (code: project_state_changed). Re-read the project before retrying: a configuration update clears paused_at, so repeating this request against a project that has since been paused also resumes it. Or a spicepod that differs from the stored one was sent for a project connected to a GitHub repository (code: github_connected); change spicepod.yaml in the repository instead, since nothing in that request is applied.
500Internal Server Error
Internal server error
502Bad Gateway
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.
503Service Unavailable
Runtime version catalog is unavailable

Delete a project

DELETE/v1/orgs/{orgId}/projects/{projectId}

The org is orgId in the path. Deletes a project and tears down its runtime resources.

Path parameters

Name	Type	Required	Description
`orgId`	integer	Yes	The org id from GET /v1/orgs Minimum: `1`
`projectId`	integer	Yes	The ID of the project to delete

Header parameters

Name	Type	Required	Description
`Authorization`	string	Yes	`Bearer <token>`. Authentication lists the tokens it accepts.
`X-Org-Name`	string	No	When present, X-Org-Name must name the same org as orgId. Otherwise the request returns org_path_mismatch (400). Pattern: `^[A-Za-z0-9._-]{1,255}$`

Example request

curl -X DELETE "https://api.spice.ai/v1/orgs/<orgId>/projects/<projectId>" \
  -H "Authorization: Bearer <token>"

Responses

204No Content
Project deleted successfully
400Bad Request
Invalid project ID. orgId is not a valid org id (invalid_org_id), or X-Org-Name does not name that org (org_path_mismatch).
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope or viewer role cannot mutate projects. The caller is not a member of the org (org_forbidden). A machine credential named a different org (org_assertion_mismatch). The org is deleted (org_deleted).
404Not Found
Project not found
500Internal Server Error
Internal server error

List forks of a project

GET/v1/orgs/{orgId}/projects/{projectId}/forks

The org is orgId in the path. Returns the live projects in the organization that were forked from this project, ordered by name. Requires apps:read.

Path parameters

Name	Type	Required	Description
`orgId`	integer	Yes	The org id from GET /v1/orgs Minimum: `1`
`projectId`	integer	Yes	The ID of the source project

Header parameters

Name	Type	Required	Description
`Authorization`	string	Yes	`Bearer <token>`. Authentication lists the tokens it accepts.
`X-Org-Name`	string	No	When present, X-Org-Name must name the same org as orgId. Otherwise the request returns org_path_mismatch (400). Pattern: `^[A-Za-z0-9._-]{1,255}$`

Example request

curl "https://api.spice.ai/v1/orgs/<orgId>/projects/<projectId>/forks" \
  -H "Authorization: Bearer <token>"

Responses

200OK
Forks of the project
application/json
- forksarray of objectRequired
  10 properties
  idinteger
  Unique identifier for the project
  namestring
  Name of the project
  kindstring
  Resolved project hosting model
  Allowed values: managed, standalone, byoc
  descriptionstring | null
  Description of the project
  visibilitystring
  Visibility setting for the project
  Allowed values: public, private
  created_atstring (date-time)
  Timestamp when the project was created
  cnamestring | null
  Region identifier
  cluster_namestring | null
  Resolved dedicated cluster name; null for projects not assigned to a dedicated cluster.
  endpointstring | null
  The data-plane endpoint the project connects to, or null before a standalone instance is attached.
  tagsmap of string | null
  Key-value tags for the project
400Bad Request
Invalid project ID. orgId is not a valid org id (invalid_org_id), or X-Org-Name does not name that org (org_path_mismatch).
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope. The caller is not a member of the org (org_forbidden). A machine credential named a different org (org_assertion_mismatch). The org is deleted (org_deleted).
404Not Found
Project not found
500Internal Server Error
Internal server error

Fork a project

POST/v1/orgs/{orgId}/projects/{projectId}/forks

The org is orgId in the path. Creates a new project from this project's configuration and records this project as its source. The fork copies the spicepod the project deploys, its linked connections, project secrets, linked organization secrets, update channel, version range, replica and executor counts, storage size, description, and tags. It does not copy API keys (new ones are generated), deployments, the GitHub repository link, the instance size, or visibility (forks are private). The fork is not deployed: deploy it with POST /v1/projects/{projectId}/deployments. Requires apps:write. The server copies secret values without returning them, so no secrets scope is needed. A source connected to a GitHub repository is read from that repository, and its spicepod is copied only when it loads no other file from the repository; to deploy a fork from a fork of the repository, fork the project in the Spice portal.

Path parameters

Name	Type	Required	Description
`orgId`	integer	Yes	The org id from GET /v1/orgs Minimum: `1`
`projectId`	integer	Yes	The ID of the project to fork

Header parameters

Name	Type	Required	Description
`Authorization`	string	Yes	`Bearer <token>`. Authentication lists the tokens it accepts.
`X-Org-Name`	string	No	When present, X-Org-Name must name the same org as orgId. Otherwise the request returns org_path_mismatch (400). Pattern: `^[A-Za-z0-9._-]{1,255}$`

Request body

Optional

application/json

namestring
Name of the fork. Defaults to the source name with -fork, then -fork-2 and so on, whichever is free.
- Minimum length: 4
- Maximum length: 38
- Pattern: ^[a-zA-Z0-9-]+$
regionstring
Region to place the fork in. Omit it and cluster_name to place the fork where the source runs.
- Allowed values: us-east-1, us-west-2
cluster_namestring
Dedicated cluster to place the fork on, as listed by GET /v1/clusters. If region is also set, it must match the cluster's region.
scheduler_state_locationstring
s3:// URI for the fork's scheduler state. Required when the source spicepod sets runtime.scheduler.state_location, and must not overlap it: two schedulers cannot share a location.
- Maximum length: 2048
default_alertsboolean
Create default monitoring alerts for the new managed fork. False skips initial setup. Manual alert creation remains available.
- Default: true

Example request

curl -X POST "https://api.spice.ai/v1/orgs/<orgId>/projects/<projectId>/forks" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "region": "us-east-1",
    "cluster_name": "string",
    "scheduler_state_location": "string",
    "default_alerts": true
  }'

Responses

201Created
Project forked. It has not been deployed yet.
application/json
- idinteger
  Unique identifier for the project
- namestring
  Name of the project
- kindstring
  Resolved project hosting model
  - Allowed values: managed, standalone, byoc
- descriptionstring | null
  Description of the project
- visibilitystring
  Visibility setting for the project
  - Allowed values: public, private
- created_atstring (date-time)
  Timestamp when the project was created
- cnamestring | null
  Region identifier
- cluster_namestring | null
  Resolved dedicated cluster name; null for projects not assigned to a dedicated cluster.
- endpointstring | null
  The data-plane endpoint the project connects to, or null before a standalone instance is attached.
- production_branchstring | null
  Production branch for the project
- api_keystringDeprecated
  Deprecated. Use the API Keys endpoints instead.
- tagsmap of string | null
  Key-value tags for the project
- forked_fromobject | null
  The project this project was forked from, while that project is live in the same organization. Null for a project that was not created as a fork.
  2 properties
  idintegerRequired
  ID of the source project
  namestringRequired
  Name of the source project
- paused_atstring (date-time) | null
  Timestamp when the project was paused; null while running
- warningstring | null
  Present when the project was created but initial configuration could not be applied
- configobject | null
  Runtime configuration; null for an unattached standalone project.
  10 properties
  spicepodobject | null
  Spicepod configuration
  registrystring | null
  Container registry for the runtime image
  image_tagstring | null
  Runtime image tag
  update_channelstring | null
  Update channel for the runtime
  Allowed values: stable, preview, nightly
  replicasinteger
  Number of replicas
  resourcesobject | null
  Resource requests and limits for the project container
  2 properties
  limitsobject
  3 properties
  cpustring
  Whole-number vCPU limit, or '-' for no CPU limit
  memorystring
  Memory limit in Gi (for example, 16Gi)
  ephemeral-storagestring
  requestsobject
  2 properties
  cpustring
  CPU request. Minimum 100 millicores (for example, 100m or 0.1).
  memorystring
  Memory request. Minimum 192Mi.
  executorobject | null
  Executor container configuration
  2 properties
  replicasinteger
  Number of executor replicas
  resourcesobject
  Resource requests and limits for the executor container
  2 properties
  limitsobject
  3 properties
  cpustring
  Whole-number vCPU limit, or '-' for no CPU limit
  memorystring
  Memory limit in Gi (for example, 16Gi)
  ephemeral-storagestring
  requestsobject
  2 properties
  cpustring
  CPU request. Minimum 100 millicores (for example, 100m or 0.1).
  memorystring
  Memory request. Minimum 192Mi.
  regionstring | null
  Cloud region code (e.g., us-east-1)
  node_groupstring | null
  Node group for scheduling the project runtime
  storage_claim_size_gbnumber | null
  Storage claim size in GB
- shared_statearray of objectRequired
  Settings copied as they are that name external state the source also uses: a replication slot or Kafka consumer group the spicepod names, or a snapshot location. Change them in the fork's spicepod before deploying it if the two projects should not share that state.
  3 properties
  componentstringRequired
  The dataset, or snapshots
  settingstringRequired
  Example: pg_replication_slot
  valuestringRequired
400Bad Request
Invalid project ID or request body, an unknown region or cluster, no region or cluster_name set for a source whose placement a fork cannot reuse (a BYOC cluster, a self-hosted runtime, or a region or cluster that is no longer available; code: fork_placement_required), or a missing or unusable scheduler_state_location (code: scheduler_state_location_required, scheduler_state_location_unsupported, scheduler_state_location_overlaps_source, or scheduler_state_location_not_applicable). orgId is not a valid org id (invalid_org_id), or X-Org-Name does not name that org (org_path_mismatch).
401Unauthorized
Unauthorized
402Payment Required
The source runs models on hosted AI credits, which the organization has used up (code: ai_credits_exhausted).
403Forbidden
Insufficient scope, a viewer role, or the source runs more replicas or executors than the plan or the dedicated cluster allows. The caller is not a member of the org (org_forbidden). A machine credential named a different org (org_assertion_mismatch). The org is deleted (org_deleted).
404Not Found
Project or organization not found
409Conflict
A project with the requested name already exists, another project creation is in progress, or every default name is taken (code: fork_name_unavailable)
413Content Too Large
Request body too large
422Unprocessable Content
The source has no spicepod (code: fork_source_has_no_spicepod), its spicepod is not valid (code: fork_source_spicepod_invalid), or its spicepod loads files from its GitHub repository besides spicepod.yaml (code: fork_source_loads_repository_files)
429Too Many Requests
Too many project creation requests (rate limited)
500Internal Server Error
The fork could not be created. When the failure comes after the project row is created, the fork is deleted again with its spicepod, secrets, and organization secret links. If the project itself cannot be deleted, the response has code: fork_rollback_failed and names the partially created project in project (id and name). Delete that project, by project.id, before reusing its name.
502Bad Gateway
The source is connected to a GitHub repository, and its spicepod could not be read from it (code: fork_source_repository_unreadable)

Pause a project

POST/v1/orgs/{orgId}/projects/{projectId}/pause

The org is orgId in the path. 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.

Path parameters

Name	Type	Required	Description
`orgId`	integer	Yes	The org id from GET /v1/orgs Minimum: `1`
`projectId`	integer	Yes	The ID of the project to pause

Header parameters

Name	Type	Required	Description
`Authorization`	string	Yes	`Bearer <token>`. Authentication lists the tokens it accepts.
`X-Org-Name`	string	No	When present, X-Org-Name must name the same org as orgId. Otherwise the request returns org_path_mismatch (400). Pattern: `^[A-Za-z0-9._-]{1,255}$`

Example request

curl -X POST "https://api.spice.ai/v1/orgs/<orgId>/projects/<projectId>/pause" \
  -H "Authorization: Bearer <token>"

Responses

200OK
Project paused
application/json
- idintegerRequired
  The project ID
- namestringRequired
  The project name
- paused_atstring (date-time)Required
  Timestamp when the project was paused
400Bad Request
Invalid project ID, missing API key, no spicepod configured, or spicepod has been deleted. orgId is not a valid org id (invalid_org_id), or X-Org-Name does not name that org (org_path_mismatch).
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope. The caller is not a member of the org (org_forbidden). A machine credential named a different org (org_assertion_mismatch). The org is deleted (org_deleted).
404Not Found
Project not found
409Conflict
Project is already paused
application/json
- errorstringRequired
- paused_atstring (date-time)Required
  Timestamp of the existing pause
500Internal Server Error
Internal server error

Resume a paused project

POST/v1/orgs/{orgId}/projects/{projectId}/resume

The org is orgId in the path. Clears the paused state on the project's spicepod and creates a new deployment to bring the runtime back up. A project connected to a GitHub repository deploys spicepod.yaml from its root directory on its production branch, read when the project resumes. Requires apps:write.

Path parameters

Name	Type	Required	Description
`orgId`	integer	Yes	The org id from GET /v1/orgs Minimum: `1`
`projectId`	integer	Yes	The ID of the project to resume

Header parameters

Name	Type	Required	Description
`Authorization`	string	Yes	`Bearer <token>`. Authentication lists the tokens it accepts.
`X-Org-Name`	string	No	When present, X-Org-Name must name the same org as orgId. Otherwise the request returns org_path_mismatch (400). Pattern: `^[A-Za-z0-9._-]{1,255}$`

Example request

curl -X POST "https://api.spice.ai/v1/orgs/<orgId>/projects/<projectId>/resume" \
  -H "Authorization: Bearer <token>"

Responses

200OK
Project resumed, deployment created
application/json
- idintegerRequired
  The project ID
- namestringRequired
  The project name
- paused_atstring (date-time) | nullRequired
  Always null after a successful resume
- deployment_idintegerRequired
  ID of the deployment created to bring the runtime back up
400Bad Request
Invalid project ID, missing API key, missing project organization, no spicepod configured, spicepod has been deleted, or the spicepod name, kind or version is missing or not valid (the body carries an issues array of {path, message}). For a project connected to a GitHub repository, also returned when the root directory has no spicepod.yaml or it is invalid or too large (code: spicepod_not_found, spicepod_invalid or spicepod_too_large). The project stays paused. orgId is not a valid org id (invalid_org_id), or X-Org-Name does not name that org (org_path_mismatch).
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope, or the org's GitHub App installation cannot read the connected repository (code: github_unauthorized or github_forbidden). The project stays paused. The caller is not a member of the org (org_forbidden). A machine credential named a different org (org_assertion_mismatch). The org is deleted (org_deleted).
404Not Found
Project not found, or the connected GitHub repository or its production branch was not found (code: github_not_found). The project stays paused.
409Conflict
Project is not paused
422Unprocessable Content
No runtime version in the catalog matches this project’s version range (code: version_no_match), or the spicepod uses version v1beta1, which the Spice 2 runtime cannot load (code: spicepod_version_unsupported). Also returned when the spicepod uses a connection credential that holds a secret reference deploy cannot resolve (code: connection_credentials_unresolved, with an unresolved_credentials array of {connection, field}). The project stays paused.
429Too Many Requests
GitHub rate-limited the read of the connected repository (code: github_rate_limited). The project stays paused.
500Internal Server Error
Internal server error
502Bad Gateway
GitHub did not answer while the connected repository was read (code: github_unavailable). The project stays paused.
503Service Unavailable
The runtime version catalog is unavailable or empty (code: version_source_unavailable), so an unpinned stable or preview resume cannot resolve an image tag.

Connect a project to a GitHub repository

PUT/v1/orgs/{orgId}/projects/{projectId}/repository

The org is orgId in the path. Connects the project to a repository in the organization's GitHub account, through the organization's Spice Cloud GitHub App installation. The next deployment reads spicepod.yaml (or spicepod.yml) from root_directory on production_branch. Connecting sets the project description to the repository description. Connecting again replaces the repository, root directory and production branch. Requires apps:write.

Path parameters

Name	Type	Required	Description
`orgId`	integer	Yes	The org id from GET /v1/orgs Minimum: `1`
`projectId`	integer	Yes	The ID of the project to connect

Header parameters

Name	Type	Required	Description
`Authorization`	string	Yes	`Bearer <token>`. Authentication lists the tokens it accepts.
`X-Org-Name`	string	No	When present, X-Org-Name must name the same org as orgId. Otherwise the request returns org_path_mismatch (400). Pattern: `^[A-Za-z0-9._-]{1,255}$`

Request body

Required

application/json

repositorystringRequired
Repository in the organization's GitHub account, as name or owner/name. The owner must be the organization's GitHub account.
- Example: cookbook
root_directorystring | null
Directory inside the repository that contains spicepod.yaml. Omit it, or send null or an empty string, for the repository root.
- Maximum length: 512
- Example: cayenne
production_branchstring
Branch that deployments read. Defaults to the repository's default branch. A branch that GitHub renamed is stored under its new name.
- Maximum length: 255
- Example: trunk

Example request

curl -X PUT "https://api.spice.ai/v1/orgs/<orgId>/projects/<projectId>/repository" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "repository": "cookbook"
  }'

Responses

200OK
Project connected
application/json
- project_idintegerRequired
  The project ID
- repositorystringRequired
  The repository as owner/name
- repository_idintegerRequired
  The GitHub repository ID
- root_directorystring | nullRequired
  The stored root directory. Null is the repository root.
- production_branchstringRequired
  The branch that deployments read
- connected_atstring (date-time)Required
  When the project was connected
- has_spicepodbooleanRequired
  True when spicepod.yaml or spicepod.yml exists in the root directory on the production branch. A deployment fails until it does.
400Bad Request
Invalid project ID or request body, a repository outside the organization's GitHub account (code: invalid_repository), or a root directory outside the repository (code: invalid_root_directory). orgId is not a valid org id (invalid_org_id), or X-Org-Name does not name that org (org_path_mismatch).
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope, or viewer role cannot mutate projects. The caller is not a member of the org (org_forbidden). A machine credential named a different org (org_assertion_mismatch). The org is deleted (org_deleted).
404Not Found
Project not found, or the organization's GitHub App installation cannot read the repository (code: repository_not_found)
409Conflict
The organization has no usable GitHub App installation (code: github_not_connected), or another project already deploys this repository and root directory (code: root_directory_conflict)
413Content Too Large
Request body too large
422Unprocessable Content
The repository has no branch named production_branch (code: branch_not_found), the project has no spicepod configuration (code: spicepod_missing), or the organization is not fully configured
500Internal Server Error
Internal server error
503Service Unavailable
GitHub did not answer (code: github_unavailable)

Get project metrics

GET/v1/orgs/{orgId}/projects/{projectId}/metrics

The org is orgId in the path. Returns current resource utilization metrics (CPU, memory, disk I/O) and data ingestion metrics for a project.

Path parameters

Name	Type	Required	Description
`orgId`	integer	Yes	The org id from GET /v1/orgs Minimum: `1`
`projectId`	integer	Yes	The ID of the project

Query parameters

Name	Type	Required	Description
`window`	string	No	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.

Header parameters

Name	Type	Required	Description
`Authorization`	string	Yes	`Bearer <token>`. Authentication lists the tokens it accepts.
`X-Org-Name`	string	No	When present, X-Org-Name must name the same org as orgId. Otherwise the request returns org_path_mismatch (400). Pattern: `^[A-Za-z0-9._-]{1,255}$`

Example request

curl "https://api.spice.ai/v1/orgs/<orgId>/projects/<projectId>/metrics" \
  -H "Authorization: Bearer <token>"

Responses

200OK
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
- ingestionobject
  Aggregated data ingestion metrics
  2 properties
  rows_ingestednumber
  Total rows ingested (without window) or rows per second (with window)
  bytes_ingestednumber
  Total bytes ingested (without window) or bytes per second (with window)
- clusterobject
  Cluster metrics for the project
  1 property
  active_executors_countnumber
  Number of active executors registered with the scheduler
- metricsmap of object
  Resource metrics keyed by pod name
  6 properties
  cpu_usage_percentnumber
  CPU usage as a percentage (0-100)
  memory_usage_bytesnumber
  Memory usage in bytes
  disk_read_bytesnumber
  Disk bytes read per second (with window) or cumulative (without window)
  disk_read_operationsnumber
  Disk read operations per second (with window) or cumulative count (without window)
  disk_write_bytesnumber
  Disk bytes written per second (with window) or cumulative (without window)
  disk_write_operationsnumber
  Disk write operations per second (with window) or cumulative count (without window)
400Bad Request
Invalid project ID. orgId is not a valid org id (invalid_org_id), or X-Org-Name does not name that org (org_path_mismatch).
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope. The caller is not a member of the org (org_forbidden). A machine credential named a different org (org_assertion_mismatch). The org is deleted (org_deleted).
404Not Found
Project or organization not found
422Unprocessable Content
Organization is not fully configured
500Internal Server Error
Internal server error
503Service Unavailable
Metrics service unavailable

List project instances

GET/v1/orgs/{orgId}/projects/{projectId}/instances

The org is orgId in the path. Lists the runtime instances of a deployed project, newest first. A managed or BYOC project lists its Spicepod instances. A standalone project lists its Cloud Connect runtime. Read the logs of an instance with GET /v1/projects/{projectId}/instances/{instanceName}/logs.

Path parameters

Name	Type	Required	Description
`orgId`	integer	Yes	The org id from GET /v1/orgs Minimum: `1`
`projectId`	integer	Yes	The ID of the project

Header parameters

Name	Type	Required	Description
`Authorization`	string	Yes	`Bearer <token>`. Authentication lists the tokens it accepts.
`X-Org-Name`	string	No	When present, X-Org-Name must name the same org as orgId. Otherwise the request returns org_path_mismatch (400). Pattern: `^[A-Za-z0-9._-]{1,255}$`

Example request

curl "https://api.spice.ai/v1/orgs/<orgId>/projects/<projectId>/instances" \
  -H "Authorization: Bearer <token>"

Responses

200OK
The project's instances
application/json
- instancesarray of objectRequired
  3 properties
  namestringRequired
  The instance name: a Spicepod instance (pod) name, or a Cloud Connect runtime id. Pass it as instanceName to read its logs.
  statusstringRequired
  A Spicepod instance is deploying, loading, ready, unhealthy, terminating, failed, or failed_to_start. A Cloud Connect runtime is online or offline.
  Allowed values: deploying, loading, ready, unhealthy, terminating, failed, failed_to_start, online, offline
  started_atstring (date-time) | nullRequired
  When the Spicepod instance started, or when the Cloud Connect runtime enrolled.
400Bad Request
Invalid project ID. orgId is not a valid org id (invalid_org_id), or X-Org-Name does not name that org (org_path_mismatch).
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope. The caller is not a member of the org (org_forbidden). A machine credential named a different org (org_assertion_mismatch). The org is deleted (org_deleted).
404Not Found
Project not found
409Conflict
The project has no running instances. code is project_not_deployed when a managed or BYOC project was never deployed, or project_paused when the project is paused.
application/json
- errorstringRequired
- codestringRequired
  - Allowed values: project_not_deployed, project_paused
422Unprocessable Content
The project is not fully configured
500Internal Server Error
Internal server error
503Service Unavailable
The project runtime did not answer

Get project instance logs

GET/v1/orgs/{orgId}/projects/{projectId}/instances/{instanceName}/logs

The org is orgId in the path. Returns the most recent log lines of one instance of a deployed project, oldest first, without color codes. The org's plan sets the largest tail. List the instance names with GET /v1/projects/{projectId}/instances.

Path parameters

Name	Type	Required	Description
`orgId`	integer	Yes	The org id from GET /v1/orgs Minimum: `1`
`projectId`	integer	Yes	The ID of the project
`instanceName`	string	Yes	The instance name from `GET /v1/projects/{projectId}/instances`

Query parameters

Name	Type	Required	Description
`tail`	integer	No	How many of the most recent lines to return Default: `100` Minimum: `1`

Header parameters

Name	Type	Required	Description
`Authorization`	string	Yes	`Bearer <token>`. Authentication lists the tokens it accepts.
`X-Org-Name`	string	No	When present, X-Org-Name must name the same org as orgId. Otherwise the request returns org_path_mismatch (400). Pattern: `^[A-Za-z0-9._-]{1,255}$`

Example request

curl "https://api.spice.ai/v1/orgs/<orgId>/projects/<projectId>/instances/<instanceName>/logs" \
  -H "Authorization: Bearer <token>"

Responses

200OK
The instance's most recent log lines
application/json
- instancestringRequired
  The instance name
- tailintegerRequired
  The number of lines asked for
- linesarray of stringRequired
  Log lines, oldest first
400Bad Request
Invalid project ID or tail. orgId is not a valid org id (invalid_org_id), or X-Org-Name does not name that org (org_path_mismatch).
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope (code is insufficient_scope), or tail is larger than the org's plan allows (code is plan_limit, and max_tail is the largest allowed tail). The caller is not a member of the org (org_forbidden). A machine credential named a different org (org_assertion_mismatch). The org is deleted (org_deleted).
application/json
- errorstringRequired
- codestringRequired
- max_tailinteger
404Not Found
The project was not found, or the instance is not one of the project's instances (code is instance_not_found).
409Conflict
The logs cannot be read in the project's current state. code is project_not_deployed when the project was never deployed, project_paused when it is paused, or instance_offline when the Cloud Connect runtime is offline and does not answer.
application/json
- errorstringRequired
- codestringRequired
  - Allowed values: project_not_deployed, project_paused, instance_offline
422Unprocessable Content
The project is not fully configured
500Internal Server Error
Internal server error
503Service Unavailable
The project runtime did not answer

List projects

GET/v1/appsDeprecated

Legacy alias of /v1/projects — projects were previously called apps. Returns projects belonging to the authenticated organization. Page with limit (default 1000, max 1000). Prefer after_id for a stable keyset (descending id). offset is accepted for compatibility. PostgREST also caps a page at 1000 rows.

Query parameters

Name	Type	Required	Description
`limit`	integer	No	Maximum number of projects to return Default: `1000` Minimum: `1` Maximum: `1000`
`offset`	integer	No	Number of projects to skip when a cursor is not supplied Default: `0` Minimum: `0`
`after_id`	integer	No	Return projects with a strictly smaller id than this value. Minimum: `1`

Header parameters

Name	Type	Required	Description
`Authorization`	string	Yes	`Bearer <token>`. Authentication lists the tokens it accepts.
`X-Org-Name`	string	No	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 portal session token is bound to none, so it must send this header on every route but `GET /v1/orgs` (400 `org_assertion_required` otherwise). Pattern: `^[A-Za-z0-9._-]{1,255}$`

Example request

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

Responses

200OK
List of projects
application/json
- appsarray of object
  10 properties
  idinteger
  Unique identifier for the project
  namestring
  Name of the project
  kindstring
  Resolved project hosting model
  Allowed values: managed, standalone, byoc
  descriptionstring | null
  Description of the project
  visibilitystring
  Visibility setting for the project
  Allowed values: public, private
  created_atstring (date-time)
  Timestamp when the project was created
  cnamestring | null
  Region identifier
  cluster_namestring | null
  Resolved dedicated cluster name; null for projects not assigned to a dedicated cluster.
  endpointstring | null
  The data-plane endpoint the project connects to, or null before a standalone instance is attached.
  tagsmap of string | null
  Key-value tags for the project
400Bad Request
Invalid limit, offset, or after_id
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope

Create a project

POST/v1/appsDeprecated

Legacy alias of /v1/projects — projects were previously called apps. Creates a new project in the authenticated organization.

Header parameters

Name	Type	Required	Description
`Authorization`	string	Yes	`Bearer <token>`. Authentication lists the tokens it accepts.
`X-Org-Name`	string	No	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 portal session token is bound to none, so it must send this header on every route but `GET /v1/orgs` (400 `org_assertion_required` otherwise). Pattern: `^[A-Za-z0-9._-]{1,255}$`

Request body

Required

application/json

namestringRequired
Project name (letters, numbers, hyphens only)
- Minimum length: 4
- Pattern: ^[a-zA-Z0-9-]+$
regionstring
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.
- Allowed values: us-east-1, us-west-2
cnamestring
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.
cluster_namestring
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.
descriptionstring
Project description
visibilitystring
- Allowed values: public, private
- Default: private
default_alertsboolean
Create default monitoring alerts for the new managed project. False skips initial setup. Manual alert creation remains available.
- Default: true
tagsmap of string
Key-value tags for the project
update_channelstring
Update channel for a managed project deployment. A standalone project has no spicepod until linking, so configure its channel after linking.
- Allowed values: stable, preview, nightly
replicasinteger
Number of replicas for a managed project. Rejected for standalone projects.
- Minimum: 0
resourcesobject
Resource requests and limits for a managed project container. Rejected for standalone projects.
2 properties
- limitsobject
  3 properties
  - cpustring
    Whole-number vCPU limit, or '-' for no CPU limit
  - memorystring
    Memory limit in Gi (for example, 16Gi)
  - ephemeral-storagestring
    Ephemeral storage limit in Gi (for example, 8Gi)
- requestsobject
  2 properties
  - cpustring
    CPU request. Minimum 100 millicores (for example, 100m or 0.1).
  - memorystring
    Memory request. Minimum 192Mi.
executorobject
Executor container configuration for a managed project. Rejected for standalone projects.
2 properties
- replicasinteger
  Number of executor replicas
  - Minimum: 0
- resourcesobject
  Resource requests and limits for the executor container
  2 properties
  - limitsobject
    3 properties
    cpustring
    Whole-number vCPU limit, or '-' for no CPU limit
    memorystring
    Memory limit in Gi (for example, 16Gi)
    ephemeral-storagestring
    Ephemeral storage limit in Gi (for example, 8Gi)
  - requestsobject
    2 properties
    cpustring
    CPU request. Minimum 100 millicores (for example, 100m or 0.1).
    memorystring
    Memory request. Minimum 192Mi.

Example request

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

Responses

201Created
Project created successfully. The response may include a warning field if initial configuration could not be applied.
application/json
- idinteger
  Unique identifier for the project
- namestring
  Name of the project
- kindstring
  Resolved project hosting model
  - Allowed values: managed, standalone, byoc
- descriptionstring | null
  Description of the project
- visibilitystring
  Visibility setting for the project
  - Allowed values: public, private
- created_atstring (date-time)
  Timestamp when the project was created
- cnamestring | null
  Region identifier
- cluster_namestring | null
  Resolved dedicated cluster name; null for projects not assigned to a dedicated cluster.
- endpointstring | null
  The data-plane endpoint the project connects to, or null before a standalone instance is attached.
- production_branchstring | null
  Production branch for the project
- api_keystringDeprecated
  Deprecated. Use the API Keys endpoints instead.
- tagsmap of string | null
  Key-value tags for the project
- forked_fromobject | null
  The project this project was forked from, while that project is live in the same organization. Null for a project that was not created as a fork.
  2 properties
  idintegerRequired
  ID of the source project
  namestringRequired
  Name of the source project
- paused_atstring (date-time) | null
  Timestamp when the project was paused; null while running
- warningstring | null
  Present when the project was created but initial configuration could not be applied
- configobject | null
  Runtime configuration; null for an unattached standalone project.
  10 properties
  spicepodobject | null
  Spicepod configuration
  registrystring | null
  Container registry for the runtime image
  image_tagstring | null
  Runtime image tag
  update_channelstring | null
  Update channel for the runtime
  Allowed values: stable, preview, nightly
  replicasinteger
  Number of replicas
  resourcesobject | null
  Resource requests and limits for the project container
  2 properties
  limitsobject
  3 properties
  cpustring
  Whole-number vCPU limit, or '-' for no CPU limit
  memorystring
  Memory limit in Gi (for example, 16Gi)
  ephemeral-storagestring
  requestsobject
  2 properties
  cpustring
  CPU request. Minimum 100 millicores (for example, 100m or 0.1).
  memorystring
  Memory request. Minimum 192Mi.
  executorobject | null
  Executor container configuration
  2 properties
  replicasinteger
  Number of executor replicas
  resourcesobject
  Resource requests and limits for the executor container
  2 properties
  limitsobject
  3 properties
  cpustring
  Whole-number vCPU limit, or '-' for no CPU limit
  memorystring
  Memory limit in Gi (for example, 16Gi)
  ephemeral-storagestring
  requestsobject
  2 properties
  cpustring
  CPU request. Minimum 100 millicores (for example, 100m or 0.1).
  memorystring
  Memory request. Minimum 192Mi.
  regionstring | null
  Cloud region code (e.g., us-east-1)
  node_groupstring | null
  Node group for scheduling the project runtime
  storage_claim_size_gbnumber | null
  Storage claim size in GB
400Bad Request
Invalid request body or invalid region
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope, dedicated-cluster assignment or special-org private-compute ceilings required for resource limits, or requested resources exceed dedicated-cluster capacity
409Conflict
A project with this name already exists, or the project was deleted while its initial configuration was being written (code is project_deleted)
429Too Many Requests
Too many project creation requests (rate limited)
500Internal Server Error
Project creation failed, including when the name-collision check could not be read
application/json
- errorstringRequired
  Generic failure reason; the underlying cause stays in the server logs
  - Example: Failed to create project

Get a project

GET/v1/apps/{appId}Deprecated

Legacy alias of /v1/projects/{projectId} — projects were previously called apps. Returns details for a specific project, including its configuration.

Path parameters

Name	Type	Required	Description
`appId`	integer	Yes	The ID of the project

Header parameters

Name	Type	Required	Description
`Authorization`	string	Yes	`Bearer <token>`. Authentication lists the tokens it accepts.
`X-Org-Name`	string	No	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 portal session token is bound to none, so it must send this header on every route but `GET /v1/orgs` (400 `org_assertion_required` otherwise). Pattern: `^[A-Za-z0-9._-]{1,255}$`

Example request

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

Responses

200OK
Project details with configuration
application/json
- idinteger
- namestring
- kindstring
  Resolved project hosting model
  - Allowed values: managed, standalone, byoc
- descriptionstring
- visibilitystring
  - Allowed values: public, private
- created_atstring (date-time)
- cluster_namestring | null
  Resolved dedicated cluster name; null for projects not assigned to a dedicated cluster.
- endpointstring | null
  The data-plane endpoint the project connects to, or null before a standalone instance is attached.
- production_branchstring
- api_keystringDeprecated
  Deprecated. Use the API Keys endpoints instead.
- tagsmap of string
- forked_fromobject | null
  The project this project was forked from, while that project is live in the same organization. Null for a project that was not created as a fork.
  2 properties
  idintegerRequired
  ID of the source project
  namestringRequired
  Name of the source project
- paused_atstring (date-time) | null
  Timestamp when the project was paused; null while running
- configobject
  10 properties
  spicepodobject
  image_tagstring
  Runtime image tag
  update_channelstring | null
  Update channel for the runtime, or null when Spice operates this project's runtime updates.
  Allowed values: stable, preview, nightly
  versionstring
  Semver range for the runtime version (e.g. 1.x, 2.x)
  replicasinteger
  resourcesobject | null
  Resource requests and limits for the project container
  2 properties
  limitsobject
  3 properties
  cpustring
  Whole-number vCPU limit, or '-' for no CPU limit
  memorystring
  Memory limit in Gi (for example, 16Gi)
  ephemeral-storagestring
  requestsobject
  2 properties
  cpustring
  CPU request. Minimum 100 millicores (for example, 100m or 0.1).
  memorystring
  Memory request. Minimum 192Mi.
  executorobject | null
  Executor container configuration
  3 properties
  replicasinteger
  Number of executor replicas
  resourcesobject
  Resource requests and limits for the executor container
  2 properties
  limitsobject
  3 properties
  cpustring
  Whole-number vCPU limit, or '-' for no CPU limit
  memorystring
  Memory limit in Gi (for example, 16Gi)
  ephemeral-storagestring
  requestsobject
  2 properties
  cpustring
  CPU request. Minimum 100 millicores (for example, 100m or 0.1).
  memorystring
  Memory request. Minimum 192Mi.
  storage_size_gbnumber | null
  regionstring | null
  Server-resolved region; null before a standalone instance is attached.
  storage_size_gbnumber | null
  storage_claim_size_gbnumberDeprecated
  Deprecated. Use storage_size_gb instead.
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope
404Not Found
Project not found
500Internal Server Error
Internal server error

Update a project

PUT/v1/apps/{appId}Deprecated

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.

Path parameters

Name	Type	Required	Description
`appId`	integer	Yes	The ID of the project

Header parameters

Name	Type	Required	Description
`Authorization`	string	Yes	`Bearer <token>`. Authentication lists the tokens it accepts.
`X-Org-Name`	string	No	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 portal session token is bound to none, so it must send this header on every route but `GET /v1/orgs` (400 `org_assertion_required` otherwise). Pattern: `^[A-Za-z0-9._-]{1,255}$`

Request body

Required

application/json

descriptionstring
visibilitystring
- Allowed values: public, private
production_branchstring
tagsmap of string
Key-value tags for the project. The map replaces the stored tags. System tags the project already has stay on the project when the map omits them.
spicepodstring | object
The project's Spicepod. A project connected to a GitHub repository takes its Spicepod from the repository's spicepod.yaml, so for such a project only the stored Spicepod, sent back unchanged, is accepted.
image_tagstring | null
Runtime image tag for a managed project; rejected for standalone projects. A non-empty value pins the project. On stable, the pin must be a published stable runtime version. On preview, it must be a published preview or stable runtime version. 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_channelstring
Update channel for a managed runtime; rejected for standalone projects.
- Allowed values: stable, preview, nightly
versionstring
Semver range for a managed runtime version (e.g. 1.x, 2.x); rejected for standalone projects.
replicasinteger
Managed runtime replica count; rejected for standalone projects.
- Minimum: 0
resourcesobject
Resource requests and limits for a managed project container; rejected for standalone projects.
2 properties
- limitsobject
  3 properties
  - cpustring
    Whole-number vCPU limit, or '-' for no CPU limit
  - memorystring
    Memory limit in Gi (for example, 16Gi)
  - ephemeral-storagestring
    Ephemeral storage limit in Gi (for example, 8Gi)
- requestsobject
  2 properties
  - cpustring
    CPU request. Minimum 100 millicores (for example, 100m or 0.1).
  - memorystring
    Memory request. Minimum 192Mi.
executorobject
Executor container configuration for a managed project; rejected for standalone projects.
3 properties
- replicasinteger
  Number of executor replicas
  - Minimum: 0
- resourcesobject
  Resource requests and limits for the executor container
  2 properties
  - limitsobject
    3 properties
    cpustring
    Whole-number vCPU limit, or '-' for no CPU limit
    memorystring
    Memory limit in Gi (for example, 16Gi)
    ephemeral-storagestring
    Ephemeral storage limit in Gi (for example, 8Gi)
  - requestsobject
    2 properties
    cpustring
    CPU request. Minimum 100 millicores (for example, 100m or 0.1).
    memorystring
    Memory request. Minimum 192Mi.
- storage_size_gbnumber
regionstring
Managed project region; standalone placement is resolved during attachment.
cluster_namestring
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.
storage_size_gbnumber
Managed runtime storage size; rejected for standalone projects.
storage_claim_size_gbnumberDeprecated
Deprecated. Use storage_size_gb instead. Rejected for standalone projects.

Example request

curl -X PUT "https://api.spice.ai/v1/apps/<appId>" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "string",
    "visibility": "public",
    "production_branch": "string",
    "tags": {},
    "spicepod": "string",
    "image_tag": "string",
    "update_channel": "stable",
    "version": "string",
    "replicas": 0,
    "resources": {},
    "executor": {},
    "region": "string",
    "cluster_name": "string",
    "storage_size_gb": 0,
    "storage_claim_size_gb": 0
  }'

Responses

200OK
Project updated successfully
application/json
- idinteger
  Unique identifier for the project
- namestring
  Name of the project
- kindstring
  Resolved project hosting model
  - Allowed values: managed, standalone, byoc
- descriptionstring | null
  Description of the project
- visibilitystring
  Visibility setting for the project
  - Allowed values: public, private
- created_atstring (date-time)
  Timestamp when the project was created
- cnamestring | null
  Region identifier
- cluster_namestring | null
  Resolved dedicated cluster name; null for projects not assigned to a dedicated cluster.
- endpointstring | null
  The data-plane endpoint the project connects to, or null before a standalone instance is attached.
- production_branchstring | null
  Production branch for the project
- api_keystringDeprecated
  Deprecated. Use the API Keys endpoints instead.
- tagsmap of string | null
  Key-value tags for the project
- forked_fromobject | null
  The project this project was forked from, while that project is live in the same organization. Null for a project that was not created as a fork.
  2 properties
  idintegerRequired
  ID of the source project
  namestringRequired
  Name of the source project
- paused_atstring (date-time) | null
  Timestamp when the project was paused; null while running
- warningstring | null
  Present when the project was created but initial configuration could not be applied
- configobject | null
  Runtime configuration; null for an unattached standalone project.
  10 properties
  spicepodobject | null
  Spicepod configuration
  registrystring | null
  Container registry for the runtime image
  image_tagstring | null
  Runtime image tag
  update_channelstring | null
  Update channel for the runtime
  Allowed values: stable, preview, nightly
  replicasinteger
  Number of replicas
  resourcesobject | null
  Resource requests and limits for the project container
  2 properties
  limitsobject
  3 properties
  cpustring
  Whole-number vCPU limit, or '-' for no CPU limit
  memorystring
  Memory limit in Gi (for example, 16Gi)
  ephemeral-storagestring
  requestsobject
  2 properties
  cpustring
  CPU request. Minimum 100 millicores (for example, 100m or 0.1).
  memorystring
  Memory request. Minimum 192Mi.
  executorobject | null
  Executor container configuration
  2 properties
  replicasinteger
  Number of executor replicas
  resourcesobject
  Resource requests and limits for the executor container
  2 properties
  limitsobject
  3 properties
  cpustring
  Whole-number vCPU limit, or '-' for no CPU limit
  memorystring
  Memory limit in Gi (for example, 16Gi)
  ephemeral-storagestring
  requestsobject
  2 properties
  cpustring
  CPU request. Minimum 100 millicores (for example, 100m or 0.1).
  memorystring
  Memory request. Minimum 192Mi.
  regionstring | null
  Cloud region code (e.g., us-east-1)
  node_groupstring | null
  Node group for scheduling the project runtime
  storage_claim_size_gbnumber | null
  Storage claim size in GB
400Bad Request
Invalid request body or project ID, including placement or hosted runtime fields that do not apply to standalone projects. When image_tag is supplied on stable or preview, a tag that is not a published version for that channel returns { error: 'Invalid image_tag for stable channel', code: 'invalid_stable_image_tag' } (or the preview analog). A spicepod that adds a component on a source the Spice runtime no longer loads returns code retired_component_source; components the project already stores on such a source may be kept, edited and renamed, and a project backed by a GitHub repository is not checked.
401Unauthorized
Unauthorized
403Forbidden
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
404Not Found
Project not found
409Conflict
The project's lifecycle state changed while the update was in flight — a pause, resume or restore landing concurrently — so the configuration was not saved (code: project_state_changed). Re-read the project before retrying: a configuration update clears paused_at, so repeating this request against a project that has since been paused also resumes it. Or a spicepod that differs from the stored one was sent for a project connected to a GitHub repository (code: github_connected); change spicepod.yaml in the repository instead, since nothing in that request is applied.
500Internal Server Error
Internal server error
502Bad Gateway
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.
503Service Unavailable
Runtime version catalog is unavailable

Delete a project

DELETE/v1/apps/{appId}Deprecated

Legacy alias of /v1/projects/{projectId} — projects were previously called apps. Deletes a project and tears down its runtime resources.

Path parameters

Name	Type	Required	Description
`appId`	integer	Yes	The ID of the project to delete

Header parameters

Name	Type	Required	Description
`Authorization`	string	Yes	`Bearer <token>`. Authentication lists the tokens it accepts.
`X-Org-Name`	string	No	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 portal session token is bound to none, so it must send this header on every route but `GET /v1/orgs` (400 `org_assertion_required` otherwise). Pattern: `^[A-Za-z0-9._-]{1,255}$`

Example request

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

Responses

204No Content
Project deleted successfully
400Bad Request
Invalid project ID
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope or viewer role cannot mutate projects
404Not Found
Project not found
500Internal Server Error
Internal server error

List forks of a project

GET/v1/apps/{appId}/forksDeprecated

Legacy alias of /v1/projects/{projectId}/forks — projects were previously called apps. Returns the live projects in the organization that were forked from this project, ordered by name. Requires apps:read.

Path parameters

Name	Type	Required	Description
`appId`	integer	Yes	The ID of the source project

Header parameters

Name	Type	Required	Description
`Authorization`	string	Yes	`Bearer <token>`. Authentication lists the tokens it accepts.
`X-Org-Name`	string	No	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 portal session token is bound to none, so it must send this header on every route but `GET /v1/orgs` (400 `org_assertion_required` otherwise). Pattern: `^[A-Za-z0-9._-]{1,255}$`

Example request

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

Responses

200OK
Forks of the project
application/json
- forksarray of objectRequired
  10 properties
  idinteger
  Unique identifier for the project
  namestring
  Name of the project
  kindstring
  Resolved project hosting model
  Allowed values: managed, standalone, byoc
  descriptionstring | null
  Description of the project
  visibilitystring
  Visibility setting for the project
  Allowed values: public, private
  created_atstring (date-time)
  Timestamp when the project was created
  cnamestring | null
  Region identifier
  cluster_namestring | null
  Resolved dedicated cluster name; null for projects not assigned to a dedicated cluster.
  endpointstring | null
  The data-plane endpoint the project connects to, or null before a standalone instance is attached.
  tagsmap of string | null
  Key-value tags for the project
400Bad Request
Invalid project ID
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope
404Not Found
Project not found
500Internal Server Error
Internal server error

Fork a project

POST/v1/apps/{appId}/forksDeprecated

Legacy alias of /v1/projects/{projectId}/forks — projects were previously called apps. Creates a new project from this project's configuration and records this project as its source. The fork copies the spicepod the project deploys, its linked connections, project secrets, linked organization secrets, update channel, version range, replica and executor counts, storage size, description, and tags. It does not copy API keys (new ones are generated), deployments, the GitHub repository link, the instance size, or visibility (forks are private). The fork is not deployed: deploy it with POST /v1/projects/{projectId}/deployments. Requires apps:write. The server copies secret values without returning them, so no secrets scope is needed. A source connected to a GitHub repository is read from that repository, and its spicepod is copied only when it loads no other file from the repository; to deploy a fork from a fork of the repository, fork the project in the Spice portal.

Path parameters

Name	Type	Required	Description
`appId`	integer	Yes	The ID of the project to fork

Header parameters

Name	Type	Required	Description
`Authorization`	string	Yes	`Bearer <token>`. Authentication lists the tokens it accepts.
`X-Org-Name`	string	No	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 portal session token is bound to none, so it must send this header on every route but `GET /v1/orgs` (400 `org_assertion_required` otherwise). Pattern: `^[A-Za-z0-9._-]{1,255}$`

Request body

Optional

application/json

namestring
Name of the fork. Defaults to the source name with -fork, then -fork-2 and so on, whichever is free.
- Minimum length: 4
- Maximum length: 38
- Pattern: ^[a-zA-Z0-9-]+$
regionstring
Region to place the fork in. Omit it and cluster_name to place the fork where the source runs.
- Allowed values: us-east-1, us-west-2
cluster_namestring
Dedicated cluster to place the fork on, as listed by GET /v1/clusters. If region is also set, it must match the cluster's region.
scheduler_state_locationstring
s3:// URI for the fork's scheduler state. Required when the source spicepod sets runtime.scheduler.state_location, and must not overlap it: two schedulers cannot share a location.
- Maximum length: 2048
default_alertsboolean
Create default monitoring alerts for the new managed fork. False skips initial setup. Manual alert creation remains available.
- Default: true

Example request

curl -X POST "https://api.spice.ai/v1/apps/<appId>/forks" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "region": "us-east-1",
    "cluster_name": "string",
    "scheduler_state_location": "string",
    "default_alerts": true
  }'

Responses

201Created
Project forked. It has not been deployed yet.
application/json
- idinteger
  Unique identifier for the project
- namestring
  Name of the project
- kindstring
  Resolved project hosting model
  - Allowed values: managed, standalone, byoc
- descriptionstring | null
  Description of the project
- visibilitystring
  Visibility setting for the project
  - Allowed values: public, private
- created_atstring (date-time)
  Timestamp when the project was created
- cnamestring | null
  Region identifier
- cluster_namestring | null
  Resolved dedicated cluster name; null for projects not assigned to a dedicated cluster.
- endpointstring | null
  The data-plane endpoint the project connects to, or null before a standalone instance is attached.
- production_branchstring | null
  Production branch for the project
- api_keystringDeprecated
  Deprecated. Use the API Keys endpoints instead.
- tagsmap of string | null
  Key-value tags for the project
- forked_fromobject | null
  The project this project was forked from, while that project is live in the same organization. Null for a project that was not created as a fork.
  2 properties
  idintegerRequired
  ID of the source project
  namestringRequired
  Name of the source project
- paused_atstring (date-time) | null
  Timestamp when the project was paused; null while running
- warningstring | null
  Present when the project was created but initial configuration could not be applied
- configobject | null
  Runtime configuration; null for an unattached standalone project.
  10 properties
  spicepodobject | null
  Spicepod configuration
  registrystring | null
  Container registry for the runtime image
  image_tagstring | null
  Runtime image tag
  update_channelstring | null
  Update channel for the runtime
  Allowed values: stable, preview, nightly
  replicasinteger
  Number of replicas
  resourcesobject | null
  Resource requests and limits for the project container
  2 properties
  limitsobject
  3 properties
  cpustring
  Whole-number vCPU limit, or '-' for no CPU limit
  memorystring
  Memory limit in Gi (for example, 16Gi)
  ephemeral-storagestring
  requestsobject
  2 properties
  cpustring
  CPU request. Minimum 100 millicores (for example, 100m or 0.1).
  memorystring
  Memory request. Minimum 192Mi.
  executorobject | null
  Executor container configuration
  2 properties
  replicasinteger
  Number of executor replicas
  resourcesobject
  Resource requests and limits for the executor container
  2 properties
  limitsobject
  3 properties
  cpustring
  Whole-number vCPU limit, or '-' for no CPU limit
  memorystring
  Memory limit in Gi (for example, 16Gi)
  ephemeral-storagestring
  requestsobject
  2 properties
  cpustring
  CPU request. Minimum 100 millicores (for example, 100m or 0.1).
  memorystring
  Memory request. Minimum 192Mi.
  regionstring | null
  Cloud region code (e.g., us-east-1)
  node_groupstring | null
  Node group for scheduling the project runtime
  storage_claim_size_gbnumber | null
  Storage claim size in GB
- shared_statearray of objectRequired
  Settings copied as they are that name external state the source also uses: a replication slot or Kafka consumer group the spicepod names, or a snapshot location. Change them in the fork's spicepod before deploying it if the two projects should not share that state.
  3 properties
  componentstringRequired
  The dataset, or snapshots
  settingstringRequired
  Example: pg_replication_slot
  valuestringRequired
400Bad Request
Invalid project ID or request body, an unknown region or cluster, no region or cluster_name set for a source whose placement a fork cannot reuse (a BYOC cluster, a self-hosted runtime, or a region or cluster that is no longer available; code: fork_placement_required), or a missing or unusable scheduler_state_location (code: scheduler_state_location_required, scheduler_state_location_unsupported, scheduler_state_location_overlaps_source, or scheduler_state_location_not_applicable).
401Unauthorized
Unauthorized
402Payment Required
The source runs models on hosted AI credits, which the organization has used up (code: ai_credits_exhausted).
403Forbidden
Insufficient scope, a viewer role, or the source runs more replicas or executors than the plan or the dedicated cluster allows
404Not Found
Project or organization not found
409Conflict
A project with the requested name already exists, another project creation is in progress, or every default name is taken (code: fork_name_unavailable)
413Content Too Large
Request body too large
422Unprocessable Content
The source has no spicepod (code: fork_source_has_no_spicepod), its spicepod is not valid (code: fork_source_spicepod_invalid), or its spicepod loads files from its GitHub repository besides spicepod.yaml (code: fork_source_loads_repository_files)
429Too Many Requests
Too many project creation requests (rate limited)
500Internal Server Error
The fork could not be created. When the failure comes after the project row is created, the fork is deleted again with its spicepod, secrets, and organization secret links. If the project itself cannot be deleted, the response has code: fork_rollback_failed and names the partially created project in project (id and name). Delete that project, by project.id, before reusing its name.
502Bad Gateway
The source is connected to a GitHub repository, and its spicepod could not be read from it (code: fork_source_repository_unreadable)

Pause a project

POST/v1/apps/{appId}/pauseDeprecated

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.

Path parameters

Name	Type	Required	Description
`appId`	integer	Yes	The ID of the project to pause

Header parameters

Name	Type	Required	Description
`Authorization`	string	Yes	`Bearer <token>`. Authentication lists the tokens it accepts.
`X-Org-Name`	string	No	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 portal session token is bound to none, so it must send this header on every route but `GET /v1/orgs` (400 `org_assertion_required` otherwise). Pattern: `^[A-Za-z0-9._-]{1,255}$`

Example request

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

Responses

200OK
Project paused
application/json
- idintegerRequired
  The project ID
- namestringRequired
  The project name
- paused_atstring (date-time)Required
  Timestamp when the project was paused
400Bad Request
Invalid project ID, missing API key, no spicepod configured, or spicepod has been deleted
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope
404Not Found
Project not found
409Conflict
Project is already paused
application/json
- errorstringRequired
- paused_atstring (date-time)Required
  Timestamp of the existing pause
500Internal Server Error
Internal server error

Resume a paused project

POST/v1/apps/{appId}/resumeDeprecated

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. A project connected to a GitHub repository deploys spicepod.yaml from its root directory on its production branch, read when the project resumes. Requires apps:write.

Path parameters

Name	Type	Required	Description
`appId`	integer	Yes	The ID of the project to resume

Header parameters

Name	Type	Required	Description
`Authorization`	string	Yes	`Bearer <token>`. Authentication lists the tokens it accepts.
`X-Org-Name`	string	No	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 portal session token is bound to none, so it must send this header on every route but `GET /v1/orgs` (400 `org_assertion_required` otherwise). Pattern: `^[A-Za-z0-9._-]{1,255}$`

Example request

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

Responses

200OK
Project resumed, deployment created
application/json
- idintegerRequired
  The project ID
- namestringRequired
  The project name
- paused_atstring (date-time) | nullRequired
  Always null after a successful resume
- deployment_idintegerRequired
  ID of the deployment created to bring the runtime back up
400Bad Request
Invalid project ID, missing API key, missing project organization, no spicepod configured, spicepod has been deleted, or the spicepod name, kind or version is missing or not valid (the body carries an issues array of {path, message}). For a project connected to a GitHub repository, also returned when the root directory has no spicepod.yaml or it is invalid or too large (code: spicepod_not_found, spicepod_invalid or spicepod_too_large). The project stays paused.
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope, or the org's GitHub App installation cannot read the connected repository (code: github_unauthorized or github_forbidden). The project stays paused.
404Not Found
Project not found, or the connected GitHub repository or its production branch was not found (code: github_not_found). The project stays paused.
409Conflict
Project is not paused
422Unprocessable Content
No runtime version in the catalog matches this project’s version range (code: version_no_match), or the spicepod uses version v1beta1, which the Spice 2 runtime cannot load (code: spicepod_version_unsupported). Also returned when the spicepod uses a connection credential that holds a secret reference deploy cannot resolve (code: connection_credentials_unresolved, with an unresolved_credentials array of {connection, field}). The project stays paused.
429Too Many Requests
GitHub rate-limited the read of the connected repository (code: github_rate_limited). The project stays paused.
500Internal Server Error
Internal server error
502Bad Gateway
GitHub did not answer while the connected repository was read (code: github_unavailable). The project stays paused.
503Service Unavailable
The runtime version catalog is unavailable or empty (code: version_source_unavailable), so an unpinned stable or preview resume cannot resolve an image tag.

Connect a project to a GitHub repository

PUT/v1/apps/{appId}/repositoryDeprecated

Legacy alias of /v1/projects/{projectId}/repository — projects were previously called apps. Connects the project to a repository in the organization's GitHub account, through the organization's Spice Cloud GitHub App installation. The next deployment reads spicepod.yaml (or spicepod.yml) from root_directory on production_branch. Connecting sets the project description to the repository description. Connecting again replaces the repository, root directory and production branch. Requires apps:write.

Path parameters

Name	Type	Required	Description
`appId`	integer	Yes	The ID of the project to connect

Header parameters

Name	Type	Required	Description
`Authorization`	string	Yes	`Bearer <token>`. Authentication lists the tokens it accepts.
`X-Org-Name`	string	No	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 portal session token is bound to none, so it must send this header on every route but `GET /v1/orgs` (400 `org_assertion_required` otherwise). Pattern: `^[A-Za-z0-9._-]{1,255}$`

Request body

Required

application/json

repositorystringRequired
Repository in the organization's GitHub account, as name or owner/name. The owner must be the organization's GitHub account.
- Example: cookbook
root_directorystring | null
Directory inside the repository that contains spicepod.yaml. Omit it, or send null or an empty string, for the repository root.
- Maximum length: 512
- Example: cayenne
production_branchstring
Branch that deployments read. Defaults to the repository's default branch. A branch that GitHub renamed is stored under its new name.
- Maximum length: 255
- Example: trunk

Example request

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

Responses

200OK
Project connected
application/json
- project_idintegerRequired
  The project ID
- repositorystringRequired
  The repository as owner/name
- repository_idintegerRequired
  The GitHub repository ID
- root_directorystring | nullRequired
  The stored root directory. Null is the repository root.
- production_branchstringRequired
  The branch that deployments read
- connected_atstring (date-time)Required
  When the project was connected
- has_spicepodbooleanRequired
  True when spicepod.yaml or spicepod.yml exists in the root directory on the production branch. A deployment fails until it does.
400Bad Request
Invalid project ID or request body, a repository outside the organization's GitHub account (code: invalid_repository), or a root directory outside the repository (code: invalid_root_directory)
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope, or viewer role cannot mutate projects
404Not Found
Project not found, or the organization's GitHub App installation cannot read the repository (code: repository_not_found)
409Conflict
The organization has no usable GitHub App installation (code: github_not_connected), or another project already deploys this repository and root directory (code: root_directory_conflict)
413Content Too Large
Request body too large
422Unprocessable Content
The repository has no branch named production_branch (code: branch_not_found), the project has no spicepod configuration (code: spicepod_missing), or the organization is not fully configured
500Internal Server Error
Internal server error
503Service Unavailable
GitHub did not answer (code: github_unavailable)

Get project metrics

GET/v1/apps/{appId}/metricsDeprecated

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.

Path parameters

Name	Type	Required	Description
`appId`	integer	Yes	The ID of the project

Query parameters

Name	Type	Required	Description
`window`	string	No	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.

Header parameters

Name	Type	Required	Description
`Authorization`	string	Yes	`Bearer <token>`. Authentication lists the tokens it accepts.
`X-Org-Name`	string	No	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 portal session token is bound to none, so it must send this header on every route but `GET /v1/orgs` (400 `org_assertion_required` otherwise). Pattern: `^[A-Za-z0-9._-]{1,255}$`

Example request

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

Responses

200OK
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
- ingestionobject
  Aggregated data ingestion metrics
  2 properties
  rows_ingestednumber
  Total rows ingested (without window) or rows per second (with window)
  bytes_ingestednumber
  Total bytes ingested (without window) or bytes per second (with window)
- clusterobject
  Cluster metrics for the project
  1 property
  active_executors_countnumber
  Number of active executors registered with the scheduler
- metricsmap of object
  Resource metrics keyed by pod name
  6 properties
  cpu_usage_percentnumber
  CPU usage as a percentage (0-100)
  memory_usage_bytesnumber
  Memory usage in bytes
  disk_read_bytesnumber
  Disk bytes read per second (with window) or cumulative (without window)
  disk_read_operationsnumber
  Disk read operations per second (with window) or cumulative count (without window)
  disk_write_bytesnumber
  Disk bytes written per second (with window) or cumulative (without window)
  disk_write_operationsnumber
  Disk write operations per second (with window) or cumulative count (without window)
400Bad Request
Invalid project ID
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope
404Not Found
Project or organization not found
422Unprocessable Content
Organization is not fully configured
500Internal Server Error
Internal server error
503Service Unavailable
Metrics service unavailable

List project instances

GET/v1/apps/{appId}/instancesDeprecated

Legacy alias of /v1/projects/{projectId}/instances — projects were previously called apps. Lists the runtime instances of a deployed project, newest first. A managed or BYOC project lists its Spicepod instances. A standalone project lists its Cloud Connect runtime. Read the logs of an instance with GET /v1/projects/{projectId}/instances/{instanceName}/logs.

Path parameters

Name	Type	Required	Description
`appId`	integer	Yes	The ID of the project

Header parameters

Name	Type	Required	Description
`Authorization`	string	Yes	`Bearer <token>`. Authentication lists the tokens it accepts.
`X-Org-Name`	string	No	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 portal session token is bound to none, so it must send this header on every route but `GET /v1/orgs` (400 `org_assertion_required` otherwise). Pattern: `^[A-Za-z0-9._-]{1,255}$`

Example request

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

Responses

200OK
The project's instances
application/json
- instancesarray of objectRequired
  3 properties
  namestringRequired
  The instance name: a Spicepod instance (pod) name, or a Cloud Connect runtime id. Pass it as instanceName to read its logs.
  statusstringRequired
  A Spicepod instance is deploying, loading, ready, unhealthy, terminating, failed, or failed_to_start. A Cloud Connect runtime is online or offline.
  Allowed values: deploying, loading, ready, unhealthy, terminating, failed, failed_to_start, online, offline
  started_atstring (date-time) | nullRequired
  When the Spicepod instance started, or when the Cloud Connect runtime enrolled.
400Bad Request
Invalid project ID
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope
404Not Found
Project not found
409Conflict
The project has no running instances. code is project_not_deployed when a managed or BYOC project was never deployed, or project_paused when the project is paused.
application/json
- errorstringRequired
- codestringRequired
  - Allowed values: project_not_deployed, project_paused
422Unprocessable Content
The project is not fully configured
500Internal Server Error
Internal server error
503Service Unavailable
The project runtime did not answer

Get project instance logs

GET/v1/apps/{appId}/instances/{instanceName}/logsDeprecated

Legacy alias of /v1/projects/{projectId}/instances/{instanceName}/logs — projects were previously called apps. Returns the most recent log lines of one instance of a deployed project, oldest first, without color codes. The org's plan sets the largest tail. List the instance names with GET /v1/projects/{projectId}/instances.

Path parameters

Name	Type	Required	Description
`appId`	integer	Yes	The ID of the project
`instanceName`	string	Yes	The instance name from `GET /v1/projects/{projectId}/instances`

Query parameters

Name	Type	Required	Description
`tail`	integer	No	How many of the most recent lines to return Default: `100` Minimum: `1`

Header parameters

Name	Type	Required	Description
`Authorization`	string	Yes	`Bearer <token>`. Authentication lists the tokens it accepts.
`X-Org-Name`	string	No	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 portal session token is bound to none, so it must send this header on every route but `GET /v1/orgs` (400 `org_assertion_required` otherwise). Pattern: `^[A-Za-z0-9._-]{1,255}$`

Example request

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

Responses

200OK
The instance's most recent log lines
application/json
- instancestringRequired
  The instance name
- tailintegerRequired
  The number of lines asked for
- linesarray of stringRequired
  Log lines, oldest first
400Bad Request
Invalid project ID or tail
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope (code is insufficient_scope), or tail is larger than the org's plan allows (code is plan_limit, and max_tail is the largest allowed tail).
application/json
- errorstringRequired
- codestringRequired
- max_tailinteger
404Not Found
The project was not found, or the instance is not one of the project's instances (code is instance_not_found).
409Conflict
The logs cannot be read in the project's current state. code is project_not_deployed when the project was never deployed, project_paused when it is paused, or instance_offline when the Cloud Connect runtime is offline and does not answer.
application/json
- errorstringRequired
- codestringRequired
  - Allowed values: project_not_deployed, project_paused, instance_offline
422Unprocessable Content
The project is not fully configured
500Internal Server Error
Internal server error
503Service Unavailable
The project runtime did not answer