Speckle Automate API Reference

This reference documents the essential APIs and interfaces for developing functions in Speckle Automate. All APIs are available in both Python and C# SDKs.

Start with the Quickstart Guide to understand the basic concepts before using this API reference.

Function Inputs

Function inputs define what users can configure when running your automation. They automatically generate forms in the web interface.

Supported Types

Type	Python	C#	Use Case
Text	`str`	`string`	Names, descriptions, IDs
Number	`float`	`double`	Measurements, thresholds
Integer	`int`	`int`	Counts, indices
Boolean	`bool`	`bool`	Toggle options
Selection	`Enum`	`enum`	Choose from options
Secret	`SecretStr`	`[Secret]`	API keys, passwords

Validation Attributes

Validation	Python	C#	Description
Required	`Field(...)`	`[Required]`	Field must be provided
Length	`min_length=1, max_length=100`	`[MinLength(1)]`, `[MaxLength(100)]`	String length limits
Range	`gt=0, lt=100`	`[Range(0, 100)]`	Number value limits
Pattern	`pattern=r"^[A-Z]+$"`	`[RegularExpression("^[A-Z]+$")]`	Regex validation

Example: Simple Inputs

simple_inputs.py

from speckle_automate import AutomateBase
from pydantic import Field

class FunctionInputs(AutomateBase):
    project_name: str = Field(
        title="Project Name",
        description="Enter the project identifier"
    )

    max_length: float = Field(
        default=10.0,
        title="Maximum Length",
        description="Maximum allowed length in meters"
    )

    include_analysis: bool = Field(
        default=True,
        title="Include Analysis",
        description="Whether to perform detailed analysis"
    )

using Speckle.Automate.Sdk.Schema;

public class FunctionInputs
{
    [DisplayName("Project Name")]
    [Description("Enter the project identifier")]
    public string ProjectName { get; set; }

    [DisplayName("Maximum Length")]
    [Description("Maximum allowed length in meters")]
    public double MaxLength { get; set; } = 10.0;

    [DisplayName("Include Analysis")]
    [Description("Whether to perform detailed analysis")]
    public bool IncludeAnalysis { get; set; } = true;
}

dropdown_selections.py

from enum import Enum

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

class FunctionInputs(AutomateBase):
    analysis_type: AnalysisType = Field(
        default=AnalysisType.STRUCTURAL,
        title="Analysis Type",
        description="Select the type of analysis to perform"
    )

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

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

Example: Secure Inputs

secure_inputs.py

from pydantic import SecretStr

class FunctionInputs(AutomateBase):
    api_key: SecretStr = Field(
        title="API Key",
        description="Your external service API key"
    )

public class FunctionInputs
{
    [Secret]
    [DisplayName("API Key")]
    [Description("Your external service API key")]
    public string ApiKey { get; set; }
}

Automation Context

The AutomationContext is your function’s interface to Speckle. It provides access to data, authentication, and methods for reporting results.

Properties

automation_run_data

AutomationRunData

Metadata about the current automation run, including run ID, trigger information, and execution context

speckle_client

SpeckleClient

Pre-configured, authenticated client for Speckle API calls. Provides full access to the Speckle SDK functionality.

function_inputs

FunctionInputs

User-provided configuration values that were specified when the automation was triggered

