### Start File Ingestion Response Example

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/api/guides/file-uploads.mdx

Example response after starting a file ingestion. The `id` returned is used to track the job's status.

```json
{
  "data": {
    "fileUploadMutations": {
      "startFileIngestion": {
        "id": "your-file-ingestion-id",
        "statusData": {
          "status": "queued"
        }
      }
    }
  }
}
```

--------------------------------

### Clone and Setup Speckle Server Repository

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/server/development/setup.mdx

Clone the Speckle server repository, navigate into the directory, enable corepack, install dependencies, and build the project.

```bash
git clone git@github.com:specklesystems/speckle-server.git
cd speckle-server
corepack enable
yarn
yarn build
```

--------------------------------

### Configure and Start pgAdmin

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/server/deployment/backup-upgrade-restore.mdx

Sets up a new pgAdmin service using Docker Compose if it's not already running. Ensure the network matches your Speckle server setup.

```yaml
version: '3'
services:
  pgadmin:
    image: dpage/pgadmin4
    restart: always
    environment:
      PGADMIN_DEFAULT_EMAIL: 'admin@localhost.com'
      PGADMIN_DEFAULT_PASSWORD: 'admin'
    volumes:
      - pgadmin-data:/var/lib/pgadmin
    ports:
      - '127.0.0.1:16543:80'
networks:
  default:
    name: speckle-server
volumes:
  pgadmin-data:
```

--------------------------------

### Copy Example Environment Files

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/server/configuration/environment-variables.mdx

Copy the example environment files to your project to begin configuration.

```bash
cp packages/server/.env.example packages/server/.env
cp packages/server/.env.test-example packages/server/.env.test
cp packages/frontend-2/.env.example packages/frontend-2/.env
```

--------------------------------

### Complete Workflow: Send Data and Create Version

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/sdks/python/api-reference/resources/version.mdx

A comprehensive example demonstrating the full workflow: creating data (a Point), sending it to the server to get an object ID, and then creating a version referencing that object.

```python
from specklepy.api import operations
from specklepy.transports.server import ServerTransport
from specklepy.objects.geometry import Point
from specklepy.core.api.inputs.version_inputs import CreateVersionInput

# 1. Create your data
point = Point(x=10.5, y=20.3, z=5.1)

# 2. Send to server
transport = ServerTransport(stream_id=project_id, client=client)
object_id = operations.send(point, [transport])

# 3. Create version
version = client.version.create(CreateVersionInput(
    project_id=project_id,
    model_id=model_id,
    object_id=object_id,
    message="Added survey point",
    source_application="Python Script"
))

print(f"✓ Created version: {version.id}")
```

--------------------------------

### CI/CD Environment Variable Setup

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/sdks/python/getting-started/authentication.mdx

Example of setting up a Speckle token as a secret in a GitHub Actions workflow.

```yaml
# .github/workflows/example.yml
env:
  SPECKLE_TOKEN: ${{ secrets.SPECKLE_TOKEN }}
```

--------------------------------

### Start PostgreSQL with Docker

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/server/configuration/database-setup.mdx

Use this command to start a PostgreSQL instance using Docker Compose. Ensure your Docker Compose file is configured correctly.

```bash
docker-compose up postgres -d
```

--------------------------------

### Complete Example: Survey Data Pipeline

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/sdks/python/guides/simple-data-patterns.mdx

This example demonstrates creating custom survey data, including points with properties and units, and sending it to Speckle as a new version.

```python
from specklepy.api import operations
from specklepy.api.client import SpeckleClient
from specklepy.transports.server import ServerTransport
from specklepy.objects import Base
from specklepy.objects.geometry import Point

# 1. Create custom survey data
survey = Base()
survey.name = "Construction Site Survey"
survey.date = "2024-01-15"
survey.coordinate_system = "UTM Zone 32N"

survey.points = []
survey_data = [
    {"id": "SP001", "x": 500100, "y": 4000100, "z": 125.5, "type": "Control"},
    {"id": "SP002", "x": 500120, "y": 4000110, "z": 125.8, "type": "Control"},
    {"id": "SP003", "x": 500150, "y": 4000150, "z": 126.2, "type": "Detail"},
]

for data in survey_data:
    point = Point(x=data["x"], y=data["y"], z=data["z"])
    point.units = "m"
    point.properties = {
        "ID": data["id"],
        "Type": data["type"],
        "Accuracy": 0.01,
        "Method": "Total Station"
    }
    survey.points.append(point)

# 2. Send to Speckle
client = SpeckleClient(host="app.speckle.systems")
client.authenticate_with_token(token)

transport = ServerTransport(stream_id=project_id, client=client)
object_id = operations.send(survey, [transport])

# 3. Create version
from specklepy.core.api.inputs.version_inputs import CreateVersionInput

version_input = CreateVersionInput(
    project_id=project_id,
    model_id=model_id,
    object_id=object_id,
    message="Initial site survey data"
)
version = client.version.create(version_input)

print(f"✓ Survey data sent: {version.id}")

```

--------------------------------

### Install Viewer Package

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/packages/viewer.mdx

Install the Speckle Viewer package using npm.

```bash
npm install @speckle/viewer
```

--------------------------------

### Install Object Loader 2

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/packages/objectloader2.mdx

