Workspaces

Overview

Workspaces are the top-level container in Praxiom AI. Each workspace represents a product and contains research sources, insights, recommendations, and documents. Users access workspaces through membership (owner, admin, or member roles).

---

Create Workspace

POST /api/workspaces

Creates a new workspace. The authenticated user becomes the owner and a trial subscription is automatically provisioned.

Requires: Product access (redeemed access code).

Request Body

Name	Type	Required	Description
name	string	Yes	Workspace display name
product_name	string	No	Name of the product
product_description	string	No	Brief description of the product
target_users	string	No	Description of target user personas
current_stage	string	No	Current product stage (e.g., "pre-launch", "growth")

Example Request

curl -X POST https://api.praxiomai.xyz/api/workspaces \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Dashboard",
    "product_name": "Acme Analytics",
    "product_description": "Real-time analytics for SaaS companies",
    "target_users": "SaaS founders and product managers",
    "current_stage": "growth"
  }'

import requests

resp = requests.post(
    "https://api.praxiomai.xyz/api/workspaces",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "name": "Acme Dashboard",
        "product_name": "Acme Analytics",
        "product_description": "Real-time analytics for SaaS companies",
        "target_users": "SaaS founders and product managers",
        "current_stage": "growth",
    },
)

const resp = await fetch("https://api.praxiomai.xyz/api/workspaces", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Acme Dashboard",
    product_name: "Acme Analytics",
    product_description: "Real-time analytics for SaaS companies",
    target_users: "SaaS founders and product managers",
    current_stage: "growth",
  }),
});

Response (201 Created)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Acme Dashboard",
  "product_name": "Acme Analytics",
  "product_description": "Real-time analytics for SaaS companies",
  "target_users": "SaaS founders and product managers",
  "current_stage": "growth",
  "owner_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "created_at": "2026-03-27T10:00:00Z",
  "updated_at": "2026-03-27T10:00:00Z"
}

---

List Workspaces

GET /api/workspaces

Returns all workspaces the authenticated user is a member of, sorted by most recently updated.

Example Request

curl https://api.praxiomai.xyz/api/workspaces \
  -H "Authorization: Bearer $TOKEN"

Response (200 OK)

{
  "workspaces": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Acme Dashboard",
      "product_name": "Acme Analytics",
      "owner_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "created_at": "2026-03-27T10:00:00Z",
      "updated_at": "2026-03-27T12:00:00Z"
    }
  ],
  "total": 1
}

---

Get Workspace

GET /api/workspaces/{workspace_id}

Get a single workspace by ID. User must be a member.

Path Parameters

Name	Type	Required	Description
workspace_id	UUID	Yes	Workspace ID

Response (200 OK)

Returns the full workspace object (same schema as create response).

---

Update Workspace

PATCH /api/workspaces/{workspace_id}

Update workspace fields. Requires owner or admin role.

Path Parameters

Name	Type	Required	Description
workspace_id	UUID	Yes	Workspace ID

Request Body

All fields are optional. Only provided fields are updated.

Name	Type	Required	Description
name	string	No	Workspace display name
product_name	string	No	Product name
product_description	string	No	Product description
target_users	string	No	Target user personas
current_stage	string	No	Product stage

Response (200 OK)

Returns the updated workspace object.

---

Get Workspace Settings

GET /api/workspaces/{workspace_id}/settings

Returns the workspace settings object. Requires workspace membership.

Path Parameters

Name	Type	Required	Description
workspace_id	UUID	Yes	Workspace ID

Response (200 OK)

{
  "researchCycleEnabled": false,
  "overnightCycleNotifyEmail": true
}

Field	Type	Description
researchCycleEnabled	boolean	Whether overnight research cycles are active
overnightCycleNotifyEmail	boolean	Whether to send morning digest emails after cycles

---

Update Workspace Settings

PATCH /api/workspaces/{workspace_id}/settings

Update workspace settings. Requires owner or admin role.

Path Parameters

Name	Type	Required	Description
workspace_id	UUID	Yes	Workspace ID

Request Body

All fields are optional. Only provided fields are updated.

Name	Type	Required	Description
researchCycleEnabled	boolean	No	Enable/disable overnight research cycles
overnightCycleNotifyEmail	boolean	No	Enable/disable morning digest email

Example Request

curl -X PATCH "https://api.praxiomai.xyz/api/workspaces/550e8400-.../settings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "researchCycleEnabled": true,
    "overnightCycleNotifyEmail": true
  }'

Response (200 OK)

Returns the updated settings object.

---

Get Agent Intro

GET /api/workspaces/{workspace_id}/agent-intro

Returns a workspace-state-aware intro message for the AI copilot. The message varies based on how much data the workspace contains (empty, has sources, has insights, or rich workspace).

Path Parameters

Name	Type	Required	Description
workspace_id	UUID	Yes	Workspace ID

Response (200 OK)

{
  "intro": "Your workspace is ready. To get started, upload your first research source...",
  "source_count": 0,
  "insight_count": 0,
  "recommendation_count": 0,
  "document_count": 0
}

---

Delete Workspace

DELETE /api/workspaces/{workspace_id}

Delete a workspace and all associated data. Only the workspace owner can delete.

Path Parameters

Name	Type	Required	Description
workspace_id	UUID	Yes	Workspace ID

Response (204 No Content)

No response body.