ModelResource

Complete API reference for model operations in SpecklePy

Overview

The ModelResource provides methods for managing models within Speckle projects. Access it via client.model after authenticating your SpeckleClient.

Models are containers within projects that organize related versions of your data. Each model can have multiple versions representing different iterations or states.

from specklepy.api.client import SpeckleClient

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

# Access model operations
model = client.model.get("model_id", "project_id")

Methods

get()

Get a single model by ID.

client.model.get(model_id: str, project_id: str) -> Model

Parameters:

model_id · str · required

The ID of the model to retrieve

project_id · str · required

The ID of the project containing the model

Returns:

model · Model

The model object

Example:

model = client.model.get("model_abc123", "project_xyz789")

print(f"Model: {model.name}")
print(f"Display Name: {model.displayName}")
print(f"Description: {model.description}")
print(f"Created: {model.createdAt}")
print(f"Updated: {model.updatedAt}")
print(f"Author: {model.author.name}")
print(f"Preview URL: {model.previewUrl}")
else:
    print("Not authenticated")

See Model for property details.

get_models()

Get all models in a project with pagination support.

client.model.get_models(
    project_id: str,
    *,
    models_limit: int = 25,
    models_cursor: Optional[str] = None,
    models_filter: Optional[ProjectModelsFilter] = None
) -> ResourceCollection[Model]

Parameters:

project_id · str · required

The ID of the project

models_limit · int · default: "25"

Maximum number of models to return

models_cursor · str · default: "None"

Cursor for pagination

models_filter · ProjectModelsFilter · default: "None"

Filter criteria. See ProjectModelsFilter

Returns:

models · ResourceCollection[Model]

Collection with items, totalCount, and cursor

Example:

# Get all models in a project
models = client.model.get_models("project_id", models_limit=50)

print(f"Total models: {models.totalCount}")
for model in models.items:
    print(f"  - {model.displayName} (updated: {model.updatedAt})")

# Paginate through more models
if models.cursor:
    next_page = client.model.get_models(
        "project_id",
        models_cursor=models.cursor
    )
    print(f"Next page has {len(next_page.items)} models")

See ProjectModelsFilter for filtering options.

The ResourceCollection object includes: - items - List of Model objects - totalCount - Total number of models (across all pages) - cursor - Pagination cursor for next page (or None if no more pages)

get_with_versions()

Get a model with its versions included.

client.model.get_with_versions(
    model_id: str,
    project_id: str,
    *,
    versions_limit: int = 25,
    versions_cursor: Optional[str] = None,
    versions_filter: Optional[ModelVersionsFilter] = None
) -> ModelWithVersions

Parameters:

model_id · str · required

The ID of the model

project_id · str · required

The ID of the project

versions_limit · int · default: "25"

Maximum number of versions to return

versions_cursor · str · default: "None"

Cursor for pagination

versions_filter · ModelVersionsFilter · default: "None"

Filter criteria for versions. See ModelVersionsFilter

Returns:

model · ModelWithVersions

Model with versions collection

Example:

# Get model with its latest 10 versions
model = client.model.get_with_versions(
    "model_id",
    "project_id",
    versions_limit=10
)

print(f"Model: {model.displayName}")
print(f"Total versions: {model.versions.totalCount}")

for version in model.versions.items:
    print(f"  - {version.message}")
    print(f"    By: {version.authorUser.name}")
    print(f"    Created: {version.createdAt}")
    print(f"    Object ID: {version.referencedObject}")

See ModelVersionsFilter for filtering options.

Pagination:

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

while True:
    model = client.model.get_with_versions(
        "model_id",
        "project_id",
        versions_limit=100,
        versions_cursor=cursor
    )

    all_versions.extend(model.versions.items)

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

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

create()

Create a new model in a project.

client.model.create(input: CreateModelInput) -> Model

Parameters:

input · CreateModelInput · required

Model creation parameters. See CreateModelInput

Returns:

model · Model

The newly created model

Example:

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

See CreateModelInput for all available fields.

Advanced Example:

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

