The mental model
The recommended workflow
Most AEC automation scripts follow these steps:- Authenticate — personal access token from an environment variable (recommended for scripts)
- Choose a project and model — IDs from the Speckle web app URL
- Load a version — usually the latest published version on that model
- Query objects —
model.Objects,ObjectsWith, and relation accessors such asLevelandHoston theModelthatReceive3returns - Analyse or transform data — counts, QA checks, CSV export, custom logic
- Optionally publish results back —
Send3with aBundleBuilderwhen you want a new version
Platform concepts
Speckle organizes data as projects → models → versions, not files. The GraphQL API exposes projects, models, and versions;IOperations loads and publishes the data inside a version. How that data is shaped: Object model.
IClient exposes each level as a typed resource:
Example
Some lower-level APIs (transports,
Send/Receive) still use streamId for what the GraphQL API
calls projectId. Pass your project’s id — they are the same value.Base, DataObject, Collection, detachment, displayValue): Work with model objects.
Load and publish model data
IOperations loads and publishes model data. For scripts and notebooks, Receive3 loads a version and Send3 publishes one. See Load and publish model data for every entry point.
Example
Object graphs before 2026.9
The sections below apply to the object-graph path (
Send, Send2, Receive2) used by versions
published before 2026.9. A 2026.9 version identifies objects by applicationId only. See Object
model.Object IDs (hashes)
Every sent object has a unique object ID, deterministically generated from its content.Transports
The classicSend/Receive + ServerTransport pair moves object graphs through a transport:
Example
Orphaned objects
Example
The type system
Every object carries aspeckle_type, derived from its .NET type, which lets Receive reconstruct the correct concrete type:
Example
Custom types and traversal: Work with model
objects. Geometry types: Working with
Geometry.
Local cache
Speckle.Sdk maintains a local SQLite cache under the current user’s application data folder (.../Speckle/), used automatically by Send/Receive when useDefaultCache: true.
FAQ
What happens if I send data but never create a version?
What happens if I send data but never create a version?
With
Send or Send2, the object is stored on the server with an object ID, but it is
orphaned until a version references it. Send3 creates the version for you when the server
finishes processing the upload.Should I use Send, Send2, or Send3?
Should I use Send, Send2, or Send3?
Use
Send3 to publish and Receive3 to load. Send, Send2, and the old receive
calls are obsolete, and Speckle does not guarantee them for new work; keep Receive2 or a
transport Receive only to read versions published before 2026.9. See Load and publish model
data.Why does streamId appear in transport code?
Why does streamId appear in transport code?
Older transport APIs use
streamId for what the GraphQL API calls projectId. Pass your
project’s id — they are the same value.Next Steps
Build your first model analysis tool
Load, query, and export a CSV report
Load and publish model data
Choose Receive3, Send3, or SendPipeline
Operations API
Receive3 and Send3 signatures