Workspaces API

Workspaces are the top-level organizational unit in RunWhen. Each workspace contains SLXs, run sessions, issues, workflows, and other resources scoped to a specific environment or team. Workspaces are backed by a Git repository that stores their declarative configuration.

List Workspaces

Retrieve all workspaces accessible to the authenticated user.

Query Parameters

Response 200 OK

{
  "count": 5,
  "next": null,
  "previous": null,
  "results": [
    {
      "name": "my-workspace",
      "displayName": "My Workspace",
      "owner": "user@example.com",
      "enabledLocations": ["location-1"],
      "createdAt": "2026-01-15T10:00:00Z",
      "updatedAt": "2026-02-20T14:30:00Z"
    }
  ]
}

Create Workspace

Create a new workspace.

Request Body

{
  "name": "my-new-workspace",
  "displayName": "My New Workspace"
}

Response 201 Created

Returns the newly created workspace object.

Get Workspace

Retrieve details of a specific workspace.

Path Parameters

Response 200 OK

{
  "name": "my-workspace",
  "displayName": "My Workspace",
  "owner": "user@example.com",
  "configProvided": {},
  "secretsProvided": {},
  "enabledLocations": ["location-1", "location-2"],
  "slxGroups": {},
  "createdAt": "2026-01-15T10:00:00Z",
  "updatedAt": "2026-02-20T14:30:00Z"
}

Update Workspace

Replace the full workspace configuration.

Path Parameters

Request Body

Provide the complete workspace object. All fields not included will be reset to defaults.

Response 200 OK

Returns the updated workspace object.

Partial Update Workspace

Update specific fields on a workspace without replacing the entire object.

Path Parameters

Request Body

{
  "displayName": "Updated Display Name",
  "enabledLocations": ["us-east-1", "eu-west-1"]
}

Only include the fields you want to modify.

Response 200 OK

Returns the updated workspace object.

Delete Workspace

Permanently delete a workspace and all of its associated resources (SLXs, run sessions, issues, etc.).

Path Parameters

Response 204 No Content

This operation is irreversible. All child resources within the workspace will be permanently removed.

Get Workspace Status

Retrieve the overall status of a workspace.

Path Parameters

Response 200 OK

Returns the current health and readiness state of the workspace.

Get Workspace Health

Retrieve detailed health information for a workspace.

Path Parameters

Query Parameters

Response 200 OK

Returns workspace health status with optional detail and metrics breakdowns.

Upload Workspace Configuration

Retrieve a presigned upload URL for pushing workspace configuration bundles.

Path Parameters

Response 200 OK

Returns a presigned upload URL. Uses GCS signed URLs on cloud deployments or MinIO presigned URLs on local/k3s deployments.

Get Upload Config

Generate a workspace builder configuration file for uploading workspace data.

Path Parameters

Query Parameters

Response 200 OK

Returns a workspace builder configuration payload.

Get Default Manifest

Retrieve a default resource manifest template for a workspace.

Path Parameters

Response 200 OK

Returns a default manifest template for the specified resource type.

Get Runner Token

Retrieve the authentication token used by runners in this workspace.

Path Parameters

Response 200 OK

Returns the runner authentication token for the workspace.

Get SLX Select Options

Retrieve a list of SLX names formatted as select options for use in UI dropdowns or integrations.

Path Parameters

Response 200 OK

Returns a list of SLX option objects suitable for select inputs.

Integrate Slack

Connect a Slack workspace to this RunWhen workspace.

Path Parameters

Response 200 OK

Returns Slack integration status and configuration.

Get AgentFarm Params

Retrieve resolved configuration parameters for AgentFarm integrations, including LLM config with workspace-to-org-to-platform default fallback.

Path Parameters

Response 200 OK

{
  "llmConfig": { ... },
  "organization": { ... },
  "permissions": { ... },
  "repoUrl": "https://...",
  "branch": "main"
}