Skip to main content

​
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:
​
project_id
str
required
The ID of the project to retrieve
Returns:
​
project
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:
​
project_id
str
required
The ID of the project
Returns:
​
permissions
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:
​
project_id
str
required
The ID of the project
​
models_limit
int
default:"25"
Maximum number of models to return
​
models_cursor
str
default:"None"
Cursor for pagination
​
models_filter
ProjectModelsFilter
default:"None"
Filter criteria for models. See ProjectModelsFilter
Returns:
​
project
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:
​
project_id
str
required
The ID of the project
Returns:
​
project
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:
​
input
ProjectCreateInput
required
Project creation parameters. See ProjectCreateInput
Returns:
​
project
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:
​
input
WorkspaceProjectCreateInput
required
Workspace project creation parameters. See WorkspaceProjectCreateInput
Returns:
​
project
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:
​
input
ProjectUpdateInput
required
Project update parameters. See ProjectUpdateInput
Returns:
​
project
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:
​
project_id
str
required
The ID of the project to delete
Returns:
​
success
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:
​
input
ProjectUpdateRoleInput
required
Role update parameters
Returns:
​
project
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.
​
id
str
Project ID
​
name
str
Project name
​
description
str
Project description
​
visibility
str
"PUBLIC", "PRIVATE", or "UNLISTED"
​
role
str
Your role: "stream:owner", "stream:contributor", or "stream:reviewer"
​
createdAt
datetime
Creation timestamp
​
updatedAt
datetime
Last update timestamp
​
allowPublicComments
bool
Whether public comments are allowed
​
sourceApps
List[str]
List of source applications used
​
workspaceId
str
Workspace ID if this is a workspace project

​
PermissionCheckResult

Result of a permission check operation.
​
authorized
bool
Whether the action is authorized
​
code
str
Permission code
​
message
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
Last modified on January 28, 2026