WorkspaceResource

API reference for workspace operations in SpecklePy

Hosted Server Feature: The 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

logo · str

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

FAQ

Which servers support workspaces?

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.

How do I check if workspace features are available?

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

How do I get my workspace ID?

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}")

What's the difference between workspace projects and personal projects?

• Workspace projects: Owned by a workspace, shared with workspace members, managed by workspace admins
• Personal projects: Owned by individual users, independent of workspaces

Critical: All personal projects will be permanently deleted on January 1, 2026. Personal projects must be migrated to a workspace before this deadline.

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")

Can I create workspace projects?

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"
    ))

Related Resources

ActiveUserResource

Get your workspaces with get_workspaces() and get_active_workspace()

ProjectResource

Create projects within workspaces

SpeckleClient

Main client documentation