# Create multiple models for different disciplines
disciplines = [
    ("Architecture", "Architectural design and layout"),
    ("Structure", "Structural engineering elements"),
    ("MEP", "Mechanical, electrical, and plumbing systems"),
]

models = []
for name, desc in disciplines:
    model = client.model.create(CreateModelInput(
        project_id=project_id,
        name=name,
        description=desc
    ))
    models.append(model)
    print(f"✓ Created: {model.displayName}")

print(f"\nTotal: {len(models)} models created")

update()

Update an existing model’s properties.

client.model.update(input: UpdateModelInput) -> Model

Parameters:

input · UpdateModelInput · required

Model update parameters. See UpdateModelInput

Returns:

model · Model

The updated model

Example:

from specklepy.core.api.inputs.model_inputs import UpdateModelInput

# Update model details
updated_model = client.model.update(UpdateModelInput(
    id="model_id",
    projectId="project_id",
    name="Updated Model Name",
    description="Updated description with more details"
))

print(f"Updated: {updated_model.displayName}")
print(f"New description: {updated_model.description}")

See UpdateModelInput for all available fields.

delete()

Delete a model permanently.

client.model.delete(input: DeleteModelInput) -> bool

Parameters:

input · DeleteModelInput · required

Model deletion parameters. See DeleteModelInput

Returns:

success · bool

True if deletion was successful

Example:

from specklepy.core.api.inputs.model_inputs import DeleteModelInput

# Delete a model
success = client.model.delete(DeleteModelInput(
    projectId="project_id",
    modelId="model_id"
))

if success:
    print("✓ Model deleted successfully")
else:
    print("✗ Failed to delete model")

DeleteModelInput Fields:

• projectId (str, required) - The project ID
• modelId (str, required) - The model ID to delete

This operation is irreversible! All versions in the model will be permanently deleted. Consider archiving or exporting data before deletion.

Types

Model

Represents a Speckle model within a project.

id · str

Model ID

name · str

Model name (URL-safe identifier)

displayName · str

Human-readable display name

description · str

Model description

createdAt · datetime

Creation timestamp

updatedAt · datetime

Last update timestamp

previewUrl · str

URL to preview image

author · LimitedUser

User who created the model. See LimitedUser

Input Types

CreateModelInput

CreateModelInput(
    name: str,
    description: Optional[str] = None,
    project_id: str
)

Used with create().

Fields:

• name (str) - Model name
• description (str, optional) - Model description
• project_id (str) - Project ID

UpdateModelInput

UpdateModelInput(
    id: str,
    name: Optional[str] = None,
    description: Optional[str] = None,
    project_id: str
)

Used with update().

Fields:

• id (str) - Model ID
• name (str, optional) - New model name
• description (str, optional) - New description
• project_id (str) - Project ID

DeleteModelInput

DeleteModelInput(
    id: str,
    project_id: str
)

Used with delete().

Fields:

• id (str) - Model ID
• project_id (str) - Project ID

Filters

ProjectModelsFilter

ProjectModelsFilter(
    contributors: Optional[Sequence[str]] = None,
    exclude_ids: Optional[Sequence[str]] = None,
    ids: Optional[Sequence[str]] = None,
    only_with_versions: Optional[bool] = None,
    search: Optional[str] = None,
    source_apps: Optional[Sequence[str]] = None
)

Used with get_models() and client.project.get_with_models().

Fields:

• contributors (List[str], optional) - Filter by contributor user IDs
• exclude_ids (List[str], optional) - Exclude specific model IDs
• ids (List[str], optional) - Include only specific model IDs
• only_with_versions (bool, optional) - Only return models with versions
• search (str, optional) - Search by model name
• source_apps (List[str], optional) - Filter by source application

ModelVersionsFilter

ModelVersionsFilter(
    priority_ids: Sequence[str],
    priority_ids_only: Optional[bool] = None
)

Used with get_with_versions().

Fields:

• priority_ids (List[str]) - Version IDs to prioritize
• priority_ids_only (bool, optional) - Only return priority versions

Related Resources

VersionResource

Create and manage versions in models

ProjectResource

Manage projects that contain models

Operations

Send and receive data to/from models

SpeckleClient

Main client documentation