ProjectResource

Overview

The ProjectResource provides methods for managing Speckle projects. Access it via client.project after authenticating your SpeckleClient. Projects are the top-level containers in Speckle that hold models, versions, and team members.

from specklepy.api.client import SpeckleClient

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

# Access project operations
project = client.project.get("project_id")

Methods

get()

Get a single project by ID.

client.project.get(project_id: str) -> Project

Parameters:

str

required

The ID of the project to retrieve

Returns:

Project

The project object

Example:

project = client.project.get("abc123def456")

print(f"Project: {project.name}")
print(f"Description: {project.description}")
print(f"Visibility: {project.visibility}")
print(f"Role: {project.role}")
print(f"Workspace ID: {project.workspaceId}")

See Project for property details.

get_permissions()

Get permission checks for a project.

client.project.get_permissions(project_id: str) -> ProjectPermissionChecks

Parameters:

str

required

The ID of the project

Returns:

ProjectPermissionChecks

Permission check results

Example:

permissions = client.project.get_permissions("project_id")

if permissions.canCreateModel.authorized:
    print("✓ You can create models")
else:
    print(f"✗ Cannot create models: {permissions.canCreateModel.message}")

if permissions.canDelete.authorized:
    print("✓ You can delete this project")

if permissions.canPublish.authorized:
    print("✓ You can publish to this project")

See PermissionCheckResult for property details.

get_with_models()

Get a project with its models included.

client.project.get_with_models(
    project_id: str,
    *,
    models_limit: int = 25,
    models_cursor: Optional[str] = None,
    models_filter: Optional[ProjectModelsFilter] = None
) -> ProjectWithModels

Parameters:

str

required

The ID of the project

int

default:"25"

Maximum number of models to return

str

default:"None"

Cursor for pagination

ProjectModelsFilter

default:"None"

Filter criteria for models. See ProjectModelsFilter

Returns:

ProjectWithModels

Project with models collection

Example:

# Get project with first 10 models
project = client.project.get_with_models(
    "project_id",
    models_limit=10
)

print(f"Project: {project.name}")
print(f"Total models: {project.models.totalCount}")

for model in project.models.items:
    print(f"  - {model.name} (updated: {model.updatedAt})")

# Paginate through more models
if project.models.cursor:
    next_page = client.project.get_with_models(
        "project_id",
        models_cursor=project.models.cursor
    )

See ProjectModelsFilter for filtering options.

get_with_team()

Get a project with its team members and pending invitations.

client.project.get_with_team(project_id: str) -> ProjectWithTeam

Parameters:

str

required

The ID of the project

Returns:

ProjectWithTeam

Project with team information

Example:

project = client.project.get_with_team("project_id")

print(f"Project: {project.name}")
print(f"\nTeam members ({len(project.team)}):")
for member in project.team:
    print(f"  - {member.user.name} ({member.role})")

print(f"\nPending invitations ({len(project.invitedTeam)}):")
for invite in project.invitedTeam:
    invited_by = invite.invitedBy.name if invite.invitedBy else "Unknown"
    user_name = invite.user.name if invite.user else invite.title
    print(f"  - {user_name} ({invite.role}) - invited by {invited_by}")

create()

Create a new personal project (non-workspace).

client.project.create(input: ProjectCreateInput) -> Project

Parameters:

ProjectCreateInput

required

Project creation parameters. See ProjectCreateInput

Returns:

Project

The newly created project

Example:

from specklepy.core.api.inputs.project_inputs import ProjectCreateInput

# Create a basic project
project = client.project.create(ProjectCreateInput(
    name="My New Project",
    description="A project for architectural designs",
    visibility="PRIVATE"
))

print(f"Created project: {project.name} (ID: {project.id})")

See ProjectCreateInput for all available fields.

Check if you can create personal projects using client.active_user.can_create_personal_projects() before calling this method.

create_in_workspace()

Create a new workspace project.

client.project.create_in_workspace(input: WorkspaceProjectCreateInput) -> Project

Parameters:

WorkspaceProjectCreateInput

required

Workspace project creation parameters. See WorkspaceProjectCreateInput

Returns:

Project

The newly created workspace project

Example:

from specklepy.core.api.inputs.project_inputs import WorkspaceProjectCreateInput

# Get workspace ID first
workspaces = client.active_user.get_workspaces(limit=1)
workspace_id = workspaces.items[0].id

# Create workspace project
project = client.project.create_in_workspace(WorkspaceProjectCreateInput(
    name="Team Project",
    description="Shared project for the team",
    visibility="PRIVATE",
    workspaceId=workspace_id
))

print(f"Created workspace project: {project.name}")
print(f"Workspace ID: {project.workspaceId}")

See WorkspaceProjectCreateInput for all available fields.

This method only works on workspace-enabled servers (e.g., app.speckle.systems). Check workspace permissions using workspace.permissions.canCreateProject before calling.

update()

Update an existing project.

client.project.update(input: ProjectUpdateInput) -> Project

Parameters:

ProjectUpdateInput

required

Project update parameters. See ProjectUpdateInput

Returns:

Project

The updated project

Example:

from specklepy.core.api.inputs.project_inputs import ProjectUpdateInput

# Update project details
updated_project = client.project.update(ProjectUpdateInput(
    id="project_id",
    name="Updated Project Name",
    description="New description",
    visibility="PUBLIC",
    allowPublicComments=True
))

