Publish a bundle from your own code

​

How a publish creates a version

# 1. Open the ingestion. The response carries the reserved version id.
mutation IngestionCreate($input: ModelIngestionCreateInput!) {
  projectMutations {
    modelIngestionMutations {
      create(input: $input) {
        id
        versionId
        cancellationRequested
      }
    }
  }
}

# While you convert: keep the idle clock alive and read the cancel flag.
mutation IngestionUpdateProgress($input: ModelIngestionUpdateInput!) {
  projectMutations {
    modelIngestionMutations {
      updateProgress(input: $input) {
        id
        cancellationRequested
      }
    }
  }
}

# On any failure: close the ingestion. failWithCancel and failWithInvalid have the same shape.
mutation IngestionFailWithError($input: ModelIngestionFailedInput!) {
  projectMutations {
    modelIngestionMutations {
      failWithError(input: $input) {
        id
      }
    }
  }
}

# 6. After complete: wait for a terminal status.
subscription ProjectModelIngestionUpdated($input: ProjectModelIngestionSubscriptionInput!) {
  projectModelIngestionUpdated(input: $input) {
    modelIngestion {
      id
      statusData {
        __typename
        ... on ModelIngestionSuccessStatus {
          versionId
        }
        ... on ModelIngestionProcessingStatus {
          progressMessage
          progress
        }
      }
    }
  }
}

{
  "input": {
    "projectId": "<projectId>",
    "modelId": "<modelId>",
    "progressMessage": "Sending from my-producer 1.0",
    "sourceData": {
      "sourceApplicationSlug": "my-producer",
      "sourceApplicationVersion": "1.0"
    },
    "maxIdleTimeoutSeconds": 600
  }
}

# 3. Sign. Bare filenames only, no paths.
POST /api/v2/projects/{projectId}/modelingestion/{ingestionId}/uploads/sign
Authorization: Bearer <token>
apollographql-client-name: my-producer
apollographql-client-version: 1.0
Content-Type: application/json

{ "files": ["<versionId>.envelope.meta.parquet", "<versionId>.eav.objects.parquet", "..."] }

200 { "uploads": { "<name>": { "url": "https://...", "key": "..." } } }

# 4. Upload. One PUT per file, no Authorization header, no extra headers.
PUT <presigned url>
<file bytes>

200  ETag: "<etag>"

# 5. Complete. ETags verbatim, quotes included.
POST /api/v2/projects/{projectId}/modelingestion/{ingestionId}/uploads/complete
Authorization: Bearer <token>
apollographql-client-name: my-producer
apollographql-client-version: 1.0
Content-Type: application/json

{
  "etags": { "<name>": "\"<etag>\"" },
  "rootId": "bundle.<projectId>.<modelId>.<versionId>",
  "totalChildrenCount": <object count>,
  "message": "Nightly export"
}

200 { "versionId": "<versionId>" }

from specklepy.api import operations
from specklepy.bundle import BundleBuilder, Producer, SendOptions

builder = BundleBuilder(Producer(slug="my-producer", version="1.0"), units="m")
# add objects, containers, levels, and relations on the builder

result = operations.send3(
    account, project_id, model_id, builder, SendOptions(message="Nightly export")
)
print(result.version_id, result.bundle_reference)

var producer = new SpeckleApplication
{
    HostApplication = "My producer",
    HostApplicationVersion = "1.0",
    Slug = "my-producer",
    SpeckleVersion = "2026.9",
};
using var builder = new BundleBuilder(producer, units: "m");
// add objects, containers, levels, and relations on the builder

var sent = await SpeckleBootstrap.Operations.Send3(
    account, projectId, modelId, builder, new SendOptions(Message: "Nightly export"), ct
);
var version = await SpeckleBootstrap.Operations.WaitForVersion(account, sent, cancellationToken: ct);

​

Rules that decide whether your bundle is correct

​

Identity

• applicationId must be stable across publishes and unique per placement. A linked file placed twice needs a per-placement suffix, or its objects and their topology collide.
• Key geometry on the placed object, never on a shared source block. Two objects sharing one mesh describe different world-space geometry.
• Derive geometry and definition keys from content, quantized, not from random ids. Random keys make material bindings fragile and defeat definition deduplication.
• An object with no properties, no geometry, and no relations is noise. Do not intern it.

​

Properties

• One value per row: exactly one of the string, number, or boolean columns is set. Numbers must be finite.
• Paths are dotted. Nesting is rebuilt from the path, never stored as a blob.
• Stamp the root scalars on every object: speckle_type, name, units, and the host’s own type.
• Parameters shared by a type go to the type tables once, linked from each object, not repeated per object.
• Decide a policy for multi-valued properties. The reference walk drops arrays; joining them is a valid alternative when your host emits them.

​

Geometry

• Write the SGEO header exactly: magic, version, primitive type, flags, the spec’s unit code, and a CRC32 over the body, all little-endian. Consumers verify the checksum. See Geometry encoding in 2026.9.
• DISPLAY, SOLID, and CENTERLINE each keep their own ordinal counter per object.
• Ship the solid beside the display mesh, not instead of it. Foreign hosts read the mesh.
• CENTERLINE is never a render edge. A consumer that drew every geometry an object owns would draw the axis through the duct.
• Shard the geometry table at 1536 MiB of uncompressed content. Shard zero keeps the canonical name. Readers glob all shards.

​

Instancing

• A definition owns its geometry once. Each placement is an instance node with a transform of 16 row-major doubles and its own units.
• When you convert transform units, scale only the translation column. Scaling all sixteen values resizes the instance.
• Definition members get no render edge. They keep an object row for properties and membership, and join back through DEFINES_MEMBER and PLACES. A member with a render edge draws twice.
• Create definition nodes before you walk placements, so a placement never references a nameless definition.

​

Grouping

• Membership is an edge (IN_COLLECTION, IN_MODEL, IN_GROUP, IN_SYSTEM). Nesting of containers is a parent reference on the container node. Do not conflate them.
• Containers are one node kind with a subtype (Layer, Collection, Folder, Model, Group, MEP System, Network). Key them by full path so two branches with the same leaf name stay distinct.
• The tree a viewer shows is a scene view: a recipe of tiers, some relations and some property paths. Declare one, or accept the default over IN_COLLECTION.
• Emit no container that would end up empty in the view.

​

Appearance

• Bind materials to geometry with HAS_MATERIAL. The object plane only fills where geometry has none, and is the only option for a placement.
• HAS_COLOR can start from geometry or from an object, and ord says which. Without it, the color lands on an unrelated element.
• Resolve inherited, by-layer appearance yourself. Land the layer’s material on the layer node and on each inheriting object’s own geometry.

​

Topology

• Emit an edge only when both ends are objects you sent. Resolve cross-object links in a second pass against your key map.
• ord is an ordinal on ordered relations and a scope tag on CONNECTS_TO. Read the catalog.
• HOSTED_ON runs hosted to host. Ownership (SUBELEMENT) wins over hosting when both apply.
• Never reuse a retired relation id, and never invent one.

​

Provenance and column binding

• Address parquet columns through the generated constants for your language. A spec column insertion must be a compile or import error, not a silent row shift. If your parquet library has no schema object, add an arity assertion yourself.
• Stamp schema_version as the spec’s semver string from the generated constant, pin the spec by commit, and write real produced_by and producer_version values. Leave the SDK columns null when you use none.
• Treat a dropped row as a failed publish. Count rows written, not rows attempted.

npm run validate -- <bundle-dir>

​

Suggested build order

​

FAQ