🔧 Full SDK Access: The speckle_client property provides access to the complete Speckle SDK functionality. You can use all features from SpecklePy (Python) or SpeckleSharp (C#) within your Automate functions.📚 Python API Documentation: For detailed, auto-generated API reference documentation for specklepy, visit the specklepy API Documentation.

Methods

receive_version()

Base

Get the model that triggered this automation. Returns the complete Speckle data structure.

mark_run_success(message)

void

Report successful completion of the automation. Call this when your function completes successfully.

mark_run_failed(message)

void

Report business logic failure. Use this when validation fails or business rules are violated.

mark_run_exception(message)

void

Report unexpected error. Use this when an exception occurs that wasn’t part of normal business logic.

attach_error_to_objects(category, object_ids, message, metadata?)

void

Mark specific objects with errors. Useful for validation failures or processing errors on individual elements.

attach_warning_to_objects(category, object_ids, message, metadata?)

void

Add warnings to specific objects. Use for performance issues, recommendations, or non-critical problems.

attach_success_to_objects(category, object_ids, message, metadata?)

void

Mark objects as successfully processed. Useful for tracking which elements were processed correctly.

create_new_version_in_project(project_id, data, message)

string

Create a new model version with modified data. Returns the ID of the newly created version.

store_file_result(file_path, file_name)

string

Save a file as an artifact. Useful for reports, exports, or analysis results. Returns the artifact ID.

Getting Model Data

getting_model_data.py

await automate_context.receive_version() -> Base

Response

The Speckle model that triggered this automation

await context.ReceiveVersion() -> Base

Response (C#)

The Speckle model that triggered this automation

Status Reporting

Your function must report its final status using one of these methods:

status_reporting.py

automate_context.mark_run_success(message: str)
automate_context.mark_run_failed(message: str)
automate_context.mark_run_exception(message: str)

Parameters

A descriptive message explaining the status. For failures, include actionable information.

context.MarkRunSuccess(string message)
context.MarkRunFailed(string message)
context.MarkRunException(string message)

Parameters (C#)

A descriptive message explaining the status. For failures, include actionable information.

Annotating Objects

Add status information to specific objects in the model:

annotating_objects.py

automate_context.attach_error_to_objects(category, object_ids, message, metadata=None)
automate_context.attach_warning_to_objects(category, object_ids, message, metadata=None)
automate_context.attach_success_to_objects(category, object_ids, message, metadata=None)

Parameters

A category name to group related annotations (e.g., “Validation Errors”, “Performance Issues”)

List of object IDs to annotate with the status

A descriptive message explaining the status for these objects

Additional data to include with the annotation (e.g., error codes, thresholds)

context.AttachErrorToObjects(category, objectIds, message, metadata = null)
context.AttachWarningToObjects(category, objectIds, message, metadata = null)
context.AttachSuccessToObjects(category, objectIds, message, metadata = null)

Parameters (C#)

A category name to group related annotations (e.g., “Validation Errors”, “Performance Issues”)

Array of object IDs to annotate with the status

A descriptive message explaining the status for these objects

Additional data to include with the annotation (e.g., error codes, thresholds)

Creating New Model Versions

creating_versions.py

await automate_context.create_new_version_in_project(project_id, data, message) -> str

Parameters

The ID of the project where the new version will be created

The modified Speckle data to save as a new version

A commit message describing the changes in this version

Response

The ID of the newly created version

await context.CreateNewVersionInProject(projectId, data, message) -> string

Parameters (C#)

The ID of the project where the new version will be created

The modified Speckle data to save as a new version

A commit message describing the changes in this version

Response (C#)

The ID of the newly created version

Saving Files

saving_files.py

await automate_context.store_file_result(file_path, file_name) -> str

Parameters

The local path to the file you want to save as an artifact

The name that will be displayed for the file in the Speckle interface

Response

The ID of the saved artifact file

await context.StoreFileResult(filePath, fileName) -> string

Parameters (C#)

The local path to the file you want to save as an artifact

The name that will be displayed for the file in the Speckle interface

Response (C#)

The ID of the saved artifact file

Working with Speckle Data

Data Structure

Speckle models are directed acyclic graphs (DAGs):

Objects can reference other objects
Properties can be primitive values or object references
References are one-way (parent → child)
Common properties: elements, parameters, units, applicationId

Complete Function Example

Here’s a complete example that demonstrates all the key concepts:

complete_example.py

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)

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"
                );
                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;
    }
}

Next Steps

Function Inputs - Detailed input configuration
Working with Data - Advanced data processing patterns
Function Testing - Testing your functions
Creating Automations - Setting up automation workflows