Skip to main content

​
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
Parameters:
​
version_id
str
required
The ID of the version to retrieve
​
project_id
str
required
The ID of the project containing the version
Returns:
​
version
Version
The version object
Example: 
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}")
See Version for property details.

​
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]
Parameters:
​
model_id
str
required
The ID of the model
​
project_id
str
required
The ID of the project
​
limit
int
default:"25"
Maximum number of versions to return
​
cursor
str
default:"None"
Cursor for pagination
​
filter
ModelVersionsFilter
default:"None"
Filter criteria
Returns:
​
versions
ResourceCollection[Version]
Collection with items, totalCount, and cursor
Example: 
# 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}")
With Pagination: 
# 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")
With Filtering: 
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 objects
  • totalCount - 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
Parameters:
​
input
CreateVersionInput
required
Version creation parameters. See CreateVersionInput
Returns:
​
version
Version
The newly created version
Example: 
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}")
CreateVersionInput Fields:
  • project_id (str, required) - The project ID
  • model_id (str, required) - The model ID
  • object_id (str, required) - The ID of the object to reference (from operations.send())
  • message (str, optional) - Commit message describing this version
  • source_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
Parameters:
​
input
UpdateVersionInput
required
Version update parameters. See UpdateVersionInput
Returns:
​
version
Version
The updated version
Example: 
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}")
See UpdateVersionInput for all available fields.
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
Parameters:
​
input
MoveVersionsInput
required
Move parameters. See MoveVersionsInput
Returns:
​
model_id
str
The target model ID
Example: 
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}")
MoveVersionsInput Fields:
  • project_id (str, required) - The project ID
  • version_ids (List[str], required) - List of version IDs to move
  • target_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
Parameters:
​
input
DeleteVersionsInput
required
Deletion parameters. See DeleteVersionsInput
Returns:
​
success
bool
True if deletion was successful
Example: 
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")
DeleteVersionsInput Fields:
  • project_id (str, required) - The project ID
  • version_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
Parameters:
​
input
MarkReceivedVersionInput
required
Mark received parameters
Returns:
​
success
bool
True if successfully marked
Example: 
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")
MarkReceivedVersionInput Fields:
  • project_id (str, required) - The project ID
  • version_id (str, required) - The version ID to mark
  • message (str, optional) - Optional message
  • source_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.
​
id
str
Version ID
​
message
str
Commit message describing this version
​
referencedObject
str
The ID of the committed object
​
createdAt
datetime
Creation timestamp
​
authorUser
LimitedUser
User who created the version. See LimitedUser
​
sourceApplication
str
Application used to create the version
​
previewUrl
str
URL to preview image

​
Input Types

​
CreateVersionInput

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
)
Used with create(). Fields:
  • object_id (str) - ID of the object (from operations.send())
  • model_id (str) - Model ID
  • project_id (str) - Project ID
  • message (str, optional) - Version message/description
  • source_application (str, optional) - Source application name. Default: "py"
  • total_children_count (int, optional) - Total number of child objects
  • parents (List[str], optional) - Parent version IDs

​
UpdateVersionInput

UpdateVersionInput(
    version_id: str,
    project_id: str,
    message: Optional[str]
)
Used with update(). Fields:
  • version_id (str) - Version ID
  • project_id (str) - Project ID
  • message (str, optional) - New version message

​
DeleteVersionsInput

DeleteVersionsInput(
    version_ids: Sequence[str],
    project_id: str
)
Used with delete(). Fields:
  • version_ids (List[str]) - List of version IDs to delete
  • project_id (str) - Project ID

​
MoveVersionsInput

MoveVersionsInput(
    target_model_name: str,
    version_ids: Sequence[str],
    project_id: str
)
Move versions to a different model. Fields:
  • target_model_name (str) - Name of the target model
  • version_ids (List[str]) - Version IDs to move
  • project_id (str) - Project ID

Operations

Send and receive objects for versions

ModelResource

Manage models that contain versions

ServerTransport

Transport for sending/receiving data

SpeckleClient

Main client documentation
Last modified on January 28, 2026