Install the @speckle/objectloader2 package using npm.

```bash
npm install @speckle/objectloader2
```

--------------------------------

### Install Object Sender Package

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/packages/objectsender.mdx

Install the @speckle/objectsender package using npm.

```bash
npm install @speckle/objectsender
```

--------------------------------

### ETABS Configuration Example

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/connectors/manual-installation/etabs.mdx

Example configuration for integrating Speckle with ETABS version 22. Ensure to replace `{VERSION}` with your specific ETABS version in all paths and settings.

```ini
[PlugIn]
NumberPlugIns=1
PlugInName=Speckle.Connectors.ETABS22
PlugInMenuText=Speckle for ETABS v3
PlugInPath=%AppData%\Computers and Structures\ETABS 22\Speckle\Speckle.Connectors.ETABS22.dll
```

--------------------------------

### Complete Example: Building Analysis with SpecklePy

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/sdks/python/concepts/data-traversal.mdx

This example demonstrates a full workflow of receiving building data from Speckle, performing analysis, and utilizing libraries like Pandas for data manipulation. It requires authentication and specifies project and version IDs.

```python
from specklepy.api import operations
from specklepy.api.client import SpeckleClient
from specklepy.transports.server import ServerTransport
from collections import defaultdict
import pandas as pd

# 1. Receive building data
client = SpeckleClient(host="app.speckle.systems")
client.authenticate_with_token(token)

version = client.version.get(project_id, version_id)
transport = ServerTransport(stream_id=project_id, client=client)
building = operations.receive(version.referencedObject, remote_transport=transport)

print(f"Received: {building.speckle_type}")
```

--------------------------------

### Example Response for Workspace Projects

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/api/graphql.mdx

An example JSON response structure for a query retrieving workspace projects.

```json
{
  "data": {
    "workspace": {
      "projects": {
        "totalCount": 4,
        "items": [
          {
            "id": "ad9c9929e6",
            "name": "Speckle First Project",
            "createdAt": "2025-10-15T12:06:46.315Z"
          },
          {
            "id": "6399c298d",
            "name": "Speckle Tower",
            "createdAt": "2026-02-04T16:30:57.240Z"
          },
          {
            "id": "e98ab96c9e",
            "name": "Speckle Demo Project",
            "createdAt": "2026-01-29T17:17:07.451Z"
          },
          {
            "id": "0387c91dvb",
            "name": "My amazing project",
            "createdAt": "2026-01-29T13:49:59.154Z"
          },
        ]
      }
    }
  }
}
  
```

--------------------------------

### Install SpecklePy and Pandas

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/workflows/revit-room-data-extraction-specklepy.mdx

Install the necessary Python libraries for SpecklePy and data manipulation with Pandas.

```bash
pip install specklepy pandas
```

--------------------------------

### File Ingestion Variables Example

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/api/guides/file-uploads.mdx

Example variables for the `startFileIngestion` mutation. The `fileId` must match the response from Step 1's `generateUploadUrl`.

```json
{
  "input": {
    "etag": "\"ad13b92e173...\"",
    "fileId": "file-id-from-step-1-response",
    "modelId": "the-target-model-id",
    "projectId": "your-project-id"
  }
}
```

--------------------------------

### Full RevitObject Example

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/data-schema/connectors/revit-schema.mdx

A comprehensive example of a RevitObject, showcasing all fields including geometry, properties, and Revit-specific attributes.

```json
{
  "id": "a1b2c3d4e5f6...",
  "speckle_type": "Objects.Data.DataObject:Objects.Data.RevitObject",
  "applicationId": "12345",
  "name": "Basic Wall - 200mm",
  "properties": {
    "Volume": 12.5,
    "Area": 45.2,
    "Instance Parameters": {
      "Wall Height": 3.0,
      "Base Offset": 0.0,
      "Top Offset": 0.0
    },
    "Type Parameters": {
      "Width": 0.2,
      "Function": "Exterior",
      "Structural Usage": "Non-bearing"
    },
    "Material Quantities": {
      "Concrete": {
        "Volume": 12.5,
        "Area": 45.2
      }
    }
  },
  "displayValue": [
    {
      "speckle_type": "Objects.Geometry.Mesh",
      "vertices": [0, 0, 0, 10, 0, 0, 10, 0, 3, 0, 0, 3, ...],
      "faces": [0, 1, 2, 0, 2, 3, ...],
      "units": "meters"
    }
  ],
  "type": "Basic Wall",
  "family": "Basic Wall",
  "category": "Walls",
  "level": "Level 1",
  "location": {
    "speckle_type": "Objects.Geometry.Line",
    "start": {"x": 0, "y": 0, "z": 0},
    "end": {"x": 10, "y": 0, "z": 0},
    "units": "meters"
  },
  "units": "meters"
}
```

--------------------------------

### List Syncs Variables Example

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/api/guides/updating-syncs.mdx

Example variables for the `ProjectSyncs` GraphQL query, specifying the project ID and retrieval limits.

```json
{
  "projectId": "0d1f93ec13",
  "limit": 25,
  "cursor": null
}
```

--------------------------------

### Complete Function Example

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/automate/api-reference.mdx

This example demonstrates a complete function for performing structural analysis and creating a new version with the results. It includes error handling and success marking.

