ProjectResource

Complete API reference for project operations in SpecklePy

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

Related Resources

ModelResource

Work with models in projects

VersionResource

Manage versions in models

ActiveUserResource

Get user’s projects and permissions

SpeckleClient

Main client documentation