Manage workspaces

Create, inspect, edit, and delete workspaces; list the regions you can create in.

Create a workspace

Only name is required. Authorization is the only required header — send X-Workspace-Id too if you're working inside an organization workspace and want the new workspace attached to the same organization:

curl -X POST "$API_BASE/v1/workspace" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Demand forecasting",
    "description": "Daily demand across EU markets",
    "goal": "Forecast SKU-level demand 14 days out",
    "keywords": ["demand", "retail", "sku"],
    "sectors": ["retail"],
    "data_granularity": "day",
    "region": "eu-1"
  }'

from predictai import PredictAI

client = PredictAI(token="pa_live_…")

data = client.workspaces.post_workspace(json={
    "name": "Demand forecasting",
    "description": "Daily demand across EU markets",
    "goal": "Forecast SKU-level demand 14 days out",
    "keywords": ["demand", "retail", "sku"],
    "sectors": ["retail"],
    "data_granularity": "day",
    "region": "eu-1",
})

import { PredictAI } from "@predictai/sdk";

const client = new PredictAI({ token: "pa_live_…" });

const data = await client.workspaces.postWorkspace({
  json: {
    name: "Demand forecasting",
    description: "Daily demand across EU markets",
    goal: "Forecast SKU-level demand 14 days out",
    keywords: ["demand", "retail", "sku"],
    sectors: ["retail"],
    data_granularity: "day",
    region: "eu-1",
  },
});

{
  "data": {
    "uid": "7d4a9b2e-3c61-4f8a-9e27-5b0c8d1f6a42",
    "message": "Workspace created successfully"
  }
}

A 201 means the workspace exists — the uid is the value you'll send as X-Workspace-Id from now on.

Field	What it is
`name` required	Display name.
`description` optional	Free text.
`goal` optional	What you want to forecast (stored as `purpose`; either key is accepted).
`keywords` optional	Array of lowercase strings.
`sectors` optional	Array of lowercase strings.
`data_granularity` optional	The cadence your data arrives at; defaults to `day`.
`region` optional	Region ID from available regions. Defaults to your account's home region. Set once — a workspace never changes region.

Errors

Status	Why	Example message
`400`	Empty body or missing `name`	`"Missing required field: name"`
`400`	`region` isn't a selectable region	`"Region 'ap-9' is not available for selection."`
`403`	Plan workspace quota reached	`"Workspace limit exceeded. Your plan allows 5 workspaces."`

The invalid-region error comes back structured, with the valid choices inline:

{
  "error": {
    "code": "invalid_region",
    "message": "Region 'ap-9' is not available for selection.",
    "details": { "available_regions": [ { "id": "eu-1", … } ] }
  },
  "status": "Region 'ap-9' is not available for selection."
}

Get one workspace

curl "$API_BASE/v1/workspace/$WORKSPACE_ID" \
  -H "Authorization: Bearer $TOKEN"

from predictai import PredictAI

client = PredictAI(token="pa_live_…")

data = client.workspaces.get_workspace_by_workspace_id(WORKSPACE_ID)

import { PredictAI } from "@predictai/sdk";

const client = new PredictAI({ token: "pa_live_…" });

const data = await client.workspaces.getWorkspaceByWorkspaceId(WORKSPACE_ID);

{
  "data": {
    "uid": "7d4a9b2e-3c61-4f8a-9e27-5b0c8d1f6a42",
    "name": "Demand forecasting",
    "description": "Daily demand across EU markets",
    "owner": "e1c62b7a-9f04-4d3b-8a15-2c7d90e4b638",
    "created_at": "2026-06-02T09:14:00+00:00",
    "updated_at": "2026-07-10T16:45:00+00:00",
    "collaborators": ["e1c62b7a-9f04-4d3b-8a15-2c7d90e4b638"],
    "user_role": "owner",
    "organization_name": "Acme Analytics",
    "organization_owner": "e1c62b7a-9f04-4d3b-8a15-2c7d90e4b638"
  }
}

organization_name and organization_owner appear only when the workspace belongs to an organization. Unlike the list route, the detail view carries no statistics block.

Errors

Status	Why	Example message
`403`	You can't access this workspace	`"Access denied to this workspace"`
`404`	No such workspace	`"Workspace with ID … not found"`

Edit a workspace

Send only the fields you're changing. The workspace owner or any collaborator can edit:

curl -X PUT "$API_BASE/v1/workspace/$WORKSPACE_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Demand forecasting (EU)" }'

from predictai import PredictAI

client = PredictAI(token="pa_live_…")

data = client.workspaces.put_workspace_by_workspace_id(WORKSPACE_ID, json={"name": "Demand forecasting (EU)"})

import { PredictAI } from "@predictai/sdk";

const client = new PredictAI({ token: "pa_live_…" });

const data = await client.workspaces.putWorkspaceByWorkspaceId(WORKSPACE_ID, { json: { name: "Demand forecasting (EU)" } });

{ "data": { "message": "Workspace updated successfully" } }

Field	Meaning
`name` optional	Rename the workspace.
`description` / `purpose` optional	Free-text metadata.
`keywords` / `sectors` optional	Arrays of lowercase strings.
`data_granularity` optional	The cadence your data arrives at.
`collaborators` optional	The array of user IDs with direct access.

Anything else in the body is ignored. If nothing actually changed, you get 200 with "No changes were made to the workspace".

Errors

Status	Why	Example message
`400`	Empty body	`"Request body is empty"`
`403`	Not the owner or a collaborator	`"You don't have permission to edit this workspace"`
`404`	No such workspace	`"Workspace with ID … not found"`

Delete a workspace

Only the workspace owner can delete:

curl -X DELETE "$API_BASE/v1/workspace/$WORKSPACE_ID" \
  -H "Authorization: Bearer $TOKEN"

from predictai import PredictAI

client = PredictAI(token="pa_live_…")

data = client.workspaces.delete_workspace_by_workspace_id(WORKSPACE_ID)

import { PredictAI } from "@predictai/sdk";

const client = new PredictAI({ token: "pa_live_…" });

const data = await client.workspaces.deleteWorkspaceByWorkspaceId(WORKSPACE_ID);

{ "data": { "message": "Workspace and all related data deleted successfully" } }

Deletion is immediate and irreversible, and it takes everything in the workspace with it: in-flight trainings, inferences, and imports are cancelled; live deployments are taken out of serving; then all models, pipelines, segments, signals, trainings, deployments, inference history, and member grants are permanently deleted.

Errors

Status	Why	Example message
`403`	Not the workspace owner	`"You don't have permission to delete this workspace"`
`404`	No such workspace	`"Workspace with ID … not found"`

List available regions

The regions you may create a workspace in, plus the default the platform would pick for you:

curl "$API_BASE/v1/workspace/available-regions" \
  -H "Authorization: Bearer $TOKEN"

from predictai import PredictAI

client = PredictAI(token="pa_live_…")

data = client.workspaces.get_workspace_available_regions()

import { PredictAI } from "@predictai/sdk";

const client = new PredictAI({ token: "pa_live_…" });

const data = await client.workspaces.getWorkspaceAvailableRegions();

{
  "data": {
    "regions": [
      {
        "id": "eu-1",
        "region": "eu-north-1",
        "subdomain": "eu.api.predict.ai",
        "countries": ["*EU"]
      },
      …
    ],
    "default_region": "eu-1"
  }
}

Pass a region's id as the region field when creating a workspace. subdomain is the API host serving that region — your base URL for workspaces created there. default_region is what you get when you don't choose; it's derived from your account's (or organization's) stored country and home region. When only one region is listed, there's nothing to decide.

On this page