Management APIs

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 org members.

Base URL

https://api.spice.ai

API Version

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:

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:

1. Personal Access Tokens (PATs)

PATs are user-scoped tokens with an expiration that you select, from 24 hours to 180 days. Recommended for:

• CLI tools and automation scripts
• Personal integrations

Creating a PAT:

1. Sign in to Spice.ai Cloud Portal
2. Click the profile picture, select Settings, then select Personal Access Tokens
3. Enter a Token Name and select an Expiration
4. Click Create
5. Copy the token (it won't be shown again)

Using a PAT:

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

Learn more: Personal Access Tokens

2. OAuth 2.0 Client Credentials

OAuth client credentials are org-scoped tokens. Ideal for:

• CI/CD pipelines
• Service-to-service authentication
• Multi-tenant applications
• Third-party integrations

Step 1: Exchange client credentials for an access token

curl -X POST https://spice.ai/api/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your-client-id",
    "client_secret": "your-client-secret",
    "grant_type": "client_credentials"
  }'

The response contains an access_token:

{
  "access_token": "eyJhbGciOiJSUzI...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Step 2: Use the access token in subsequent requests

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

3. User Session Tokens (CLI)

The Spice CLI stores a credential for the Management API with spice login. On a terminal it asks which one to use:

spice login
? How would you like to authenticate to Spice Cloud? ›
❯ Login with a web browser
  Paste an access token

Login with a web browser signs in through the browser and stores the resulting user session token, which carries the user's identity. Paste an access token stores a personal access token instead.

The prompt appears only when the CLI is attached to a terminal. Scripts and CI pipelines name the method as a subcommand, which also lets them supply the credential without being prompted for it:

Run with no terminal and no subcommand, spice login reports that the login type must be chosen explicitly rather than waiting on a prompt that cannot be answered.

Org context

Every Management API request acts on exactly one org. By default that is the org the credential was minted against. Send the X-Org-Name header with an org handle to act on a different one.

A portal session token is bound to no org. A request with one must send X-Org-Name, except on GET /v1/orgs and on /v1/orgs/{orgId}/... routes. Without the header, the request is refused with org_assertion_required.

A /v1/orgs/{orgId}/... route takes the org from the orgId in its path. Use an id from GET /v1/orgs. On these routes, X-Org-Name is optional and may only name the same org.

A user credential carries a user identity, so the API authorizes the request against that user's membership. A machine credential carries no user identity and stays pinned to one org: a header naming a different org is refused rather than ignored.

Handles are matched case-insensitively and may contain letters, numbers, dots, hyphens, and underscores.

curl -H "Authorization: Bearer <token>" \
  -H "X-Org-Name: acme-corp" \
  https://api.spice.ai/v1/projects

Discovering orgs

GET /v1/orgs lists the orgs the caller belongs to, with the caller's role in each. Use it to choose a value for X-Org-Name.

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

{
  "orgs": [
    { "id": 42, "name": "acme-corp", "role": "owner" },
    { "id": 57, "name": "example-org", "role": "member" }
  ]
}

• name is the org handle: the value X-Org-Name accepts, and the one used in <org>/<project> addressing.
• role is the caller's highest-privilege role in that org: owner, admin, member, or viewer.
• A caller who belongs to no org receives 200 with an empty orgs array, never a 404.
• An OAuth client credential lists only the org it was issued to, with the role owner.
• Requires the apps:read scope.

Refused requests

A refusal returns a machine-readable code alongside error, because each one has a different remedy:

Two details are easy to miss:

• A blank X-Org-Name is an error, not an omission. It returns invalid_org_assertion, because a client that sent the header believes it named an org.
• An org that does not exist and one the caller cannot see both return org_forbidden. The header cannot be used to test whether an org exists.

OAuth Scopes

Access to API resources is controlled through scopes. PATs and OAuth clients must be granted appropriate scopes:

Scope hierarchy:

• A write scope automatically includes its corresponding read scope (e.g. apps:write implies apps:read).
• apps:delete includes apps:write and 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 project. These limits are a high-level failsafe; actual throughput depends on the size of your deployed Spice instance or cluster.

Per-Project Request Rate Limits

Concurrent Query Limits

These limits apply to SQL queries executed against your Spice runtime, not to management API calls.

Error Responses

The API uses standard HTTP status codes:

Error Response Format:

{
  "error": "Human-readable error message",
  "details": {
    "fieldErrors": {
      "field_name": ["Validation error message"]
    }
  }
}

Authorization failures also carry a machine-readable code, so a client can tell the refusals apart instead of guessing:

{
  "error": "You are not a member of the requested organization",
  "code": "org_forbidden"
}

See Refused requests for the codes and their remedies.

Pagination

The project and deployment list endpoints take a limit query parameter. Its default and maximum depend on the endpoint:

GET /v1/projects returns projects in descending id order. To read the next page, pass the smallest id from the current page as after_id. offset skips a number of projects and applies only when after_id is not set. Other list endpoints use their own pagination parameters and limits. See each endpoint's reference page for its parameters.

OpenAPI Specification

The API publishes its own OpenAPI specification, which describes every endpoint and the headers it accepts:

https://api.spice.ai/openapi.json

The same document is also served at https://api.spice.ai/v1/docs and https://api.spice.ai/v1/docs/openapi.json.

SDK Support

Official SDKs are available for popular languages:

• Python SDK
• Node.js SDK
• Go SDK
• Rust SDK

Endpoints

• Health - API health check
• Regions - List available deployment regions
• Projects - Manage Spice projects
• Deployments - Deploy and manage project deployments
• Secrets - Manage project secrets
• API Keys - Manage project API keys
• Members - Manage org members
• Orgs - List the orgs the caller belongs to
• Metrics - Scrape per-project runtime metrics
• Monitors - Manage project monitors
• Reactions - Manage data reactions (private preview)
• Limits - Read org limits

Terraform Provider

Manage Spice.ai resources as infrastructure-as-code with the Spice.ai Terraform Provider. See the Terraform Provider page for resources, data sources, import instructions, and complete examples.

Examples

List all projects

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

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

curl -X POST https://api.spice.ai/v1/projects \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-project",
    "region": "us-west-2",
    "description": "My Spice project",
    "visibility": "private"
  }'

