diff --git a/cloud/api/management/README.md b/cloud/api/management/README.md index 46735c3..d37c8eb 100644 --- a/cloud/api/management/README.md +++ b/cloud/api/management/README.md @@ -5,7 +5,13 @@ icon: code # Management APIs -The Spice.ai Management API (also known as the control-plane API) provides programmatic access to manage Spice.ai Cloud resources—apps, deployments, secrets, API keys, and organization members. +The Spice.ai Management API (also known as the control-plane API) provides programmatic access to manage Spice.ai Cloud resources—projects, deployments, secrets, API keys, and organization members. + +{% hint style="info" %} +**Projects were previously called apps.** Every `/v1/projects` endpoint is also served at the legacy `/v1/apps` path, which remains supported. Existing integrations continue to work without changes. + +The legacy paths are marked deprecated in the OpenAPI specification, and new integrations should use `/v1/projects`. See [Projects and apps](#projects-and-apps). +{% endhint %} ## Base URL @@ -21,6 +27,24 @@ All API endpoints are versioned under `/v1`: https://api.spice.ai/v1 ``` +## Projects and apps + +What the API and portal now call a **project** was previously called an **app**. The resource is unchanged — only the name is different. + +Both path prefixes reach the same handlers: + +| Path | Status | List response envelope | +| ------------------------ | --------------------- | ---------------------- | +| `/v1/projects` | Canonical | `{ "projects": [...] }` | +| `/v1/apps` | Legacy, still served | `{ "apps": [...] }` | + +Two details matter when migrating: + +* **The list envelope differs.** `GET /v1/projects` returns results under a `projects` key, while `GET /v1/apps` keeps its original `apps` key. A client switching to the canonical path must read the new key. All other response shapes and field names are identical, including the `id` and `name` fields on each resource. +* **OAuth scope names are unchanged.** The scopes are still `apps:read`, `apps:write`, and `apps:delete`, because they are embedded in already-issued tokens. They grant access to projects under either path. + +The Spice CLI, Terraform provider, and SDKs continue to call the legacy paths and are unaffected. + ## Authentication The Management API supports three authentication methods: @@ -44,7 +68,7 @@ PATs are long-lived, user-scoped tokens. Recommended for: ```bash curl -H "Authorization: Bearer " \ - https://api.spice.ai/v1/apps + https://api.spice.ai/v1/projects ``` Learn more: [Personal Access Tokens](../../../portal/profile/personal-access-tokens.md) @@ -84,7 +108,7 @@ The response contains an `access_token`: ```bash curl -H "Authorization: Bearer " \ - https://api.spice.ai/v1/apps + https://api.spice.ai/v1/projects ``` ### 3. User Session Tokens (CLI) @@ -102,15 +126,15 @@ Access to API resources is controlled through scopes. PATs and OAuth clients mus | Scope | Description | | ------------------- | ------------------------------------------------------------- | | `*` | Full access to all resources (not recommended for production) | -| `apps:read` | Read app information | -| `apps:write` | Create and update apps | -| `apps:delete` | Delete apps | +| `apps:read` | Read project information | +| `apps:write` | Create and update projects | +| `apps:delete` | Delete projects | | `deployments:read` | View deployment status and history | | `deployments:write` | Create new deployments | | `secrets:read` | List and view secrets (values are masked) | | `secrets:write` | Create, update, and delete secrets | -| `config:read` | Read app configuration | -| `config:write` | Update app configuration | +| `config:read` | Read project configuration | +| `config:write` | Update project configuration | | `members:read` | View organization members | | `members:write` | Add and update organization members | | `members:delete` | Remove organization members | @@ -119,12 +143,13 @@ Access to API resources is controlled through scopes. PATs and OAuth clients mus * A write scope automatically includes its corresponding read scope (e.g. `apps:write` implies `apps:read`). * The wildcard scope (`*`) grants all permissions. +* The `apps:*` scope names are unchanged by the projects rename, and apply to projects. ## Rate Limiting -Requests are rate-limited per app. These limits are a high-level failsafe; actual throughput depends on the size of your deployed Spice instance or cluster. +Requests are rate-limited per project. These limits are a high-level failsafe; actual throughput depends on the size of your deployed Spice instance or cluster. -### Per-App Request Rate Limits +### Per-Project Request Rate Limits | Plan | Requests / second | | ---------- | ----------------- | @@ -204,12 +229,12 @@ Official SDKs are available for popular languages: * [Health](/broken/pages/MMiAVKRYaydEPCc1zdZU) - API health check * [Regions](/broken/pages/6ZPPX3ncuyaq7usBYCzO) - List available deployment regions -* [Apps](/broken/pages/Cxualhhbj3JVjFycQplA) - Manage Spice apps -* [Deployments](/broken/pages/cW4Y9zvF1YF9X2ExU15D) - Deploy and manage app deployments -* [Secrets](/broken/pages/jux7LfeRfZnBFKMpjIXA) - Manage app secrets -* [API Keys](/broken/pages/C2SEPG58kdQqhs4SL9B7) - Manage app API keys +* [Projects](/broken/pages/Cxualhhbj3JVjFycQplA) - Manage Spice projects +* [Deployments](/broken/pages/cW4Y9zvF1YF9X2ExU15D) - Deploy and manage project deployments +* [Secrets](/broken/pages/jux7LfeRfZnBFKMpjIXA) - Manage project secrets +* [API Keys](/broken/pages/C2SEPG58kdQqhs4SL9B7) - Manage project API keys * [Members](/broken/pages/fDcgKtae3y2pEzLWtbVg) - Manage organization members -* [Metrics](../metrics.md) - Scrape per-app runtime metrics +* [Metrics](../metrics.md) - Scrape per-project runtime metrics * [Container Images](/broken/pages/5fsccwHHHi12wJt5s0Ca) - List available runtime versions ## Terraform Provider @@ -218,33 +243,35 @@ Manage Spice.ai resources as infrastructure-as-code with the [Spice.ai Terraform ## Examples -### List all apps +### List all projects ```bash curl -H "Authorization: Bearer " \ - https://api.spice.ai/v1/apps + https://api.spice.ai/v1/projects ``` -### Create a new app +Results are returned under a `projects` key. The legacy `GET /v1/apps` path returns the same records under an `apps` key. + +### Create a new project ```bash -curl -X POST https://api.spice.ai/v1/apps \ +curl -X POST https://api.spice.ai/v1/projects \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ - "name": "my-app", + "name": "my-project", "region": "us-west-2", - "description": "My Spice app", + "description": "My Spice project", "visibility": "private" }' ``` -Organizations with a [dedicated cluster](dedicated-clusters.md) can pass `cluster_name` in place of `region` to create the app on their dedicated infrastructure. +Organizations with a [dedicated cluster](dedicated-clusters.md) can pass `cluster_name` in place of `region` to create the project on their dedicated infrastructure. ### Create a deployment ```bash -curl -X POST https://api.spice.ai/v1/apps/123/deployments \ +curl -X POST https://api.spice.ai/v1/projects/123/deployments \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ @@ -257,7 +284,7 @@ curl -X POST https://api.spice.ai/v1/apps/123/deployments \ ### Add a secret ```bash -curl -X POST https://api.spice.ai/v1/apps/123/secrets \ +curl -X POST https://api.spice.ai/v1/projects/123/secrets \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ diff --git a/cloud/api/management/dedicated-clusters.md b/cloud/api/management/dedicated-clusters.md index 3d7f609..89a1c9a 100644 --- a/cloud/api/management/dedicated-clusters.md +++ b/cloud/api/management/dedicated-clusters.md @@ -1,13 +1,13 @@ --- -description: Creating and managing apps on a dedicated, single-tenant cluster +description: Creating and managing projects on a dedicated, single-tenant cluster icon: server --- # Dedicated Clusters -An organization on an enterprise plan can have one or more **dedicated clusters**: Spice-managed, single-tenant infrastructure where an organization's apps run only alongside other apps from the same organization — never on shared infrastructure. Each cluster has its own `cluster_name`, isolated network, and connection endpoint. +An organization on an enterprise plan can have one or more **dedicated clusters**: Spice-managed, single-tenant infrastructure where an organization's projects run only alongside other projects from the same organization — never on shared infrastructure. Each cluster has its own `cluster_name`, isolated network, and connection endpoint. -Dedicated clusters are provisioned by Spice.ai and requested through [support](https://spice.ai/support). Once a cluster is provisioned and registered to an organization, it is available to the Management API and in the Portal's app-creation picker. +Dedicated clusters are provisioned by Spice.ai and requested through [support](https://spice.ai/support). Once a cluster is provisioned and registered to an organization, it is available to the Management API and in the Portal's project-creation picker. ## Listing clusters @@ -33,21 +33,21 @@ curl -H "Authorization: Bearer " \ } ``` -- **`cluster_name`** — the cluster's identifier, used when creating or reassigning apps. -- **`endpoint`** — the cluster's data-plane endpoint (an `https://` URL); apps running on the cluster are reached at this URL. +- **`cluster_name`** — the cluster's identifier, used when creating or reassigning projects. +- **`endpoint`** — the cluster's data-plane endpoint (an `https://` URL); projects running on the cluster are reached at this URL. -## Creating an app on a dedicated cluster +## Creating a project on a dedicated cluster -A create request specifies `cluster_name` instead of `region`, set to a `cluster_name` returned by `GET /v1/clusters`. Exactly one of the two is provided; the app's region is derived from the cluster. The request requires the `apps:write` scope. +A create request specifies `cluster_name` instead of `region`, set to a `cluster_name` returned by `GET /v1/clusters`. Exactly one of the two is provided; the project's region is derived from the cluster. The request requires the `apps:write` scope. ```bash -curl -X POST https://api.spice.ai/v1/apps \ +curl -X POST https://api.spice.ai/v1/projects \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ - "name": "my-app", + "name": "my-project", "cluster_name": "acme-prod-sandbox", - "description": "An app on a dedicated cluster" + "description": "A project on a dedicated cluster" }' ``` @@ -56,14 +56,14 @@ The response includes the resolved assignment and the cluster's endpoint: ```json { "id": 123, - "name": "my-app", + "name": "my-project", "cluster_name": "acme-prod-sandbox", "endpoint": "https://private-acme-prod-sandbox-us-west-2-prod-data.spiceai.io", "...": "..." } ``` -An app created without `cluster_name` deploys to the shared regional infrastructure as usual; `cluster_name: null` is equivalent to omitting it. +A project created without `cluster_name` deploys to the shared regional infrastructure as usual; `cluster_name: null` is equivalent to omitting it. {% hint style="info" %} If `region` is also provided it must match the cluster's region. @@ -77,26 +77,26 @@ If `region` is also provided it must match the cluster's region. | `400` `'' is not a deployable cluster` | The name is not a deployable cluster — a `cluster_name` from `GET /v1/clusters` is required | | `400` `region '' does not match cluster region ''` | An explicit `region` was provided that differs from the cluster's region | -## Moving an existing app to a dedicated cluster +## Moving an existing project to a dedicated cluster -`PUT /v1/apps/{appId}` with `cluster_name` reassigns the app. Subsequent deployments land on the cluster, and the app's endpoint changes to the cluster's host. +`PUT /v1/projects/{projectId}` with `cluster_name` reassigns the project. Subsequent deployments land on the cluster, and the project's endpoint changes to the cluster's host. ```bash -curl -X PUT https://api.spice.ai/v1/apps/123 \ +curl -X PUT https://api.spice.ai/v1/projects/123 \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"cluster_name": "acme-prod-sandbox"}' ``` {% hint style="warning" %} -Reassigning an app changes its data and Flight endpoints. Clients that pin the old hostnames must be updated, and a new [deployment](README.md#create-a-deployment) created so the app's runtime is placed on the cluster. +Reassigning a project changes its data and Flight endpoints. Clients that pin the old hostnames must be updated, and a new [deployment](README.md#create-a-deployment) created so the project's runtime is placed on the cluster. {% endhint %} -## Querying apps on a dedicated cluster +## Querying projects on a dedicated cluster -The app and `GET /v1/clusters` responses return the cluster's `endpoint` — the URL clients connect to. +The project and `GET /v1/clusters` responses return the cluster's `endpoint` — the URL clients connect to. -It serves the same APIs (SQL, search, and LLM over HTTP, plus Apache Arrow Flight), and authentication is unchanged — the app's [API key](../../portal/apps/api-keys.md) or platform credentials work exactly as on shared infrastructure. For Apache Arrow Flight, the endpoint's host is used with `-data` replaced by `-flight`, over `grpc+tls://:443`. +It serves the same APIs (SQL, search, and LLM over HTTP, plus Apache Arrow Flight), and authentication is unchanged — the project's [API key](../../portal/apps/api-keys.md) or platform credentials work exactly as on shared infrastructure. For Apache Arrow Flight, the endpoint's host is used with `-data` replaced by `-flight`, over `grpc+tls://:443`. With the [SDKs](../../../sdks/), the endpoint replaces the `data.spiceai.io` / `flight.spiceai.io` defaults. For example, with the [Python SDK](../../../sdks/python-sdk/) over Flight: @@ -104,9 +104,9 @@ With the [SDKs](../../../sdks/), the endpoint replaces the `data.spiceai.io` / ` from spicepy import Client client = Client( - api_key="", + api_key="", url="grpc+tls://private-acme-prod-sandbox-us-west-2-prod-flight.spiceai.io:443", ) ``` -Everything else — deployments, secrets, API keys, spicepod configuration — works identically to apps on shared infrastructure. The [Management APIs](README.md) reference documents the full endpoint set. +Everything else — deployments, secrets, API keys, spicepod configuration — works identically to projects on shared infrastructure. The [Management APIs](README.md) reference documents the full endpoint set.