Skip to main content
When you automate AEC workflows from C#, your code uses SpeckleSharp to talk to Speckle Server. Speckle Server stores projects, models, and versions. Each version holds the model’s objects, their properties, and the relations between them — structured model data instead of files. When to read this: before deep dives into guides or API reference. Read next: Build your first model analysis tool for a complete script, or Load and publish model data to pick a load or publish method.

The mental model

Most AEC automation scripts follow these steps:
  1. Authenticate — personal access token from an environment variable (recommended for scripts)
  2. Choose a project and model — IDs from the Speckle web app URL
  3. Load a version — usually the latest published version on that model
  4. Query objects — model.Objects, ObjectsWith, and relation accessors such as Level and Host on the Model that Receive3 returns
  5. Analyse or transform data — counts, QA checks, CSV export, custom logic
  6. Optionally publish results back — Send3 with a BundleBuilder when you want a new version
The recommended approach for most AEC automation scripts: PAT via env var → Receive3 latest version → query model.Objects → analyse → optional Send3.

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.
Object modeling for versions published before 2026.9 (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.
Base.GetId() is obsolete and does not match the IDs produced by every send path. Always use the ID returned by the send operation you actually called (Operations.Send, Send2, or SendPipeline) rather than computing it separately.

Transports

The classic Send/Receive + ServerTransport pair moves object graphs through a transport:
Example

Orphaned objects

Objects sent to the server but not referenced by any version are orphaned — stored with an object ID but unreachable through the Speckle UI until a version references them.
Example
Always create a version after sending data you want users to find.

The type system

Every object carries a speckle_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

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.
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.
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
Last modified on October 19, 2026