```csharp
}
            context.MarkRunSuccess("Structural analysis completed successfully");
        }
        
        // Create new version with results
        await context.CreateNewVersionInProject(
            projectId: context.AutomationRunData.ProjectId,
            data: modelData,
            message: $"{inputs.Type} analysis results"
        );
    }
    catch (Exception e)
    {
        context.MarkRunException($"Analysis failed: {e.Message}");
    }
}

private static double CalculateStress(Beam beam)
{
    // Simplified stress calculation
    return beam.length * 10.0;
}
}
```

--------------------------------

### Complete Function Example (C#)

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/automate/api-reference.mdx

Provides a C# implementation of a Speckle Automate function, mirroring the Python example. Useful for .NET developers integrating with Speckle Automate.

```csharp
using Speckle.Automate.Sdk;
using Speckle.Automate.Sdk.Schema;
using System.ComponentModel.DataAnnotations;

public enum AnalysisType
{
    [Description("Structural Analysis")]
    Structural,
    [Description("Thermal Analysis")]
    Thermal
}

public class FunctionInputs
{
    [DisplayName("Analysis Type")]
    [Description("Type of analysis to perform")]
    public AnalysisType Type { get; set; } = AnalysisType.Structural;

    [Range(0, double.MaxValue)]
    [DisplayName("Maximum Stress (MPa)")]
    [Description("Maximum allowable stress")]
    public double MaxStress { get; set; } = 250.0;
}

public class AutomateFunction
{
    public static async Task Run(AutomateContext context, FunctionInputs inputs)
    {
        try
        {
            // Get the model data
            var modelData = await context.ReceiveVersion();
            
            // Find structural elements
            var beams = modelData.Traverse<Beam>();
            
            if (!beams.Any())
            {
                context.MarkRunFailed("No beams found in model");
                return;
            }
            
            // Perform analysis
            var failedBeams = new List<string>();
            foreach (var beam in beams)
            {
                var stress = CalculateStress(beam);
                beam.Parameters["calculated_stress"] = stress;
                beam.Parameters["safety_factor"] = 1.2;
            }
            
            // Report results
            if (failedBeams.Any())
            {
                context.AttachErrorToObjects(
                    category: "Stress Exceeded",
                    objectIds: failedBeams.ToArray(),
                    message: $"Stress exceeds maximum of {inputs.MaxStress} MPa"
                );
                context.MarkRunFailed($"{failedBeams.Count} beams exceed stress limit");
            }
            else
            {
                context.AttachSuccessToObjects(
                    category: "Analysis Complete",
                    objectIds: beams.Select(b => b.id).ToArray(),
                    message: "All beams within stress limits"

```

--------------------------------

### Start Speckle Server with Docker Compose

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/server/getting-started.mdx

Starts the Speckle server and all its dependent services in detached mode. Ensure you are in the directory containing your `docker-compose.yml` file before running this command.

```bash
docker compose up -d
```

--------------------------------

### Install Speckle Enterprise Helm Chart

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/server/deployment/enterprise-license.mdx

Install the Speckle Enterprise Server Helm chart using the provided package registry URL and your values.yaml file. Ensure the Enterprise version of the chart is specified.

```bash
helm install speckle-server <PACKAGE_REGISTRY_URL>/speckle-server-chart \
--namespace <NAMESPACE> \
-f values.yaml
```

--------------------------------

### Create and Get Project

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/sdks/python/api-reference/client.mdx

Demonstrates creating a new project with a name and description, then retrieving it using its ID.

```python
from specklepy.core.api.inputs.project_inputs import ProjectCreateInput

project = client.project.create(ProjectCreateInput(
    name="My Project",
    description="A new project"
))

retrieved = client.project.get(project.id)
```

--------------------------------

### Get Batch Start Index

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/viewer/render-view-api.mdx

Retrieves the start index within the batch's index buffer for this render view.

```typescript
get batchStart(): number
```

--------------------------------

### Get Ingestion Status Variables Example

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/api/guides/file-uploads.mdx

Example variables for the `Ingestion` query, requiring the `ingestionId` and `projectId` to fetch the job status.

```json
{
  "ingestionId": "your-file-ingestion-id",
  "projectId": "your-project-id"
}
```

--------------------------------

### Get Vertex Start Index

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/viewer/render-view-api.mdx

Retrieves the starting index for this render view's vertex position attribute array within its batch.

```typescript
get vertStart(): number
```

--------------------------------

### Initialize Speckle Client and Get Server Info

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/sdks/python/api-reference/resources/server.mdx

Demonstrates how to initialize a SpeckleClient and retrieve general server information. Ensure you have authenticated with a token before making requests.

```python
from specklepy.api.client import SpeckleClient

client = SpeckleClient(host="https://app.speckle.systems")
client.authenticate_with_token(token)

info = client.server.get()
```

--------------------------------

### Full IFC DataObject Example

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/data-schema/connectors/ifc-schema.mdx

This example shows a complete IFC DataObject, including geometry in 'displayValue' and detailed properties like IFC Type, GUID, attributes, and property sets.

