# Create a project

## `POST /v1/projects`

Creates a new project in the authenticated organization.

### Header parameters

- `Authorization` (string, required): `Bearer <token>`. [Authentication](https://spice.ai/docs/cloud/api/management#authentication) lists the tokens it accepts.
- `X-Org-Name` (string, optional): 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.

Content type: `application/json`

- `name` (string, required): Project name (letters, numbers, hyphens only). Minimum length: `4`. Pattern: `^[a-zA-Z0-9-]+$`.
- `region` (string): 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`.
- `cname` (string): **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_name` (string): 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.
- `description` (string): Project description
- `visibility` (string): Allowed values: `public`, `private`. Default: `private`.
- `default_alerts` (boolean): Create default monitoring alerts for the new managed project. False skips initial setup. Manual alert creation remains available. Default: `true`.
- `tags` (map of string): Key-value tags for the project
- `update_channel` (string): 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`.
- `replicas` (integer): Number of replicas for a managed project. Rejected for standalone projects. Minimum: `0`.
- `resources` (object): Resource requests and limits for a managed project container. Rejected for standalone projects.
  - `limits` (object)
    - `cpu` (string): Whole-number vCPU limit, or '-' for no CPU limit
    - `memory` (string): Memory limit in Gi (for example, 16Gi)
    - `ephemeral-storage` (string): Ephemeral storage limit in Gi (for example, 8Gi)
  - `requests` (object)
    - `cpu` (string): CPU request. Minimum 100 millicores (for example, 100m or 0.1).
    - `memory` (string): Memory request. Minimum 192Mi.
- `executor` (object): Executor container configuration for a managed project. Rejected for standalone projects.
  - `replicas` (integer): Number of executor replicas. Minimum: `0`.
  - `resources` (object): Resource requests and limits for the executor container
    - `limits` (object)
      - `cpu` (string): Whole-number vCPU limit, or '-' for no CPU limit
      - `memory` (string): Memory limit in Gi (for example, 16Gi)
      - `ephemeral-storage` (string): Ephemeral storage limit in Gi (for example, 8Gi)
    - `requests` (object)
      - `cpu` (string): CPU request. Minimum 100 millicores (for example, 100m or 0.1).
      - `memory` (string): Memory request. Minimum 192Mi.

### Example request

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

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

{
  "name": "string"
}
```

### Responses

**201 Created**

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

Content type: `application/json`

- `id` (integer): Unique identifier for the project
- `name` (string): Name of the project
- `kind` (string): Resolved project hosting model. Allowed values: `managed`, `standalone`, `byoc`.
- `description` (string | null): Description of the project
- `visibility` (string): Visibility setting for the project. Allowed values: `public`, `private`.
- `created_at` (string (date-time)): Timestamp when the project was created
- `cname` (string | null): Region identifier
- `cluster_name` (string | null): Resolved dedicated cluster name; null for projects not assigned to a dedicated cluster.
- `endpoint` (string | null): The data-plane endpoint the project connects to, or null before a standalone instance is attached.
- `production_branch` (string | null): Production branch for the project
- `api_key` (string, deprecated): Deprecated. Use the API Keys endpoints instead.
- `tags` (map of string | null): Key-value tags for the project
- `forked_from` (object | 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.
  - `id` (integer, required): ID of the source project
  - `name` (string, required): Name of the source project
- `paused_at` (string (date-time) | null): Timestamp when the project was paused; null while running
- `warning` (string | null): Present when the project was created but initial configuration could not be applied
- `config` (object | null): Runtime configuration; null for an unattached standalone project.
  - `spicepod` (object | null): Spicepod configuration
  - `registry` (string | null): Container registry for the runtime image
  - `image_tag` (string | null): Runtime image tag
  - `update_channel` (string | null): Update channel for the runtime. Allowed values: `stable`, `preview`, `nightly`.
  - `replicas` (integer): Number of replicas
  - `resources` (object | null): Resource requests and limits for the project container
    - `limits` (object)
      - `cpu` (string): Whole-number vCPU limit, or '-' for no CPU limit
      - `memory` (string): Memory limit in Gi (for example, 16Gi)
      - `ephemeral-storage` (string)
    - `requests` (object)
      - `cpu` (string): CPU request. Minimum 100 millicores (for example, 100m or 0.1).
      - `memory` (string): Memory request. Minimum 192Mi.
  - `executor` (object | null): Executor container configuration
    - `replicas` (integer): Number of executor replicas
    - `resources` (object): Resource requests and limits for the executor container
      - `limits` (object)
        - `cpu` (string): Whole-number vCPU limit, or '-' for no CPU limit
        - `memory` (string): Memory limit in Gi (for example, 16Gi)
        - `ephemeral-storage` (string)
      - `requests` (object)
        - `cpu` (string): CPU request. Minimum 100 millicores (for example, 100m or 0.1).
        - `memory` (string): Memory request. Minimum 192Mi.
  - `region` (string | null): Cloud region code (e.g., us-east-1)
  - `node_group` (string | null): Node group for scheduling the project runtime
  - `storage_claim_size_gb` (number | null): Storage claim size in GB

**400 Bad Request**

Invalid request body or invalid region

**401 Unauthorized**

Unauthorized

**403 Forbidden**

Insufficient scope, dedicated-cluster assignment or special-org private-compute ceilings required for resource limits, or requested resources exceed dedicated-cluster capacity

**409 Conflict**

A project with this name already exists, or the project was deleted while its initial configuration was being written (`code` is `project_deleted`)

**429 Too Many Requests**

Too many project creation requests (rate limited)

**500 Internal Server Error**

Project creation failed, including when the name-collision check could not be read

Content type: `application/json`

- `error` (string, required): Generic failure reason; the underlying cause stays in the server logs. Example: `Failed to create project`.

## `POST /v1/orgs/{orgId}/projects`

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

### Path parameters

- `orgId` (integer, required): The org id from GET /v1/orgs. Minimum: `1`.

### Header parameters

- `Authorization` (string, required): `Bearer <token>`. [Authentication](https://spice.ai/docs/cloud/api/management#authentication) lists the tokens it accepts.
- `X-Org-Name` (string, optional): 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.

Content type: `application/json`

- `name` (string, required): Project name (letters, numbers, hyphens only). Minimum length: `4`. Pattern: `^[a-zA-Z0-9-]+$`.
- `region` (string): 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`.
- `cname` (string): **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_name` (string): 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.
- `description` (string): Project description
- `visibility` (string): Allowed values: `public`, `private`. Default: `private`.
- `default_alerts` (boolean): Create default monitoring alerts for the new managed project. False skips initial setup. Manual alert creation remains available. Default: `true`.
- `tags` (map of string): Key-value tags for the project
- `update_channel` (string): 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`.
- `replicas` (integer): Number of replicas for a managed project. Rejected for standalone projects. Minimum: `0`.
- `resources` (object): Resource requests and limits for a managed project container. Rejected for standalone projects.
  - `limits` (object)
    - `cpu` (string): Whole-number vCPU limit, or '-' for no CPU limit
    - `memory` (string): Memory limit in Gi (for example, 16Gi)
    - `ephemeral-storage` (string): Ephemeral storage limit in Gi (for example, 8Gi)
  - `requests` (object)
    - `cpu` (string): CPU request. Minimum 100 millicores (for example, 100m or 0.1).
    - `memory` (string): Memory request. Minimum 192Mi.
- `executor` (object): Executor container configuration for a managed project. Rejected for standalone projects.
  - `replicas` (integer): Number of executor replicas. Minimum: `0`.
  - `resources` (object): Resource requests and limits for the executor container
    - `limits` (object)
      - `cpu` (string): Whole-number vCPU limit, or '-' for no CPU limit
      - `memory` (string): Memory limit in Gi (for example, 16Gi)
      - `ephemeral-storage` (string): Ephemeral storage limit in Gi (for example, 8Gi)
    - `requests` (object)
      - `cpu` (string): CPU request. Minimum 100 millicores (for example, 100m or 0.1).
      - `memory` (string): Memory request. Minimum 192Mi.

### Example request

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

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

{
  "name": "string"
}
```

### Responses

**201 Created**

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

Content type: `application/json`

- `id` (integer): Unique identifier for the project
- `name` (string): Name of the project
- `kind` (string): Resolved project hosting model. Allowed values: `managed`, `standalone`, `byoc`.
- `description` (string | null): Description of the project
- `visibility` (string): Visibility setting for the project. Allowed values: `public`, `private`.
- `created_at` (string (date-time)): Timestamp when the project was created
- `cname` (string | null): Region identifier
- `cluster_name` (string | null): Resolved dedicated cluster name; null for projects not assigned to a dedicated cluster.
- `endpoint` (string | null): The data-plane endpoint the project connects to, or null before a standalone instance is attached.
- `production_branch` (string | null): Production branch for the project
- `api_key` (string, deprecated): Deprecated. Use the API Keys endpoints instead.
- `tags` (map of string | null): Key-value tags for the project
- `forked_from` (object | 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.
  - `id` (integer, required): ID of the source project
  - `name` (string, required): Name of the source project
- `paused_at` (string (date-time) | null): Timestamp when the project was paused; null while running
- `warning` (string | null): Present when the project was created but initial configuration could not be applied
- `config` (object | null): Runtime configuration; null for an unattached standalone project.
  - `spicepod` (object | null): Spicepod configuration
  - `registry` (string | null): Container registry for the runtime image
  - `image_tag` (string | null): Runtime image tag
  - `update_channel` (string | null): Update channel for the runtime. Allowed values: `stable`, `preview`, `nightly`.
  - `replicas` (integer): Number of replicas
  - `resources` (object | null): Resource requests and limits for the project container
    - `limits` (object)
      - `cpu` (string): Whole-number vCPU limit, or '-' for no CPU limit
      - `memory` (string): Memory limit in Gi (for example, 16Gi)
      - `ephemeral-storage` (string)
    - `requests` (object)
      - `cpu` (string): CPU request. Minimum 100 millicores (for example, 100m or 0.1).
      - `memory` (string): Memory request. Minimum 192Mi.
  - `executor` (object | null): Executor container configuration
    - `replicas` (integer): Number of executor replicas
    - `resources` (object): Resource requests and limits for the executor container
      - `limits` (object)
        - `cpu` (string): Whole-number vCPU limit, or '-' for no CPU limit
        - `memory` (string): Memory limit in Gi (for example, 16Gi)
        - `ephemeral-storage` (string)
      - `requests` (object)
        - `cpu` (string): CPU request. Minimum 100 millicores (for example, 100m or 0.1).
        - `memory` (string): Memory request. Minimum 192Mi.
  - `region` (string | null): Cloud region code (e.g., us-east-1)
  - `node_group` (string | null): Node group for scheduling the project runtime
  - `storage_claim_size_gb` (number | null): Storage claim size in GB

**400 Bad 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`).

**401 Unauthorized**

Unauthorized

**403 Forbidden**

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`).

**409 Conflict**

A project with this name already exists, or the project was deleted while its initial configuration was being written (`code` is `project_deleted`)

**429 Too Many Requests**

Too many project creation requests (rate limited)

**500 Internal Server Error**

Project creation failed, including when the name-collision check could not be read

Content type: `application/json`

- `error` (string, required): Generic failure reason; the underlying cause stays in the server logs. Example: `Failed to create project`.

## `POST /v1/apps` (deprecated)

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

### Header parameters

- `Authorization` (string, required): `Bearer <token>`. [Authentication](https://spice.ai/docs/cloud/api/management#authentication) lists the tokens it accepts.
- `X-Org-Name` (string, optional): 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.

Content type: `application/json`

- `name` (string, required): Project name (letters, numbers, hyphens only). Minimum length: `4`. Pattern: `^[a-zA-Z0-9-]+$`.
- `region` (string): 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`.
- `cname` (string): **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_name` (string): 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.
- `description` (string): Project description
- `visibility` (string): Allowed values: `public`, `private`. Default: `private`.
- `default_alerts` (boolean): Create default monitoring alerts for the new managed project. False skips initial setup. Manual alert creation remains available. Default: `true`.
- `tags` (map of string): Key-value tags for the project
- `update_channel` (string): 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`.
- `replicas` (integer): Number of replicas for a managed project. Rejected for standalone projects. Minimum: `0`.
- `resources` (object): Resource requests and limits for a managed project container. Rejected for standalone projects.
  - `limits` (object)
    - `cpu` (string): Whole-number vCPU limit, or '-' for no CPU limit
    - `memory` (string): Memory limit in Gi (for example, 16Gi)
    - `ephemeral-storage` (string): Ephemeral storage limit in Gi (for example, 8Gi)
  - `requests` (object)
    - `cpu` (string): CPU request. Minimum 100 millicores (for example, 100m or 0.1).
    - `memory` (string): Memory request. Minimum 192Mi.
- `executor` (object): Executor container configuration for a managed project. Rejected for standalone projects.
  - `replicas` (integer): Number of executor replicas. Minimum: `0`.
  - `resources` (object): Resource requests and limits for the executor container
    - `limits` (object)
      - `cpu` (string): Whole-number vCPU limit, or '-' for no CPU limit
      - `memory` (string): Memory limit in Gi (for example, 16Gi)
      - `ephemeral-storage` (string): Ephemeral storage limit in Gi (for example, 8Gi)
    - `requests` (object)
      - `cpu` (string): CPU request. Minimum 100 millicores (for example, 100m or 0.1).
      - `memory` (string): Memory request. Minimum 192Mi.

### Example request

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

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

{
  "name": "string"
}
```

### Responses

**201 Created**

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

Content type: `application/json`

- `id` (integer): Unique identifier for the project
- `name` (string): Name of the project
- `kind` (string): Resolved project hosting model. Allowed values: `managed`, `standalone`, `byoc`.
- `description` (string | null): Description of the project
- `visibility` (string): Visibility setting for the project. Allowed values: `public`, `private`.
- `created_at` (string (date-time)): Timestamp when the project was created
- `cname` (string | null): Region identifier
- `cluster_name` (string | null): Resolved dedicated cluster name; null for projects not assigned to a dedicated cluster.
- `endpoint` (string | null): The data-plane endpoint the project connects to, or null before a standalone instance is attached.
- `production_branch` (string | null): Production branch for the project
- `api_key` (string, deprecated): Deprecated. Use the API Keys endpoints instead.
- `tags` (map of string | null): Key-value tags for the project
- `forked_from` (object | 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.
  - `id` (integer, required): ID of the source project
  - `name` (string, required): Name of the source project
- `paused_at` (string (date-time) | null): Timestamp when the project was paused; null while running
- `warning` (string | null): Present when the project was created but initial configuration could not be applied
- `config` (object | null): Runtime configuration; null for an unattached standalone project.
  - `spicepod` (object | null): Spicepod configuration
  - `registry` (string | null): Container registry for the runtime image
  - `image_tag` (string | null): Runtime image tag
  - `update_channel` (string | null): Update channel for the runtime. Allowed values: `stable`, `preview`, `nightly`.
  - `replicas` (integer): Number of replicas
  - `resources` (object | null): Resource requests and limits for the project container
    - `limits` (object)
      - `cpu` (string): Whole-number vCPU limit, or '-' for no CPU limit
      - `memory` (string): Memory limit in Gi (for example, 16Gi)
      - `ephemeral-storage` (string)
    - `requests` (object)
      - `cpu` (string): CPU request. Minimum 100 millicores (for example, 100m or 0.1).
      - `memory` (string): Memory request. Minimum 192Mi.
  - `executor` (object | null): Executor container configuration
    - `replicas` (integer): Number of executor replicas
    - `resources` (object): Resource requests and limits for the executor container
      - `limits` (object)
        - `cpu` (string): Whole-number vCPU limit, or '-' for no CPU limit
        - `memory` (string): Memory limit in Gi (for example, 16Gi)
        - `ephemeral-storage` (string)
      - `requests` (object)
        - `cpu` (string): CPU request. Minimum 100 millicores (for example, 100m or 0.1).
        - `memory` (string): Memory request. Minimum 192Mi.
  - `region` (string | null): Cloud region code (e.g., us-east-1)
  - `node_group` (string | null): Node group for scheduling the project runtime
  - `storage_claim_size_gb` (number | null): Storage claim size in GB

**400 Bad Request**

Invalid request body or invalid region

**401 Unauthorized**

Unauthorized

**403 Forbidden**

Insufficient scope, dedicated-cluster assignment or special-org private-compute ceilings required for resource limits, or requested resources exceed dedicated-cluster capacity

**409 Conflict**

A project with this name already exists, or the project was deleted while its initial configuration was being written (`code` is `project_deleted`)

**429 Too Many Requests**

Too many project creation requests (rate limited)

**500 Internal Server Error**

Project creation failed, including when the name-collision check could not be read

Content type: `application/json`

- `error` (string, required): Generic failure reason; the underlying cause stays in the server logs. Example: `Failed to create project`.

OpenAPI: [api.spice.ai/openapi.json](https://api.spice.ai/openapi.json)