Skip to main content

Overview

The operations module loads and publishes Speckle data. receive3() loads a version as a Model and send3() publishes a new one. send(), receive(), serialize(), and deserialize() work with Base object graphs, the shape of versions published before 2026.9.
receive3() and send3() need the bundle extra: pip install "specklepy[bundle]==2026.9.0b3". To move existing send() / receive() code, see Migrate to 2026.9.

Load and Publish

receive3()

Load a version as a Model: objects with path-keyed properties and relation accessors.
Parameters:
Account
required
An authenticated account, for example client.account after authenticate_with_token, or get_default_account()
str
required
The version to load
bool
default:"True"
Set to False to skip downloading geometry when you only need properties and relations
bool
default:"True"
Record that this version was received, for the version’s activity
Returns:
Model
The loaded version. Use it as a context manager, or call model.close(), to delete the downloaded files. Query it with model.objects, model.objects_with(path), and model.object_by_application_id(id).
receive3() raises a SpeckleException when the version has no bundle — a version published before 2026.9 that the server has not converted. Load that version with receive().

send3()

Publish the objects described in a BundleBuilder as a new version.
Returns:
SendResult
Includes version_id, a reserved id. The version appears when the server finishes processing the upload. The builder cannot be reused.
See the Quickstart for a complete BundleBuilder example.

Object-graph Operations (before 2026.9)

send() and receive() move Base object graphs through transports. Keep receive() to read versions published before 2026.9; on a 2026.9 version it returns only a best-effort Base projection and needs an authenticated ServerTransport. Publishing with send() is deprecated, and Speckle does not guarantee it for new work: publish with send3(). After send(), client.version.create returns a reserved version id — see Publish through model ingestions.

send()

Send a Base object to one or more transports.
Parameters:
Base
required
The object to send
List[AbstractTransport]
default:"None"
Where to send the object. Defaults to local cache only.
bool
default:"True"
Whether to also save to the local SQLite cache
Returns:
str
The object ID (hash) of the sent object
Examples:
When you send an object, all nested Base objects are automatically sent too. You don’t need to send them separately.

receive()

Receive a Base object from a transport.
Parameters:
str
required
The ID of the object to receive
AbstractTransport
default:"None"
The transport to receive from (e.g., ServerTransport)
AbstractTransport
default:"None"
The local cache to check first. Defaults to SQLiteTransport
Returns:
Base
The received object, fully recomposed with all children
Examples:
receive() automatically reconstructs the entire object tree. All referenced child objects are fetched and recomposed.

Serialization

Note: The serialize() and deserialize() functions below are included for completeness, but most developers won’t need them directly. The send() and receive() operations handle serialization and deserialization implicitly. Use these functions only when you need custom workflows like saving objects to files or working with JSON representations directly.

serialize()

Serialize a Base object to a JSON string.
Parameters:
Base
required
The object to serialize
List[AbstractTransport]
default:"None"
Transports to write detached objects to. If None, objects are serialized inline without detachment
Returns:
str
JSON string representation of the object
Examples:
Without write transports, large nested objects are serialized inline, which can result in huge JSON strings. Use write transports for large objects.

deserialize()

Deserialize a JSON string back into a Base object.
Parameters:
str
required
JSON string to deserialize
AbstractTransport
default:"None"
Transport to read detached/referenced objects from. Defaults to SQLiteTransport
Returns:
Base
The deserialized object
Examples:
If the JSON contains references (like "@displayValue": "hash123..."), you must provide a read_transport that contains those referenced objects.

Detachment and Chunking

When send() writes an object graph, it detaches and chunks large objects automatically:
Objects like Mesh have predefined chunking and detachment rules. See the Mesh documentation for details.

Best Practices

Always let the local cache work for you:
Network operations can fail:
Be careful with deserialization:
Choose the right transport for your use case:

Summary

The operations module provides:
  • ✅ receive3() - Load a version as a queryable Model
  • ✅ send3() - Publish a BundleBuilder as a new version
  • ✅ send() / receive() - Move Base object graphs through transports (versions published before 2026.9)
  • ✅ serialize() / deserialize() - Convert Base objects to and from JSON strings

Next Steps

Transports

Learn about different transport types

SpeckleClient

Client for server authentication and resources
Last modified on October 19, 2026