```json
{
  "id": "ifc-abc123...",
  "speckle_type": "Objects.Data.DataObject",
  "applicationId": "ifc-guid-456",
  "name": "Basic Wall",
  "properties": {
    "IFC Type": "IfcWall",
    "IFC GUID": "3xKj$l5n1H5QvzJp7xH9$A",
    "IFC Attributes": {
      "GlobalId": "3xKj$l5n1H5QvzJp7xH9$A",
      "OwnerHistory": {...},
      "Name": "Basic Wall",
      "Description": null,
      "ObjectType": "Basic Wall",
      "ObjectPlacement": {...},
      "Representation": {...}
    },
    "Property Sets": {
      "Pset_WallCommon": {
        "IsExternal": true,
        "LoadBearing": false,
        "FireRating": "2h"
      },
      "Pset_Construction": {
        "ConstructionMethod": "In-situ",
        "Material": "Concrete"
      }
    }
  },
  "displayValue": [
    {
      "speckle_type": "Objects.Geometry.Mesh",
      "vertices": [0, 0, 0, 10, 0, 0, 10, 0, 3, 0, 0, 3, ...],
      "faces": [0, 1, 2, 0, 2, 3, ...],
      "units": "meters"
    }
  ],
  "units": "meters"
}
```

--------------------------------

### Initialize a project with uv and add specklepy

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/sdks/python/getting-started/installation.mdx

This sequence of commands initializes a new project with uv, creates a virtual environment, adds specklepy to the project's dependencies, and shows how to run a script within that environment.

```bash
# Install uv if you don't have it
pip install uv

# Create a new project with virtual environment
uv init my-speckle-project
cd my-speckle-project

# Add specklepy
uv add specklepy

# Run your script
uv run python main.py
```

--------------------------------

### Create a Basic Model

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/sdks/python/api-reference/resources/model.mdx

Creates a new model with essential parameters like project ID, name, and description. Use this for standard model creation.

```python
from specklepy.core.api.inputs.model_inputs import CreateModelInput

# Create a basic model
model = client.model.create(CreateModelInput(
    project_id="project_id",
    name="Main Design",
    description="Primary architectural design model"
))

print(f"Created model: {model.displayName} (ID: {model.id})")
```

--------------------------------

### IFC Properties Example

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/data-schema/connectors/ifc-schema.mdx

The 'properties' field contains IFC property set data, IFC type, IFC GUID, and IFC entity attributes. Property sets are nested under 'Property Sets'.

```json
{
  "properties": {
    "IFC Type": "IfcWall",
    "IFC GUID": "3xKj$l5n1H5QvzJp7xH9$A",
    "IFC Attributes": {
      "GlobalId": "3xKj$l5n1H5QvzJp7xH9$A",
      "OwnerHistory": {...},
      "Name": "Basic Wall",
      "Description": null
    },
    "Property Sets": {
      "Pset_WallCommon": {
        "IsExternal": true,
        "LoadBearing": false,
        "FireRating": "2h"
      },
      "Pset_Construction": {
        "ConstructionMethod": "In-situ"
      }
    }
  }
}
```

--------------------------------

### Verify specklepy installation by printing version

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/sdks/python/getting-started/installation.mdx

This Python script imports the specklepy library and prints its installed version to confirm the installation was successful.

```python
import specklepy
print(f"specklepy version: {specklepy.__version__}")
```

--------------------------------

### Complete Speckle Python Workflow Example

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/sdks/python/getting-started/quickstart.mdx

This script demonstrates a full Speckle workflow: authentication, project creation, geometry definition, sending data, creating a version, and receiving data back. Replace 'your_token_here' with your actual Speckle token.

```python
from specklepy.api.client import SpeckleClient
from specklepy.api import operations
from specklepy.objects.geometry import Point, Line, Polyline
from specklepy.objects import Base
from specklepy.transports.server import ServerTransport
from specklepy.core.api.inputs.project_inputs import ProjectCreateInput
from specklepy.core.api.inputs.model_inputs import CreateModelInput
from specklepy.core.api.inputs.version_inputs import CreateVersionInput
from specklepy.core.api.enums import ProjectVisibility

# 1. Authenticate
client = SpeckleClient(host="app.speckle.systems")
token = "your_token_here"  # Replace with your token
client.authenticate_with_token(token)
print(f"✓ Authenticated as {client.account.userInfo.name}")

# 2. Create project
project = client.project.create(ProjectCreateInput(
    name="My First Speckle Project",
    description="Learning specklepy",
    visibility=ProjectVisibility.PRIVATE
))
print(f"✓ Created project: {project.id}")

# 3. Create geometry
p1 = Point(x=0, y=0, z=0, units="m")
p2 = Point(x=10, y=0, z=0, units="m")
p3 = Point(x=10, y=10, z=0, units="m")
p4 = Point(x=0, y=10, z=0, units="m")

line = Line(start=p1, end=p2, units="m")

# Polyline uses a flat list of coordinates
coords = [
    p1.x, p1.y, p1.z,
    p2.x, p2.y, p2.z,
    p3.x, p3.y, p3.z,
    p4.x, p4.y, p4.z,
    p1.x, p1.y, p1.z,
]
polyline = Polyline(value=coords, units="m")

data = Base()
data.line = line
data.rectangle = polyline
data.points = [p1, p2, p3, p4]
print("✓ Created geometry")

# 4. Send data
# Send to server
transport = ServerTransport(stream_id=project.id, client=client)
object_id = operations.send(base=data, transports=[transport])
print(f"✓ Sent data: {object_id}")

# 5. Create version
# Create a new model
model_input = CreateModelInput(
    project_id=project.id,
    name="My first model",
    description="This is my first model"
)
model = client.model.create(model_input)

version_input = CreateVersionInput(
    project_id=project.id,
    model_id=model.id,
    object_id=object_id,
    message="My first version!"
)
version = client.version.create(version_input)
print(f"✓ Created version: {version.id}")
print(f"View: https://app.speckle.systems/projects/{project.id}/models/{model.id}")

# 6. Receive data
received_data = operations.receive(obj_id=object_id, remote_transport=transport)
print(f"✓ Received data: {len(received_data.points)} points")
```