Orgs with a dedicated cluster can pass cluster_name in place of region to create the project on their dedicated infrastructure.

Update a project

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

Create a deployment

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

An empty body deploys the project's current configuration. For a project connected to a GitHub repository, it deploys the head of the production branch.

To deploy a specific revision of a connected repository, set branch, commit_sha, or both. branch names a branch or a tag, and it must exist. commit_sha takes 7 to 40 hexadecimal characters. The ref in branch must contain the commit. When branch is omitted, the production branch must contain it. A project with no connected repository refuses both fields with 400 repository_not_connected.

curl -X POST https://api.spice.ai/v1/projects/123/deployments \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "branch": "main",
    "commit_sha": "9fceb02d0ae598e95dc970b74767f19372d61af8"
  }'

Deployment status and errors

Deployment statuses

Deployments use these statuses:

Deployment errors

The error catalog classifies codes as retriable or terminal:

error_code is optional. When it is present, it is a catalog code. error_message contains human-readable catalog text. On current writes, the two fields are set together and cleared together. Older failed deployments can carry an error_message without an error_code. Branch on error_code when it is present, not on the message text.

A project instance that cannot start because the cluster lacks CPU, memory, storage, or instance capacity is a retriable scheduling block. GET /v1/projects/{projectId}/deployments and GET /v1/projects/{projectId}/deployments/{deploymentId} keep status as in_progress and return both error_code (insufficient_cpu, insufficient_memory, insufficient_storage, or insufficient_instances) and error_message while Cloud retries placement. That is not a terminal failed deployment. Terminal codes (pod_exceeds_node_capacity, unable_to_start, internal_error) record failed.

The Deployments page in the portal reports the same codes.

Add a secret

curl -X POST https://api.spice.ai/v1/projects/123/secrets \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "DATABASE_URL",
    "value": "postgresql://user:pass@host:5432/db"
  }'

Support

Have questions or running into issues?

• Community Slack
• Help Center