print(f"Updated: {updated_project.name}")

See ProjectUpdateInput for all available fields.

delete()

Delete a project permanently.

client.project.delete(project_id: str) -> bool

Parameters:

str

required

The ID of the project to delete

Returns:

bool

True if deletion was successful

Example:

# Delete a project
success = client.project.delete("project_id")

if success:
    print("✓ Project deleted successfully")
else:
    print("✗ Failed to delete project")

This operation is irreversible! All models, versions, and data in the project will be permanently deleted.

update_role()

Update a team member’s role in the project.

client.project.update_role(input: ProjectUpdateRoleInput) -> ProjectWithTeam

Parameters:

ProjectUpdateRoleInput

required

Role update parameters

Returns:

ProjectWithTeam

Updated project with team information

Example:

from specklepy.core.api.inputs.project_inputs import ProjectUpdateRoleInput

# Promote a user to contributor
project = client.project.update_role(ProjectUpdateRoleInput(
    projectId="project_id",
    userId="user_id",
    role="stream:contributor"  # or "stream:reviewer", "stream:owner"
))

print("Updated team roles:")
for member in project.team:
    print(f"  - {member.user.name}: {member.role}")

ProjectUpdateRoleInput Fields:

projectId (str, required) - The project ID
userId (str, required) - The user ID whose role to update
role (str, required) - New role: "stream:owner", "stream:contributor", or "stream:reviewer"

Role Permissions:

stream:owner - Full control, can delete project and manage team
stream:contributor - Can create models and versions
stream:reviewer - Read-only access

Types

Project

Represents a Speckle project.

str

Project ID

str

Project name

str

Project description

str

"PUBLIC", "PRIVATE", or "UNLISTED"

str

Your role: "stream:owner", "stream:contributor", or "stream:reviewer"

datetime

Creation timestamp

datetime

Last update timestamp

bool

Whether public comments are allowed

List[str]

List of source applications used

str

Workspace ID if this is a workspace project

PermissionCheckResult

Result of a permission check operation.

bool

Whether the action is authorized

str

Permission code

str

Human-readable message

Input Types

ProjectCreateInput

ProjectCreateInput(
    name: str,
    description: Optional[str] = None,
    visibility: Optional[str] = None
)

Used with create(). Fields:

name (str) - Project name
description (str, optional) - Project description
visibility (str, optional) - "PRIVATE", "PUBLIC", or "UNLISTED"

ProjectUpdateInput

ProjectUpdateInput(
    id: str,
    name: Optional[str] = None,
    description: Optional[str] = None,
    allow_public_comments: Optional[bool] = None,
    visibility: Optional[str] = None
)

Used with update(). Fields:

id (str) - Project ID
name (str, optional) - New project name
description (str, optional) - New description
allow_public_comments (bool, optional) - Allow public comments
visibility (str, optional) - New visibility setting

WorkspaceProjectCreateInput

WorkspaceProjectCreateInput(
    name: str,
    description: Optional[str] = None,
    visibility: Optional[str] = None,
    workspaceId: str
)

Used with create_in_workspace(). Fields:

name (str) - Project name
description (str, optional) - Project description
visibility (str, optional) - "PRIVATE", "PUBLIC", or "UNLISTED"
workspaceId (str) - Workspace ID

Filters

ProjectModelsFilter

ProjectModelsFilter(
    contributors: Optional[Sequence[str]] = None,
    exclude_ids: Optional[Sequence[str]] = None,
    ids: Optional[Sequence[str]] = None,
    only_with_versions: Optional[bool] = None,
    search: Optional[str] = None,
    source_apps: Optional[Sequence[str]] = None
)

Used with get_with_models() and client.model.get_models(). Fields:

contributors (List[str], optional) - Filter by contributor user IDs
exclude_ids (List[str], optional) - Exclude specific model IDs
ids (List[str], optional) - Include only specific model IDs
only_with_versions (bool, optional) - Only return models with versions
search (str, optional) - Search by model name
source_apps (List[str], optional) - Filter by source application

ModelResource

Work with models in projects

VersionResource

Manage versions in models

ActiveUserResource

Get user’s projects and permissions

SpeckleClient

Main client documentation

Python

C# .NET

Typescript

Overview

Methods

get()

get_permissions()

get_with_models()

get_with_team()

create()

create_in_workspace()

update()

delete()

update_role()

Types

Project

PermissionCheckResult

Input Types

ProjectCreateInput

ProjectUpdateInput

WorkspaceProjectCreateInput

Filters

ProjectModelsFilter

ModelResource

VersionResource

ActiveUserResource

SpeckleClient

​Overview

​Methods

​get()

​get_permissions()

​get_with_models()

​get_with_team()

​create()

​create_in_workspace()

​update()

​delete()

​update_role()

​Types

​Project

​PermissionCheckResult

​Input Types

​ProjectCreateInput

​ProjectUpdateInput

​WorkspaceProjectCreateInput

​Filters

​ProjectModelsFilter

​Related Resources

ModelResource

VersionResource

ActiveUserResource

SpeckleClient

Overview

Methods

get()

get_permissions()

get_with_models()

get_with_team()

create()

create_in_workspace()

update()

delete()

update_role()

Types

Project

PermissionCheckResult

Input Types

ProjectCreateInput

ProjectUpdateInput

WorkspaceProjectCreateInput

Filters

ProjectModelsFilter

Related Resources