--------------------------------

### Configure Speckle Server with Let's Encrypt Certificates

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/server/configuration/ssl-certificates.mdx

Enable SSL by setting SSL_ENABLED to true and specifying the paths to the Let's Encrypt private key and full chain certificate. These paths are typically found in the /etc/letsencrypt/live/your-domain.com/ directory.

```env
SSL_ENABLED=true
SSL_KEY_PATH=/etc/letsencrypt/live/your-domain.com/privkey.pem
SSL_CERT_PATH=/etc/letsencrypt/live/your-domain.com/fullchain.pem
```

--------------------------------

### Configure Environment Files for Speckle Server

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/server/development/setup.mdx

Copy example environment files to create configuration files for various Speckle server packages. Ensure these files are updated with your specific deployment variables.

```bash
cp packages/server/.env.example packages/server/.env
cp packages/server/.env.test-example packages/server/.env.test
cp packages/frontend-2/.env.example packages/frontend-2/.env
cp packages/fileimport-service/.env.example packages/fileimport-service/.env
cp packages/preview-service/.env.example packages/preview-service/.env
cp packages/webhook-service/.env.example packages/webhook-service/.env
cp packages/monitor-deployment/.env.example packages/monitor-deployment/.env
```

--------------------------------

### Install a specific version of specklepy

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/sdks/python/getting-started/installation.mdx

Install a particular version of specklepy by specifying the version number after '=='.

```bash
pip install specklepy==3.0.10
```

--------------------------------

### Initialize Speckle Client and Access Version Resource

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/sdks/python/api-reference/resources/version.mdx

Demonstrates how to initialize a SpeckleClient and access the version resource for operations. Ensure you replace 'token' with your actual authentication token.

```python
from specklepy.api.client import SpeckleClient

client = SpeckleClient(host="https://app.speckle.systems")
client.authenticate_with_token(token)

# Access version operations
version = client.version.get("version_id", "project_id")
```

--------------------------------

### Install specklepy with pip

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/sdks/python/getting-started/installation.mdx

Use this command to install the latest version of specklepy in your current Python environment.

```bash
pip install specklepy
```

--------------------------------

### Setup SpecklePy with .env file

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/workflows/notebooks/specklepy-model-data-analytics.ipynb

Configure your Speckle token and model URL in a .env file for authentication and data access.

```bash
SPECKLE_TOKEN=your_personal_access_token
SPECKLE_MODEL_URL=https://app.speckle.systems/projects/your_project_id/models/your_model_id
# Optional:
# SPECKLE_HOST=https://app.speckle.systems
```

--------------------------------

### Start Speckle Server Development Server

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/server/development/setup.mdx

Initiates the development server for the Speckle server, including the Node.js API and Vue.js frontend.

```bash
yarn dev
```

--------------------------------

### Get Current Camera Position

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/viewer/extensions/speckle-controls-api.mdx

Gets the current goal position of the control's target camera.

```typescript
abstract getPosition(): Vector3
```

--------------------------------

### Creating and Using a Point

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/sdks/python/guides/working-with-geometry.mdx

Shows how to create a Point object, set its units, calculate the distance to another point, and add custom properties.

```python
from specklepy.objects.geometry import Point

# Create a point
point = Point(x=10.0, y=20.0, z=5.0)
point.units = "m"

# Calculate distance
other = Point(x=15.0, y=20.0, z=5.0)
distance = point.distance_to(other)
print(f"Distance: {distance} {point.units}")  # Distance: 5.0 m

# Add custom properties
point.label = "Corner A"
point.timestamp = "2024-01-15"
```

--------------------------------

### Failed Ingestion Response Example

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/api/guides/file-uploads.mdx

Example response when a file ingestion job fails, including the `errorReason` for the failure.

```json
{
  "data": {
    "project": {
      "ingestion": {
        "statusData": {
          "status": "failed",
          "errorReason": "the reason for the failure"
        }
      }
    }
  }
}
```

--------------------------------

### Initialize Speckle Client and Access Project Operations

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/sdks/python/api-reference/resources/project.mdx

Initializes the Speckle client with a host and token, then accesses the project resource for further operations. Ensure you have a valid token.

```python
from specklepy.api.client import SpeckleClient

client = SpeckleClient(host="https://app.speckle.systems")
client.authenticate_with_token(token)

# Access project operations
project = client.project.get("project_id")
```

--------------------------------

### Create SpeckleClient for Hosted Server

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/sdks/python/api-reference/client.mdx

Instantiate a SpeckleClient for the default Speckle hosted server. Ensure you have the correct host URL.

