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 aModel: objects with path-keyed properties and relation accessors.
An authenticated account, for example
client.account after authenticate_with_token, or
get_default_account()Set to
False to skip downloading geometry when you only need properties and relationsThe 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).send3()
Publish the objects described in aBundleBuilder as a new version.
Includes
version_id, a reserved id. The version appears when the server finishes processing the
upload. The builder cannot be reused.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.- Send to Server
- Send Complex Object
- Send to Multiple Transports
- Local Cache Only
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.- Receive from Server
- Receive with Local Cache
- Receive from Cache Only
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.Transports to write detached objects to. If
None, objects are serialized inline without
detachment- Simple Serialization
- Serialize with Detachment
- Save to File
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.Transport to read detached/referenced objects from. Defaults to SQLiteTransport
- Simple Deserialization
- Deserialize with References
- Load from File
Detachment and Chunking
Whensend() 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
Use local cache for better performance
Use local cache for better performance
Always let the local cache work for you:
Handle errors gracefully
Handle errors gracefully
Network operations can fail:
Don't deserialize untrusted JSON
Don't deserialize untrusted JSON
Be careful with deserialization:
Use appropriate transports
Use appropriate transports
Choose the right transport for your use case:
Summary
The operations module provides:- ✅ receive3() - Load a version as a queryable
Model - ✅ send3() - Publish a
BundleBuilderas a new version - ✅ send() / receive() - Move
Baseobject graphs through transports (versions published before 2026.9) - ✅ serialize() / deserialize() - Convert
Baseobjects to and from JSON strings
Next Steps
Transports
Learn about different transport types
SpeckleClient
Client for server authentication and resources