Skip to main content
Hosted Server FeatureThe WorkspaceResource is only available on workspace-enabled Speckle deployments, primarily the hosted server at app.speckle.systems.Self-hosted/open-source server deployments do not include workspace features. Attempting to use workspace methods on non-workspace servers will raise an error.

​
Overview

The WorkspaceResource provides methods for managing Speckle workspaces. Access it via client.workspace after authenticating your SpeckleClient. Workspaces are organizational units that group projects and team members together on workspace-enabled servers. 
from specklepy.api.client import SpeckleClient

client = SpeckleClient(host="https://app.speckle.systems")
client.authenticate_with_token(token)

workspace = client.workspace.get("workspace_id")

​
Methods

​
get()

Get a single workspace by ID. 
client.workspace.get(workspace_id: str) -> Workspace
Parameters:
​
workspace_id
str
required
The ID of the workspace to retrieve
Returns:
​
workspace
Workspace
The workspace object
Example: 
workspace = client.workspace.get("workspace_abc123")

print(f"Name: {workspace.name}")
print(f"Slug: {workspace.slug}")
print(f"Description: {workspace.description}")
print(f"Role: {workspace.role}")
print(f"Created: {workspace.createdAt}")

if workspace.permissions.canCreateProject.authorized:
    print("✓ Can create projects in this workspace")
See Workspace for property details.

​
get_projects()

Get all projects in a workspace with pagination support. 
client.workspace.get_projects(
    workspace_id: str,
    limit: int = 25,
    cursor: Optional[str] = None,
    filter: Optional[WorkspaceProjectsFilter] = None
) -> ResourceCollection[Project]
Parameters:
​
workspace_id
str
required
The ID of the workspace
​
limit
int
default:"25"
Maximum number of projects to return
​
cursor
str
default:"None"
Cursor for pagination
​
filter
WorkspaceProjectsFilter
default:"None"
Filter criteria
Returns:
​
projects
ResourceCollection[Project]
Collection with items, totalCount, and cursor
Example: 
projects = client.workspace.get_projects("workspace_id", limit=50)

print(f"Total projects: {projects.totalCount}")
for project in projects.items:
    print(f"  - {project.name}")
    print(f"    Visibility: {project.visibility}")
    print(f"    Role: {project.role}")

# Pagination
if projects.cursor:
    next_page = client.workspace.get_projects("workspace_id", cursor=projects.cursor)
Filter Example: 
from specklepy.core.api.inputs.project_inputs import WorkspaceProjectsFilter

# Filter by search term
filter = WorkspaceProjectsFilter(search="design")
projects = client.workspace.get_projects("workspace_id", filter=filter)

# Note: Check the WorkspaceProjectsFilter class for all available filter options
# Common filters include:
# - search: Search term for project name/description
# - filter by visibility, roles, etc.

​
get_projects_with_permissions()

Get all projects in a workspace with detailed permission information. 
client.workspace.get_projects_with_permissions(
    workspace_id: str,
    limit: int = 25,
    cursor: Optional[str] = None,
    filter: Optional[WorkspaceProjectsFilter] = None
) -> ResourceCollection[ProjectWithPermissions]
Parameters:
​
workspace_id
str
required
The ID of the workspace
​
limit
int
default:"25"
Maximum number of projects to return
​
cursor
str
default:"None"
Cursor for pagination
​
filter
WorkspaceProjectsFilter
default:"None"
Filter criteria
Returns:
​
projects
ResourceCollection[ProjectWithPermissions]
Collection of projects with permission details
Example: 
projects = client.workspace.get_projects_with_permissions("workspace_id")

for project in projects.items:
    print(f"\nProject: {project.name}")
    print(f"  Role: {project.role}")

    # Check permissions
    if project.permissions.canCreateModel.authorized:
        print("  ✓ Can create models")
    if project.permissions.canDelete.authorized:
        print("  ✓ Can delete project")
    if project.permissions.canPublish.authorized:
        print("  ✓ Can publish versions")
ProjectWithPermissions Additional Properties:
  • permissions (ProjectPermissions) - Detailed permission checks
    • canCreateModel - Model creation permission
    • canDelete - Project deletion permission
    • canLoad - Project loading permission
    • canPublish - Version publishing permission
Each permission object includes:
  • authorized (bool) - Whether the action is authorized
  • code (str) - Permission code
  • message (str, optional) - Human-readable message

​
Types

​
Workspace

Represents a Speckle workspace.
​
id
str
Workspace ID
​
name
str
Workspace name
​
slug
str
URL-safe identifier
​
role
str
Your role in the workspace
Workspace logo URL
​
description
str
Workspace description
​
createdAt
datetime
Creation timestamp
​
updatedAt
datetime
Last update timestamp
​
readOnly
bool
Whether workspace is read-only
​
creationState
object
Creation state information
  • completed (bool) - Whether workspace setup is complete
​
permissions
WorkspacePermissions
Permission checks
  • canCreateProject - Project creation permission

​
Filters

​
WorkspaceProjectsFilter

WorkspaceProjectsFilter(
    search: Optional[str] = None,
    with_project_role_only: Optional[bool] = None
)
Used with get_projects() and get_projects_with_permissions(). Fields:
  • search (str, optional) - Filter by project name
  • with_project_role_only (bool, optional) - Only return projects where user has explicit project role

​
Frequently Asked Questions

Workspace features are available on:
  • app.speckle.systems (hosted Speckle server)
  • Enterprise deployments with workspace features enabled
Workspace features are NOT available on:
  • Self-hosted open-source Speckle servers
  • Community edition deployments
Check before using by wrapping calls in try/except blocks.
Attempt to get workspaces and handle the error:
try:
    workspaces = client.active_user.get_workspaces()
    print("Workspace features available")
    # Proceed with workspace operations
except Exception as e:
    print("Workspace features not available")
    # Fall back to non-workspace operations
Use the active_user resource to list your workspaces:
workspaces = client.active_user.get_workspaces()

for ws in workspaces.items:
    print(f"Workspace: {ws.name}")
    print(f"  ID: {ws.id}")
    print(f"  Slug: {ws.slug}")
  • Workspace projects: Owned by a workspace, shared with workspace members, managed by workspace admins
  • Personal projects: Owned by individual users, independent of workspaces
On workspace-enabled servers, projects can belong to either a workspace or a user. Check the workspaceId field on a project to determine ownership.
project = client.project.get("project_id")
if project.workspaceId:
    print(f"Workspace project: {project.workspaceId}")
else:
    print("Personal project")
Project creation happens through the ProjectResource, but you can specify the workspace:
from specklepy.core.api.inputs.project_inputs import ProjectCreateInput

# Check permission first
workspace = client.workspace.get("workspace_id")
if not workspace.permissions.canCreateProject.authorized:
    print("Cannot create projects in this workspace")
else:
    # Create through project resource with workspaceId
    project = client.project.create(ProjectCreateInput(
        name="My Project",
        workspaceId="workspace_id"
    ))

ActiveUserResource

Get your workspaces with get_workspaces() and get_active_workspace()

ProjectResource

Create projects within workspaces

SpeckleClient

Main client documentation