```python
from specklepy.api.client import SpeckleClient

client = SpeckleClient(host="https://app.speckle.systems")
```

--------------------------------

### Get Current Camera Target

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/viewer/extensions/speckle-controls-api.mdx

Gets the current goal look position of the control's target camera.

```typescript
abstract getTarget(): Vector3
```

--------------------------------

### Creating a Speckle Project

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/sdks/python/concepts/overview.mdx

Shows how to create a new Speckle project using the client. Requires the ProjectCreateInput object for project details.

```python
from specklepy.core.api.inputs.project_inputs import ProjectCreateInput

project = client.project.create(ProjectCreateInput(
    name="Office Building Renovation",
    description="Main project for the renovation"
))
project_id = project.id
```

--------------------------------

### Measurement Tool Example

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/viewer/examples/more-extensions-example.mdx

This example showcases the default measurement tool, which supports PointToPoint, Perpendicular, and AutoLazer measurement modes.

```typescript
// Measurement tool functionality is demonstrated via the embedded example.
```

--------------------------------

### Example TeklaObject

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/data-schema/connectors/tekla-schema.mdx

A complete example of a TeklaObject, showcasing its fields including geometry, application ID, and detailed report data.

```json
{
  "id": "tekla-abc123...",
  "speckle_type": "Objects.Data.DataObject:Objects.Data.TeklaObject",
  "applicationId": "element-456",
  "name": "Beam - HEA200",
  "properties": {
    "Report": {
      "Profile": "HEA200",
      "Material": "S355",
      "Length": 5.0,
      "Weight": 125.5,
      "Part Number": "P1",
      "Assembly Number": "A1",
      "Start Point": {"x": 0, "y": 0, "z": 0},
      "End Point": {"x": 5, "y": 0, "z": 0}
    }
  },
  "displayValue": [
    {
      "speckle_type": "Objects.Geometry.Brep",
      "units": "meters"
    }
  ],
  "type": "Beam",
  "units": "meters"
}
```

--------------------------------

### Initializing and Authenticating the Client

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/sdks/python/api-reference/client.mdx

Demonstrates how to initialize the SpeckleClient with a server host and authenticate using a personal access token.

```APIDOC
## Initializing and Authenticating the Client

### Description
Instantiate the `SpeckleClient` with your server's host URL and authenticate your session using a personal access token.

### Method
```python
from specklepy.api.client import SpeckleClient

# Initialize client
client = SpeckleClient(host="https://your-speckle-server.com")

# Authenticate with a token
client.authenticate_with_token(your_token)
```

### Parameters
- **host** (str): The URL of the Speckle server.
- **your_token** (str): Your personal access token for authentication.
```

--------------------------------

### Create Speckle Server Directory

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/server/getting-started.mdx

Creates a directory for the Speckle server and navigates into it. This is the first step before setting up the Docker Compose file.

```bash
mkdir /opt/speckle/
cd /opt/speckle/
```

--------------------------------

### Full Civil3dObject Example

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/data-schema/connectors/civil3d-schema.mdx

A comprehensive example of a Civil3dObject, showcasing its ID, type, name, properties, displayValue, baseCurves, and units.

```json
{
  "id": "civil3d-abc123...",
  "speckle_type": "Objects.Data.DataObject:Objects.Data.Civil3dObject",
  "applicationId": "entity-456",
  "name": "Alignment - Main Road",
  "properties": {
    "Property Sets": {
      "Alignment Properties": {
        "Length": 1250.5,
        "Start Station": 0.0,
        "End Station": 1250.5
      }
    },
    "Part Data": {
      "Entity Type": "Alignment",
      "Style": "Centerline"
    }
  },
  "displayValue": [
    {
      "speckle_type": "Objects.Geometry.Polyline",
      "points": [
        {"x": 0, "y": 0, "z": 0},
        {"x": 100, "y": 50, "z": 0},
        {"x": 200, "y": 100, "z": 0}
      ],
      "units": "meters"
    }
  ],
  "baseCurves": [
    {
      "speckle_type": "Objects.Geometry.Polyline",
      "points": [
        {"x": 0, "y": 0, "z": 0},
        {"x": 100, "y": 50, "z": 0},
        {"x": 200, "y": 100, "z": 0}
      ],
      "units": "meters"
    }
  ],
  "units": "meters"
}
```

--------------------------------

### Start Docker Dependencies for Speckle Server

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/server/development/setup.mdx

Use this command to bring up the necessary Docker containers for the Speckle server development environment.

```bash
yarn dev:docker:up
```

--------------------------------

### Initialize Speckle Client and Access Other User Operations

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/sdks/python/api-reference/resources/other-user.mdx

Initializes the Speckle client with a host and token, then demonstrates how to access the `other_user` resource to retrieve a user by ID.

```python
from specklepy.api.client import SpeckleClient

client = SpeckleClient(host="https://app.speckle.systems")
client.authenticate_with_token(token)

# Access other user operations
user = client.other_user.get("user_id")
```

--------------------------------

### Install SpecklePy and Dependencies

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/workflows/specklepy-model-data-analytics.mdx

Install necessary Python packages for SpecklePy, DuckDB, Pandas, Requests, and Dotenv. Ensure you have Python 3.10+.

```bash
pip install specklepy duckdb pandas requests python-dotenv
```

--------------------------------

