Skip to main content

What You Will Build

In this quickstart, you’ll learn how to:
  1. Authenticate with Speckle Server
  2. Create a workspace project and model
  3. Describe a wall and a door in code
  4. Publish them as a new version
  5. Load the version back and query it
Let’s get started!

Prerequisites

  1. Install specklepy with the bundle extra. It adds the parquet support that publishing and loading need:
  1. Get a personal access token. In the web app, open the workspace switcher (the workspace name at the top of the left sidebar), select your name, then open Developer and create a token. See Authentication.
Updating a script written for operations.send and operations.receive? See Migrate to 2026.9.

Full Workflow

Step 1: Authentication

First, let’s authenticate with Speckle Server:
If this works, you’ll see your name printed!

Step 2: Create a Workspace Project and Model

Projects are the top-level containers for your data. A model holds the versions you publish. Replace your_workspace_id with an id returned by client.active_user.get_workspaces().
If project creation fails because your workspace can’t take another project, skip the create call and use an existing project’s ID instead.

Step 3: Describe Objects

A BundleBuilder collects objects, their properties, their geometry, and the relations between them. Each object is identified by an application id you choose.
Nested property dictionaries become dotted paths: the wall’s offset is stored as Constraints.Base Offset. door.host = wall records a typed relation instead of nesting the door inside the wall. See Object model and Relations.

Step 4: Publish a Version

Use operations.send3() to upload the objects. The server then processes them and creates the version, so wait for it before you load it:
Go to that URL to see the new version in the web app.
In a long-running script, add a timeout to the wait loop. If processing fails, the version is never created and you should publish again — see Publish through model ingestions.

Step 5: Load and Query the Version

Now let’s load the version back:
receive3 downloads the version’s bundle to a scratch directory and returns a Model. The with block deletes the files when you are done.
You’ve now completed your first full Speckle workflow with Python.

Complete Example

Here’s the complete script:

Next Steps

Now that you understand the basics, explore more advanced topics:

Object model

How properties and relations are stored in a version

Migrate to 2026.9

Move an existing operations.receive script

API Reference

Dive into the complete API documentation

Need Help?

Community Forum

Ask questions and get help

GitHub

View source code and report issues
Last modified on November 14, 2026