Overview
The ModelResource provides methods for managing models within Speckle projects. Access it via client.model after authenticating your SpeckleClient.
Models are containers within projects that organize related versions of your data. Each model can have multiple versions representing different iterations or states.
from specklepy.api.client import SpeckleClient
client = SpeckleClient(host="https://app.speckle.systems")
client.authenticate_with_token(token)
# Access model operations
model = client.model.get("model_id", "project_id")
Methods
get()
Get a single model by ID.
client.model.get(model_id: str, project_id: str) -> Model
The ID of the model to retrieve
The ID of the project containing the model
model = client.model.get("model_abc123", "project_xyz789")
print(f"Model: {model.name}")
print(f"Display Name: {model.displayName}")
print(f"Description: {model.description}")
print(f"Created: {model.createdAt}")
print(f"Updated: {model.updatedAt}")
print(f"Author: {model.author.name}")
print(f"Preview URL: {model.previewUrl}")
else:
print("Not authenticated")
get_models()
Get all models in a project with pagination support.
client.model.get_models(
project_id: str,
*,
models_limit: int = 25,
models_cursor: Optional[str] = None,
models_filter: Optional[ProjectModelsFilter] = None
) -> ResourceCollection[Model]
Maximum number of models to return
models_filter
ProjectModelsFilter
default:"None"
models
ResourceCollection[Model]
Collection with items, totalCount, and cursor
# Get all models in a project
models = client.model.get_models("project_id", models_limit=50)
print(f"Total models: {models.totalCount}")
for model in models.items:
print(f" - {model.displayName} (updated: {model.updatedAt})")
# Paginate through more models
if models.cursor:
next_page = client.model.get_models(
"project_id",
models_cursor=models.cursor
)
print(f"Next page has {len(next_page.items)} models")
The ResourceCollection object includes:
items - List of Model objectstotalCount - Total number of models (across all pages)cursor - Pagination cursor for next page (or None if no more pages)
get_with_versions()
Get a model with its versions included.
client.model.get_with_versions(
model_id: str,
project_id: str,
*,
versions_limit: int = 25,
versions_cursor: Optional[str] = None,
versions_filter: Optional[ModelVersionsFilter] = None
) -> ModelWithVersions
Maximum number of versions to return
versions_filter
ModelVersionsFilter
default:"None"
Model with versions collection
# Get model with its latest 10 versions
model = client.model.get_with_versions(
"model_id",
"project_id",
versions_limit=10
)
print(f"Model: {model.displayName}")
print(f"Total versions: {model.versions.totalCount}")
for version in model.versions.items:
print(f" - {version.message}")
print(f" By: {version.authorUser.name}")
print(f" Created: {version.createdAt}")
print(f" Object ID: {version.referencedObject}")
# Get all versions (paginated)
all_versions = []
cursor = None
while True:
model = client.model.get_with_versions(
"model_id",
"project_id",
versions_limit=100,
versions_cursor=cursor
)
all_versions.extend(model.versions.items)
if not model.versions.cursor:
break
cursor = model.versions.cursor
print(f"Retrieved {len(all_versions)} versions total")
create()
Create a new model in a project.
client.model.create(input: CreateModelInput) -> Model
from specklepy.core.api.inputs.model_inputs import CreateModelInput
# Create a basic model
model = client.model.create(CreateModelInput(
project_id="project_id",
name="Main Design",
description="Primary architectural design model"
))
print(f"Created model: {model.displayName} (ID: {model.id})")
from specklepy.core.api.inputs.model_inputs import CreateModelInput
# Create multiple models for different disciplines
disciplines = [
("Architecture", "Architectural design and layout"),
("Structure", "Structural engineering elements"),
("MEP", "Mechanical, electrical, and plumbing systems"),
]
models = []
for name, desc in disciplines:
model = client.model.create(CreateModelInput(
project_id=project_id,
name=name,
description=desc
))
models.append(model)
print(f"✓ Created: {model.displayName}")
print(f"\nTotal: {len(models)} models created")
update()
Update an existing model’s properties.
client.model.update(input: UpdateModelInput) -> Model
from specklepy.core.api.inputs.model_inputs import UpdateModelInput
# Update model details
updated_model = client.model.update(UpdateModelInput(
id="model_id",
projectId="project_id",
name="Updated Model Name",
description="Updated description with more details"
))
print(f"Updated: {updated_model.displayName}")
print(f"New description: {updated_model.description}")
delete()
Delete a model permanently.
client.model.delete(input: DeleteModelInput) -> bool
True if deletion was successful
from specklepy.core.api.inputs.model_inputs import DeleteModelInput
# Delete a model
success = client.model.delete(DeleteModelInput(
projectId="project_id",
modelId="model_id"
))
if success:
print("✓ Model deleted successfully")
else:
print("✗ Failed to delete model")
projectId (str, required) - The project IDmodelId (str, required) - The model ID to delete
This operation is irreversible! All versions in the model will be permanently deleted. Consider archiving or exporting data before deletion.
Types
Model
Represents a Speckle model within a project.
Model name (URL-safe identifier)
Human-readable display name
CreateModelInput(
name: str,
description: Optional[str] = None,
project_id: str
)
create().
Fields:
name (str) - Model namedescription (str, optional) - Model descriptionproject_id (str) - Project ID
UpdateModelInput(
id: str,
name: Optional[str] = None,
description: Optional[str] = None,
project_id: str
)
update().
Fields:
id (str) - Model IDname (str, optional) - New model namedescription (str, optional) - New descriptionproject_id (str) - Project ID
DeleteModelInput(
id: str,
project_id: str
)
delete().
Fields:
id (str) - Model IDproject_id (str) - Project 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
)
get_models() and client.project.get_with_models().
Fields:
contributors (List[str], optional) - Filter by contributor user IDsexclude_ids (List[str], optional) - Exclude specific model IDsids (List[str], optional) - Include only specific model IDsonly_with_versions (bool, optional) - Only return models with versionssearch (str, optional) - Search by model namesource_apps (List[str], optional) - Filter by source application
ModelVersionsFilter
ModelVersionsFilter(
priority_ids: Sequence[str],
priority_ids_only: Optional[bool] = None
)
get_with_versions().
Fields:
priority_ids (List[str]) - Version IDs to prioritizepriority_ids_only (bool, optional) - Only return priority versions