### Configure Environment Variables

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/workflows/specklepy-model-data-analytics.mdx

Set up a .env file with your Speckle personal access token, model URL, and optionally Speckle host and version ID. This avoids hardcoding sensitive information.

```bash
SPECKLE_TOKEN=your_personal_access_token
SPECKLE_MODEL_URL=https://app.speckle.systems/projects/your_project_id/models/your_model_id
# Optional:
# SPECKLE_HOST=https://app.speckle.systems
# SPECKLE_VERSION_ID=optional_specific_version
```

--------------------------------

### Full EtabsObject Example

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/data-schema/connectors/etabs-schema.mdx

A complete example of an EtabsObject representing a frame element, including its ID, type, properties, and display value.

```json
{
  "id": "etabs-abc123...",
  "speckle_type": "Objects.Data.DataObject:Objects.Data.EtabsObject",
  "applicationId": "element-456",
  "name": "Frame - Frame1",
  "properties": {
    "Assignments": {
      "Material": "Steel",
      "Section": "W24x55",
      "Property Modifiers": {
        "Area": 1.0,
        "Moment of Inertia": 1.0
      }
    },
    "Geometry Properties": {
      "Length": 5.0,
      "Start Point": {"x": 0, "y": 0, "z": 0},
      "End Point": {"x": 5, "y": 0, "z": 0}
    },
    "Object ID Properties": {
      "Label": "Frame1",
      "Level": "Level 1",
      "Design Orientation": "X"
    }
  },
  "displayValue": [
    {
      "speckle_type": "Objects.Geometry.Line",
      "start": {"x": 0, "y": 0, "z": 0},
      "end": {"x": 5, "y": 0, "z": 0},
      "units": "meters"
    }
  ],
  "type": "Frame",
  "units": "meters"
}
```

--------------------------------

### Get Transformed AABB

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/viewer/batch-object-api.mdx

Gets the axis-aligned bounding box of this object, considering its transformation. This is useful for working with object dimensions and positioning.

```typescript
get aabb(): Box3
```

--------------------------------

### Get Project Preview

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/api/previews/preview-service.mdx

Fetches the preview image for the latest version of a project. Replace `YOUR_SERVER_URL` with your Speckle server address and `abc123` with the project ID. An optional view angle like `iso`, `top`, or `front` can be appended.

```bash
curl https://YOUR_SERVER_URL/preview/abc123
```

--------------------------------

### Install SpecklePy and Dependencies

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/workflows/notebooks/specklepy-model-data-analytics.ipynb

Installs the necessary Python libraries for SpecklePy, DuckDB, Pandas, Requests, and Python DotEnv. Use this at the beginning of your notebook.

```python
%pip install -q specklepy duckdb pandas requests python-dotenv
```

--------------------------------

### Create a New Version

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/sdks/python/api-reference/resources/version.mdx

This snippet shows the initial import required to create a new version. The actual creation logic would involve instantiating `CreateVersionInput` and calling `client.version.create()`.

```python
from specklepy.core.api.inputs.version_inputs import CreateVersionInput
```

--------------------------------

### Instantiate Speckle Client

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/sdks/python/api-reference/client.mdx

Instantiate a SpeckleClient for a self-hosted server. Ensure you have your server URL and authentication token ready.

```python
company = SpeckleClient(host="https://speckle.company.com")
company.authenticate_with_token(company_token)
```

--------------------------------

### Differ Tool Example

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/viewer/examples/more-extensions-example.mdx

This example demonstrates the Differ tool for comparing models, providing both data-wise and visual diffs based on object IDs.

```typescript
// Differ tool functionality is demonstrated via the embedded example.
```

--------------------------------

### Create RenderMaterialProxy

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/sdks/python/concepts/proxification.mdx

Demonstrates creating a RenderMaterialProxy to assign render materials to multiple objects efficiently.

```python
from specklepy.objects.proxies import RenderMaterialProxy

material_proxy = RenderMaterialProxy(
    value=render_material_object,  # Material definition (stored once)
    objects=["obj-guid-1", ...]    # Objects using this material
)

# Accessed at root
material_proxies = getattr(root, "renderMaterialProxies", [])
```

--------------------------------

### Example AutoCAD Instance Object

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/data-schema/connectors/autocad-schema.mdx

An example of an Instance object, showing its ID, application ID, definition ID for the block, transformation matrix, and units.

```json
{
  "id": "instance-xyz789...",
  "speckle_type": "Objects.Instance",
  "applicationId": "instance-handle-789",
  "definitionId": "block-door",
  "transform": {
    "speckle_type": "Objects.Geometry.Matrix",
    "value": [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 5, 10, 0, 1]
  },
  "units": "meters"
}
```

--------------------------------

### Quick Start: Load and Construct Object

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/packages/objectloader2.mdx

Initialize the ObjectLoader with a client and object ID, then load and construct the Speckle object.

```typescript
import { ObjectLoader } from '@speckle/objectloader2';

// Initialize loader
const loader = new ObjectLoader(client, objectId);

// Load object
const object = await loader.getAndConstructObject();
```

--------------------------------

### Successful Ingestion Response Example

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/api/guides/file-uploads.mdx

Example response when a file ingestion job completes successfully, providing the `versionId` of the newly created model version.

