What You Will Build
In this quickstart, you’ll learn how to:- Authenticate with Speckle Server
- Create a workspace project and model
- Describe a wall and a door in code
- Publish them as a new version
- Load the version back and query it
Prerequisites
- Install specklepy with the
bundleextra. It adds the parquet support that publishing and loading need:
- 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:- Using Token
- Using Local Account
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. Replaceyour_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
ABundleBuilder collects objects, their properties, their geometry, and the relations between them. Each object is identified by an application id you choose.
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
Useoperations.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.
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 scriptAPI Reference
Dive into the complete API documentation
Need Help?
Community Forum
Ask questions and get help
GitHub
View source code and report issues