Create a project

POST`https://api.spice.ai/v1/projects`

Creates a new project in the authenticated organization.

Authorizations

AuthorizationstringRequired
Bearer <token>. Authentication lists the tokens it accepts.

Header parameters

X-Org-Namestring
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}$

Body

application/jsonRequired

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.

Responses

201Createdapplication/json

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

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

400Invalid request body or invalid region

401Unauthorized

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 project creation requests (rate limited)

500Project creation failed, including when the name-collision check could not be readapplication/json

errorstringRequired
Generic failure reason; the underlying cause stays in the server logs
- Example: Failed to create project

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

POST /v1/projects HTTP/1.1
Host: api.spice.ai
Authorization: Bearer <token>
Content-Type: application/json
Content-Length: 22

{
  "name": "string"
}

{
  "id": 0,
  "name": "string",
  "kind": "managed",
  "description": "string",
  "visibility": "public",
  "created_at": "2026-01-01T00:00:00Z",
  "cname": "string",
  "cluster_name": "string",
  "endpoint": "string",
  "production_branch": "string",
  "api_key": "string",
  "tags": {},
  "forked_from": {
    "id": 0,
    "name": "string"
  },
  "paused_at": "2026-01-01T00:00:00Z",
  "warning": "string",
  "config": {
    "spicepod": {},
    "registry": "string",
    "image_tag": "string",
    "update_channel": "stable",
    "replicas": 0,
    "resources": {
      "limits": {
        "cpu": "string",
        "memory": "string",
        "ephemeral-storage": "string"
      },
      "requests": {
        "cpu": "string",
        "memory": "string"
      }
    },
    "executor": {
      "replicas": 0,
      "resources": {
        "limits": {
          "cpu": "string",
          "memory": "string",
          "ephemeral-storage": "string"
        },
        "requests": {
          "cpu": "string",
          "memory": "string"
        }
      }
    },
    "region": "string",
    "node_group": "string",
    "storage_claim_size_gb": 0
  }
}

application/json

{
  "error": "Failed to create project"
}

application/json

POST`https://api.spice.ai/v1/orgs/{orgId}/projects`

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

Authorizations

AuthorizationstringRequired
Bearer <token>. Authentication lists the tokens it accepts.

Path parameters

orgIdintegerRequired
The org id from GET /v1/orgs
- Minimum: 1

Header parameters

X-Org-Namestring
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}$

Body

application/jsonRequired

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.

Responses

201Createdapplication/json

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

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

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 project creation requests (rate limited)

500Project creation failed, including when the name-collision check could not be readapplication/json

errorstringRequired
Generic failure reason; the underlying cause stays in the server logs
- Example: Failed to create project

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

POST /v1/orgs/<orgId>/projects HTTP/1.1
Host: api.spice.ai
Authorization: Bearer <token>
Content-Type: application/json
Content-Length: 22

{
  "name": "string"
}

{
  "id": 0,
  "name": "string",
  "kind": "managed",
  "description": "string",
  "visibility": "public",
  "created_at": "2026-01-01T00:00:00Z",
  "cname": "string",
  "cluster_name": "string",
  "endpoint": "string",
  "production_branch": "string",
  "api_key": "string",
  "tags": {},
  "forked_from": {
    "id": 0,
    "name": "string"
  },
  "paused_at": "2026-01-01T00:00:00Z",
  "warning": "string",
  "config": {
    "spicepod": {},
    "registry": "string",
    "image_tag": "string",
    "update_channel": "stable",
    "replicas": 0,
    "resources": {
      "limits": {
        "cpu": "string",
        "memory": "string",
        "ephemeral-storage": "string"
      },
      "requests": {
        "cpu": "string",
        "memory": "string"
      }
    },
    "executor": {
      "replicas": 0,
      "resources": {
        "limits": {
          "cpu": "string",
          "memory": "string",
          "ephemeral-storage": "string"
        },
        "requests": {
          "cpu": "string",
          "memory": "string"
        }
      }
    },
    "region": "string",
    "node_group": "string",
    "storage_claim_size_gb": 0
  }
}

application/json

{
  "error": "Failed to create project"
}

application/json

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

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

Authorizations

AuthorizationstringRequired
Bearer <token>. Authentication lists the tokens it accepts.

Header parameters

X-Org-Namestring
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}$

Body

application/jsonRequired

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.

Responses

201Createdapplication/json

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

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

400Invalid request body or invalid region

401Unauthorized

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 project creation requests (rate limited)

500Project creation failed, including when the name-collision check could not be readapplication/json

errorstringRequired
Generic failure reason; the underlying cause stays in the server logs
- Example: Failed to create project

OpenAPIapi.spice.ai/openapi.json

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

POST /v1/apps HTTP/1.1
Host: api.spice.ai
Authorization: Bearer <token>
Content-Type: application/json
Content-Length: 22

{
  "name": "string"
}

{
  "id": 0,
  "name": "string",
  "kind": "managed",
  "description": "string",
  "visibility": "public",
  "created_at": "2026-01-01T00:00:00Z",
  "cname": "string",
  "cluster_name": "string",
  "endpoint": "string",
  "production_branch": "string",
  "api_key": "string",
  "tags": {},
  "forked_from": {
    "id": 0,
    "name": "string"
  },
  "paused_at": "2026-01-01T00:00:00Z",
  "warning": "string",
  "config": {
    "spicepod": {},
    "registry": "string",
    "image_tag": "string",
    "update_channel": "stable",
    "replicas": 0,
    "resources": {
      "limits": {
        "cpu": "string",
        "memory": "string",
        "ephemeral-storage": "string"
      },
      "requests": {
        "cpu": "string",
        "memory": "string"
      }
    },
    "executor": {
      "replicas": 0,
      "resources": {
        "limits": {
          "cpu": "string",
          "memory": "string",
          "ephemeral-storage": "string"
        },
        "requests": {
          "cpu": "string",
          "memory": "string"
        }
      }
    },
    "region": "string",
    "node_group": "string",
    "storage_claim_size_gb": 0
  }
}

application/json

{
  "error": "Failed to create project"
}

application/json

POSThttps://api.spice.ai/v1/projects

Authorizations

Header parameters

Body

Responses

POSThttps://api.spice.ai/v1/orgs/{orgId}/projects

Authorizations

Path parameters

Header parameters

Body

Responses

POSThttps://api.spice.ai/v1/appsDeprecated

Authorizations

Header parameters

Body

Responses

POST`https://api.spice.ai/v1/projects`

POST`https://api.spice.ai/v1/orgs/{orgId}/projects`

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