```json
{
  "data": {
    "project": {
      "ingestion": {
        "statusData": {
          "status": "success",
          "versionId": "the-new-version-id-created-from-the-import"
        }
      }
    }
  }
}
```

--------------------------------

### Complete Function Example (Python)

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/automate/api-reference.mdx

Demonstrates a full Speckle Automate function, including input definition, data retrieval, analysis, reporting, and version creation. Use this as a template for your own functions.

```python
from speckle_automate import AutomateBase, execute_automate_function
from pydantic import Field
from enum import Enum

class AnalysisType(str, Enum):
    STRUCTURAL = "structural"
    THERMAL = "thermal"

class FunctionInputs(AutomateBase):
    analysis_type: AnalysisType = Field(
        default=AnalysisType.STRUCTURAL,
        title="Analysis Type",
        description="Type of analysis to perform"
    )
    
    max_stress: float = Field(
        default=250.0,
        title="Maximum Stress (MPa)",
        description="Maximum allowable stress",
        gt=0
    )

async def automate_function(automate_context, function_inputs):
    try:
        # Get the model data
        model_data = await automate_context.receive_version()
        
        # Find structural elements
        beams = model_data.query(lambda obj: 
            obj.speckle_type == "Objects.BuiltElements.Beam"
        )
        
        if not beams:
            automate_context.mark_run_failed("No beams found in model")
            return
        
        # Perform analysis
        failed_beams = []
        for beam in beams:
            stress = calculate_stress(beam)
            beam.parameters["calculated_stress"] = stress
            
            if stress > function_inputs.max_stress:
                failed_beams.append(beam.id)
        
        # Report results
        if failed_beams:
            automate_context.attach_error_to_objects(
                category="Stress Exceeded",
                object_ids=failed_beams,
                message=f"Stress exceeds maximum of {function_inputs.max_stress} MPa"
            )
            automate_context.mark_run_failed(f"{len(failed_beams)} beams exceed stress limit")
        else:
            automate_context.attach_success_to_objects(
                category="Analysis Complete",
                object_ids=[beam.id for beam in beams],
                message="All beams within stress limits"
            )
            automate_context.mark_run_success("Structural analysis completed successfully")
        
        # Create new version with results
        await automate_context.create_new_version_in_project(
            project_id=automate_context.automation_run_data.project_id,
            data=model_data,
            message=f"{function_inputs.analysis_type.title()} analysis results"
        )
        
    except Exception as e:
        automate_context.mark_run_exception(f"Analysis failed: {str(e)}")

def calculate_stress(beam):
    # Simplified stress calculation
    return getattr(beam, "length", 0) * 10.0

if __name__ == "__main__":
    execute_automate_function(automate_function, FunctionInputs)

```

--------------------------------

### Listing Projects on Different Server Types

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/sdks/python/api-reference/client.mdx

Demonstrates how to list projects, differentiating between servers with workspace features and those without.

```APIDOC
## Listing Projects on Different Server Types

### Description
This method shows how to list projects, adapting the approach based on whether the server supports workspaces. For workspace-enabled servers, it lists projects within workspaces and personal projects. For others, it lists all accessible projects.

### Method
```python
# Assuming 'client' is an authenticated SpeckleClient instance

info = client.server.get()
has_workspaces = info.workspaces and info.workspaces.workspacesEnabled

if has_workspaces:
    # Workspace-enabled server (e.g., https://app.speckle.systems)
    # List workspace projects
    workspaces = client.active_user.get_workspaces()
    for ws in workspaces.items:
        projects = client.workspace.get_projects(ws.id)
        print(f"Workspace {ws.name}: {projects.totalCount} projects")

    # List personal projects
    from specklepy.core.api.inputs.user_inputs import UserProjectsFilter
    personal = client.active_user.get_projects(
        filter=UserProjectsFilter(personalOnly=True)
    )
else:
    # Non-workspace server (self-hosted/open-source)
    # List all accessible projects
    projects = client.active_user.get_projects()
    print(f"Total projects: {projects.totalCount}")
```

### Notes
- Earlier versions of `specklepy` used `stream.list()`, which has been replaced by the resource-based approach shown above.
```

--------------------------------

### Sync Update Response Example

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/api/guides/updating-syncs.mdx

This is an example of a successful response after updating a sync. It includes the sync ID, active status, updated context, and timestamp.

```json
{
  "data": {
    "syncMutations": {
      "update": {
        "id": "3d5085bbcc",
        "active": true,
        "context": {
          "referencePoint": "surveyPoint",
          "viewName": null
        },
        "updatedAt": "2026-05-06T14:55:00.000Z"
      }
    }
  }
}
```

--------------------------------

### Paginate Through All Versions

Source: https://github.com/specklesystems/speckle-docs-new/blob/main/developers/sdks/python/api-reference/resources/version.mdx

This example demonstrates how to retrieve all versions from a model by repeatedly calling `get_versions` and using the cursor to fetch subsequent pages until no more versions are available.

```python
# Get all versions (paginated)
all_versions = []
cursor = None

while True:
    versions = client.version.get_versions(
        "model_id",
        "project_id",
        limit=100,
        cursor=cursor
    )

    all_versions.extend(versions.items)

    if not versions.cursor:
        break
    cursor = versions.cursor

print(f"Retrieved {len(all_versions)} versions total")
```