Overview
The VersionResource provides methods for managing versions within Speckle models. Access it via client.version after authenticating your SpeckleClient.
Versions represent specific states or iterations of your data within a model. Each version references a committed object and includes metadata like author, timestamp, and a descriptive message.
from specklepy.api.client import SpeckleClient
client = SpeckleClient(host="https://app.speckle.systems")
client.authenticate_with_token(token)
# Access version operations
version = client.version.get("version_id", "project_id")
Methods
get()
Get a single version by ID.
client.version.get(version_id: str, project_id: str) -> Version
The ID of the version to retrieve
The ID of the project containing the version
version = client.version.get("version_abc123", "project_xyz789")
print(f"Message: {version.message}")
print(f"Object ID: {version.referencedObject}")
print(f"Created: {version.createdAt}")
print(f"Author: {version.authorUser.name}")
print(f"Source App: {version.sourceApplication}")
print(f"Preview: {version.previewUrl}")
get_versions()
Get all versions in a model with pagination support.
client.version.get_versions(
model_id: str,
project_id: str,
*,
limit: int = 25,
cursor: Optional[str] = None,
filter: Optional[ModelVersionsFilter] = None
) -> ResourceCollection[Version]
Maximum number of versions to return
filter
ModelVersionsFilter
default:"None"
Filter criteria
versions
ResourceCollection[Version]
Collection with items, totalCount, and cursor
# Get latest 25 versions
versions = client.version.get_versions("model_id", "project_id")
print(f"Total versions: {versions.totalCount}")
for version in versions.items:
print(f" - {version.message} by {version.authorUser.name}")
print(f" Created: {version.createdAt}")
# Get all versions (paginated)
all_versions = []
cursor = None
while True:
versions = client.version.get_versions(
"model_id",
"project_id",
limit=100,
cursor=cursor
)
all_versions.extend(versions.items)
if not versions.cursor:
break
cursor = versions.cursor
print(f"Retrieved {len(all_versions)} versions total")
from specklepy.core.api.inputs.model_inputs import ModelVersionsFilter
# Filter by source application
filter = ModelVersionsFilter(sourceApplication="Rhino")
versions = client.version.get_versions(
"model_id",
"project_id",
filter=filter
)
print(f"Found {versions.totalCount} versions from Rhino")
The ResourceCollection object includes:
items - List of Version objectstotalCount - Total number of versions (across all pages)cursor - Pagination cursor for next page (or None if no more pages)
create()
Create a new version in a model.
client.version.create(input: CreateVersionInput) -> Version
input
CreateVersionInput
required
The newly created version
from specklepy.core.api.inputs.version_inputs import CreateVersionInput
# Create a version
version = client.version.create(CreateVersionInput(
project_id="project_id",
model_id="model_id",
object_id="object_id_from_send",
message="Updated design with client feedback",
source_application="Rhino 7"
))
print(f"Created version: {version.id}")
print(f"Message: {version.message}")
project_id (str, required) - The project IDmodel_id (str, required) - The model IDobject_id (str, required) - The ID of the object to reference (from operations.send())message (str, optional) - Commit message describing this versionsource_application (str, optional) - Name of the source application
Complete Workflow Example:
from specklepy.api import operations
from specklepy.transports.server import ServerTransport
from specklepy.objects.geometry import Point
from specklepy.core.api.inputs.version_inputs import CreateVersionInput
# 1. Create your data
point = Point(x=10.5, y=20.3, z=5.1)
# 2. Send to server
transport = ServerTransport(stream_id=project_id, client=client)
object_id = operations.send(point, [transport])
# 3. Create version
version = client.version.create(CreateVersionInput(
project_id=project_id,
model_id=model_id,
object_id=object_id,
message="Added survey point",
source_application="Python Script"
))
print(f"✓ Created version: {version.id}")
update()
Update an existing version’s properties.
client.version.update(input: UpdateVersionInput) -> Version
input
UpdateVersionInput
required
from specklepy.core.api.inputs.version_inputs import UpdateVersionInput
# Update version message
updated_version = client.version.update(UpdateVersionInput(
project_id="project_id",
version_id="version_id",
message="Updated: Design revision after meeting"
))
print(f"Updated message: {updated_version.message}")
You can only update the message of a version. The referenced object cannot be changed after creation.
move_to_model()
Move versions from one model to another within the same project.
client.version.move_to_model(input: MoveVersionsInput) -> str
input
MoveVersionsInput
required
from specklepy.core.api.inputs.version_inputs import MoveVersionsInput
# Move versions to a different model
target_model_id = client.version.move_to_model(MoveVersionsInput(
project_id="project_id",
version_ids=["version_1", "version_2", "version_3"],
target_model_id="new_model_id"
))
print(f"✓ Moved 3 versions to model: {target_model_id}")
project_id (str, required) - The project IDversion_ids (List[str], required) - List of version IDs to movetarget_model_id (str, required) - The destination model ID
Both the source and target models must be in the same project. This operation cannot be undone.
delete()
Delete one or more versions permanently.
client.version.delete(input: DeleteVersionsInput) -> bool
input
DeleteVersionsInput
required
True if deletion was successful
from specklepy.core.api.inputs.version_inputs import DeleteVersionsInput
# Delete multiple versions
success = client.version.delete(DeleteVersionsInput(
project_id="project_id",
version_ids=["version_1", "version_2"]
))
if success:
print("✓ Versions deleted successfully")
else:
print("✗ Failed to delete versions")
project_id (str, required) - The project IDversion_ids (List[str], required) - List of version IDs to delete
This operation is irreversible! The versions will be permanently deleted, though the referenced objects may still exist in the project.
received()
Mark a version as received (useful for tracking which versions have been processed).
client.version.received(input: MarkReceivedVersionInput) -> bool
input
MarkReceivedVersionInput
required
Mark received parameters
True if successfully marked
from specklepy.core.api.inputs.version_inputs import MarkReceivedVersionInput
from specklepy.api import operations
from specklepy.transports.server import ServerTransport
# Receive a version
transport = ServerTransport(stream_id=project_id, client=client)
obj = operations.receive(version.referencedObject, transport)
# Mark as received
success = client.version.received(MarkReceivedVersionInput(
project_id=project_id,
version_id=version.id,
source_application="Python Processor"
))
if success:
print("✓ Marked version as received")
project_id (str, required) - The project IDversion_id (str, required) - The version ID to markmessage (str, optional) - Optional messagesource_application (str, optional) - Application that received the version
This method is useful for automation workflows where you want to track which versions have been processed by your scripts or applications.
Types
Version
Represents a version within a Speckle model.
Commit message describing this version
The ID of the committed object
Application used to create the version
CreateVersionInput(
object_id: str,
model_id: str,
project_id: str,
message: Optional[str] = None,
source_application: Optional[str] = "py",
total_children_count: Optional[int] = None,
parents: Optional[Sequence[str]] = None
)
create().
Fields:
object_id (str) - ID of the object (from operations.send())model_id (str) - Model IDproject_id (str) - Project IDmessage (str, optional) - Version message/descriptionsource_application (str, optional) - Source application name. Default: "py"total_children_count (int, optional) - Total number of child objectsparents (List[str], optional) - Parent version IDs
UpdateVersionInput(
version_id: str,
project_id: str,
message: Optional[str]
)
update().
Fields:
version_id (str) - Version IDproject_id (str) - Project IDmessage (str, optional) - New version message
DeleteVersionsInput(
version_ids: Sequence[str],
project_id: str
)
delete().
Fields:
version_ids (List[str]) - List of version IDs to deleteproject_id (str) - Project ID
MoveVersionsInput(
target_model_name: str,
version_ids: Sequence[str],
project_id: str
)
target_model_name (str) - Name of the target modelversion_ids (List[str]) - Version IDs to moveproject_id (str) - Project ID
