Workspaces API

Manage workspaces programmatically. All endpoints require authentication.

Base path: /api/v1/workspaces

---

Create Workspace

Create a new workspace in your organization.

POST /api/v1/workspaces

Request Body

Field	Type	Required	Description
name	string	✅	Display name for the workspace
provider	string	—	AI provider. One of: vertex_ai, google_ai_studio, openai, anthropic, ollama
model	string	—	Model identifier (e.g., gemini-2.5-pro, claude-sonnet-4-20250514, gpt-4o)
systemPrompt	string	—	System prompt for the workspace AI

Example Request

curl -X POST https://roundtable.foxtrotcommunications.net/api/v1/workspaces \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Analytics",
    "provider": "vertex_ai",
    "model": "gemini-2.5-pro",
    "systemPrompt": "You are a data analytics assistant with access to BigQuery."
  }'

Example Response

// 201 Created
{
  "id": "ws_abc123def456",
  "name": "Analytics",
  "provider": "vertex_ai",
  "model": "gemini-2.5-pro",
  "systemPrompt": "You are a data analytics assistant with access to BigQuery.",
  "status": "stopped",
  "createdAt": "2026-05-21T17:30:00.000Z",
  "updatedAt": "2026-05-21T17:30:00.000Z"
}

:::info Initial Status New workspaces are created in a stopped state. Update the status to running to start the workspace pod. :::

---

List Workspaces

Retrieve all workspaces in your organization.

GET /api/v1/workspaces

Example Request

curl https://roundtable.foxtrotcommunications.net/api/v1/workspaces \
  -H "Authorization: Bearer ${TOKEN}"

Example Response

// 200 OK
{
  "workspaces": [
    {
      "id": "ws_abc123def456",
      "name": "Analytics",
      "provider": "vertex_ai",
      "model": "gemini-2.5-pro",
      "status": "running",
      "createdAt": "2026-05-21T17:30:00.000Z",
      "updatedAt": "2026-05-21T17:35:00.000Z"
    },
    {
      "id": "ws_ghi789jkl012",
      "name": "Engineering",
      "provider": "anthropic",
      "model": "claude-sonnet-4-20250514",
      "status": "stopped",
      "createdAt": "2026-05-20T10:00:00.000Z",
      "updatedAt": "2026-05-20T10:00:00.000Z"
    }
  ]
}

---

Get Workspace

Retrieve details for a specific workspace.

GET /api/v1/workspaces/:id

Parameters

Parameter	Location	Description
id	Path	Workspace ID

Example Request

curl https://roundtable.foxtrotcommunications.net/api/v1/workspaces/ws_abc123def456 \
  -H "Authorization: Bearer ${TOKEN}"

Example Response

// 200 OK
{
  "id": "ws_abc123def456",
  "name": "Analytics",
  "provider": "vertex_ai",
  "model": "gemini-2.5-pro",
  "systemPrompt": "You are a data analytics assistant with access to BigQuery.",
  "status": "running",
  "createdAt": "2026-05-21T17:30:00.000Z",
  "updatedAt": "2026-05-21T17:35:00.000Z"
}

Error Response

// 404 Not Found
{
  "error": "Workspace not found",
  "details": {
    "workspaceId": "ws_invalid"
  }
}

---

Update Workspace

Update an existing workspace's configuration. Only include the fields you want to change.

PATCH /api/v1/workspaces/:id

Parameters

Parameter	Location	Description
id	Path	Workspace ID

Request Body

All fields are optional — include only what you want to update.

Field	Type	Description
name	string	New display name
provider	string	New AI provider
model	string	New model identifier
systemPrompt	string	New system prompt
status	string	running or stopped — start or stop the workspace

Example Request: Update Name and Model

curl -X PATCH https://roundtable.foxtrotcommunications.net/api/v1/workspaces/ws_abc123def456 \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Analytics v2",
    "model": "gemini-2.5-flash"
  }'

Example Response

// 200 OK
{
  "id": "ws_abc123def456",
  "name": "Analytics v2",
  "provider": "vertex_ai",
  "model": "gemini-2.5-flash",
  "systemPrompt": "You are a data analytics assistant with access to BigQuery.",
  "status": "running",
  "createdAt": "2026-05-21T17:30:00.000Z",
  "updatedAt": "2026-05-21T18:00:00.000Z"
}

Example Request: Start a Workspace

curl -X PATCH https://roundtable.foxtrotcommunications.net/api/v1/workspaces/ws_abc123def456 \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"status": "running"}'

Example Request: Stop a Workspace

curl -X PATCH https://roundtable.foxtrotcommunications.net/api/v1/workspaces/ws_abc123def456 \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"status": "stopped"}'

:::warning Stopping a Running Workspace Stopping a workspace terminates its Kubernetes pod. Any active conversations will be interrupted. Workspace data (system prompt, configuration, conversation history) is preserved. :::

---

Delete Workspace

Permanently delete a workspace and its associated resources.

DELETE /api/v1/workspaces/:id

Parameters

Parameter	Location	Description
id	Path	Workspace ID

Example Request

curl -X DELETE https://roundtable.foxtrotcommunications.net/api/v1/workspaces/ws_abc123def456 \
  -H "Authorization: Bearer ${TOKEN}"

Example Response

// 200 OK
{
  "message": "Workspace deleted",
  "id": "ws_abc123def456"
}

:::danger Permanent Action Deleting a workspace is irreversible. The workspace pod is terminated, and all configuration, conversation history, and associated bridges are permanently removed. :::

Error Response

// 404 Not Found
{
  "error": "Workspace not found",
  "details": {
    "workspaceId": "ws_abc123def456"
  }
}