Load a bundle in your own code

​

Tell the two formats apart

​

How a load fetches a version

# 1. Read the version record and dispatch on its shape.
query VersionShape($projectId: String!, $modelId: String!, $versionId: String!) {
  project(id: $projectId) {
    model(id: $modelId) {
      version(id: $versionId) {
        id
        schemaVersion
        referencedObject
        sourceApplication
        message
      }
    }
  }
}

# 6. Record the receive.
mutation MarkReceived($input: MarkReceivedVersionInput!) {
  versionMutations {
    markReceived(input: $input)
  }
}

{
  "input": {
    "projectId": "<projectId>",
    "versionId": "<versionId>",
    "sourceApplication": "my-consumer"
  }
}

# 2. List. Use the model-level path without a version id for the latest version.
GET /api/v2/projects/{projectId}/models/{modelId}/versions/{versionId}/artifacts
Authorization: Bearer <token>

200 {
  "files": [
    { "name": "<versionId>.envelope.meta.parquet", "url": "https://...", "expiresAt": "..." },
    { "name": "<versionId>.geometries.parquet", "url": "https://...", "expiresAt": "..." },
    { "name": "<versionId>.viewer.dat", "url": "https://...", "expiresAt": "..." }
  ]
}
404 when the version has no bundle, or the token cannot read the project.

# 3. Download. No Authorization header on presigned URLs.
GET <presigned url>

from specklepy.api import operations

with operations.receive3(account, project_id, model_id, version_id) as model:
    print(model.units, len(model.objects), model.unknown_relations)
    for obj in model.objects_with("category"):
        print(obj.application_id, obj.name)

using var model = await SpeckleBootstrap.Operations.Receive3(
    account, projectId, modelId, versionId, cancellationToken: ct
);
Console.WriteLine($"{model.Units} {model.Objects.Count} {model.UnknownRelations.Count}");

​

Rules that decide whether your load is correct

​

Reading the files

• Read columns by name and tolerate columns you do not know. The spec adds columns without moving the version, so a bundle written before a column existed must still load.
• Read every geometry shard, {id}.geometries.parquet and {id}.geometries.{n}.parquet. A reader that opens only shard zero silently drops geometry above the shard cap.
• Treat a relation id or node kind missing from your vocabulary as skip-and-report, never as an error. A newer producer than your reader is normal.
• Do not gate on meta.schema_version. It is provenance, not a compatibility switch.

​

Identity

• A bare integer is meaningless without its namespace. The relation type’s source and target namespaces in rel_types say whether an end is an object, a node, or a geometry.
• The object’s identity is applicationId. If you project the bundle into a tree with ids on nodes, mint synthetic ids per bundle and expect them to differ across versions.

​

Properties

• Each row sets exactly one of the string, number, and boolean columns. Coalesce them.
• Rebuild nesting from the dotted path. properties.Constraints.Base Offset is a nested dictionary, not a flat key.
• Merge type-level rows into each object through the object-to-type link. Without that merge, most type parameters are missing.
• The root scalars speckle_type, name, units, and type sit beside properties.*, not under it.

​

Geometry

• Verify the CRC and decode by primitive type. See Geometry encoding in 2026.9.
• DISPLAY is what to render. Prefer a SOLID only when your host can read its format, and fall back to the display mesh otherwise. Never draw CENTERLINE as a body.
• Convert with the blob’s own unit, not a model-wide unit. Objects, instances, and geometry can disagree.

​

Instancing

• Expand a definition once through DEFINES, then place it for every DISPLAY_INSTANCE edge using the instance node’s transform, 16 row-major doubles in the instance’s units. Scale only the translation when you convert units. DEFINES_INSTANCE nests one definition in another.
• An object with no render edge is a carrier for a definition member’s properties and grouping. Skip it when you bake geometry, or the member draws twice, once untransformed at the origin. DEFINES_MEMBER and PLACES join carriers to their definition and placement.

​

Grouping

• Build the tree from the default scene view. Each tier is either a relation such as IN_MODEL or IN_COLLECTION, or a property path such as category. With no scene view, group by IN_COLLECTION.
• Nest containers through their parent reference column, not through a relation.
• IN_COLLECTION is single-valued. IN_GROUP and IN_SYSTEM are not.

​

Appearance

• Material fills from specific to general: HAS_MATERIAL on the geometry, then OBJECT_HAS_MATERIAL on the object, then NODE_HAS_MATERIAL on the object’s container.
• Color is presentational: OBJECT_HAS_COLOR overrides HAS_COLOR on the geometry, and NODE_HAS_COLOR is the container default.
• HAS_COLOR starts from a geometry or an object, and ord says which. Read it before you resolve the source key.
• Appearance edges are single-valued per source. When a bundle repeats one, the last row wins.

​

Placement

• Read modelPlacement.* and referencePoint.* from the model-scoped properties. When appliedToGeometry is true, stored coordinates are already in that datum. When it is false, apply the transform yourself. No rows means the internal origin.

​

Suggested build order

​

FAQ