> ## Documentation Index
> Fetch the complete documentation index at: https://docs.speckle.systems/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> These docs contain multiple Speckle product experiences. For Speckle 2026.9, prefer /next/ pages for the topics and changes they cover. The navigation label Current does not override this version-specific precedence.
> Coverage under /next/ is incremental. Use Current documentation for unchanged topics and when a /next/ page says coverage is unavailable or explicitly refers you to Current. Do not infer a feature was removed from a missing page.
> Read the page-specific documentation status, applicability, affected guidance and replacement links in agent-only content. Impacted, changed and superseded apply only to the stated scope; they do not mean the entire feature is deprecated. Historical connector guides apply only to the legacy connector described.
> Match guidance to the customer's deployment version, model data format and connector. Respect plan, permission and compatibility restrictions. If an unknown version or data format changes the answer, ask a focused clarification; do not infer deployment version from the date alone.

# Publish, load, and integration depth

> Choose publish-only or publish-and-load for host connectors—and how far to invest beyond baseline publish extraction.

The first decision for host connectivity is **direction**: whether the integration **publishes** to Speckle, **loads** from Speckle, or does both. The second is **depth**: how much interoperability you implement on the load path (if any).

<Warning>
  **Do not design for round-tripping via Speckle.** Speckle is not a bidirectional model exchange
  format. Publish and load are separate workflows with different goals. Baseline **publish** depth
  is sufficient for many integrations; deeper load-side work is a deliberate product choice, not a
  requirement.
</Warning>

## Direction: publish, load, or both

| Mode | What it means | Typical use |
| - | - | - |
| **Publish only** | Host → Speckle (create versions). No load UI or conversion back into the host. | Most new CAD/BIM/structural connectors: extraction, coordination, dashboards, automation, analysis results in the cloud. |
| **Publish and load** | Both directions in one connector—but **not** semantic round-trip. | Desktop hosts where users publish their model and load others’ geometry or metadata for coordination (load-side depth beyond publish). |
| **Receive / load only** | Speckle → tool only. No publish path from that application. | **Uncommon for design hosts.** Example: [Power BI](/connectors/power-bi/power-bi) ([speckle-powerbi](https://github.com/specklesystems/speckle-powerbi) repo)—consumes published versions only. Not typical for new Revit-, Rhino-, or Tekla-style connectors. |

Most new **host** integrations should assume **publish only** until there is a clear user need to load Speckle data back into that host.

<Note>
  **Receive-only is not a default connector shape.** If you are building inside a CAD/BIM/structural
  application, implement **publish** depth first. Treat **load only** as a specialised product model
  like analytics and reporting tools, not as the third equal option for every host.
</Note>

SDK and API terms may say **send** and **receive**; user-facing connector docs often say **publish** and **load**. The concepts align: publish/send creates a **version**; load/receive materializes objects from a version into the host.

## Integration depth (increasing effort)

Depth describes how much you invest after the host can publish reliably. Each step adds load-side capability. **Many connectors never go beyond publish.**

| Depth | Focus |
| - | - |
| **Publish** | Geometry, metadata, analysis results into Speckle |
| **Load: reference geometry** | Coordination meshes and similar in the host |
| **Load: interop lite** | Category mapping, metadata on load |
| **Load: pragmatic interop** | Selected native object translations |

<Steps>
  <Step title="Publish">
    **Goal:** Reliable extraction from the host into Speckle.

    Includes:

    * Geometry (meshes, curves, points, display values)
    * Metadata (parameters, identifiers, discipline-specific properties)
    * Analysis or results payloads where the host exposes them

    **Outcome:** New **versions** in Speckle that downstream tools, viewers, and automations can consume without any load path in the host.

    **When to stop:** Coordination, visualization, ETL, reporting, or cloud processing only need published data. **Most connectors can ship at publish depth.**

    Speckle connectors (examples):

    * [ETABS](/connectors/etabs) — publish-only; structural model and analysis-oriented publish
    * [Tekla Structures](/connectors/teklastructures) — publish-only
    * [Navisworks](/connectors/navisworks) — publish-only; coordination and federation publish
    * [Revit](/connectors/revit/revit), [Rhino](/connectors/rhino/rhino), [Grasshopper](/connectors/grasshopper/grasshopper), [Blender](/connectors/blender), [Archicad](/connectors/archicad), [Civil 3D](/connectors/civil3d), [AutoCAD](/connectors/autocad), [SketchUp](/connectors/sketchup) — publish (and load where supported)

    **Docs:** [Data & build order](/developers/connectivity/data-and-build) · [Desktop host](/developers/connectivity/desktop-host) · [Data schema](/developers/data-schema/overview)
  </Step>

  <Step title="Load: reference geometry">
    **Goal:** Bring Speckle geometry into the host as **reference** content—not editable native model semantics.

    Typical behaviour:

    * Place meshes or simplified geometry for coordination
    * Optional transforms, layers, or visibility by source model
    * No expectation that edits in the host write back to Speckle

    **Requires:** Publish and load in the product sense, but still **not** round-trip.

    Speckle connectors (examples):

    * [Revit](/connectors/revit/revit) — default load as Direct Shapes (generic models) for coordination geometry
    * [Rhino](/connectors/rhino/rhino), [Blender](/connectors/blender), [SketchUp](/connectors/sketchup), [Archicad](/connectors/archicad), [Civil 3D](/connectors/civil3d), [AutoCAD](/connectors/autocad) — load workflows documented per connector

    **Docs:** [Display values](/developers/sdks/python/concepts/display-values) · [Geometry schema](/developers/data-schema/geometry-schema)
  </Step>

  <Step title="Load: interop lite">
    **Goal:** Smarter load without full native object reconstruction.

    Typical behaviour:

    * **Category mapping** — map Speckle types or layers to host categories, families, or styles
    * **Metadata transfer** — attach parameters or properties to reference elements
    * Still pragmatic: partial coverage, documented limitations

    **Tradeoff:** More useful than raw reference geometry; less cost than native translation.

    Speckle connectors (examples):

    * [Revit](/connectors/revit/revit) — materials and parameters on loaded objects; category and type behaviour described in connector FAQ
    * [Grasshopper](/connectors/grasshopper/grasshopper) — receive workflows with property and parameter-driven filtering

    **Docs:** [Connector schemas](/developers/data-schema/connector-index) · [Revit](/connectors/revit/revit) user guide
  </Step>

  <Step title="Load: pragmatic interop">
    **Goal:** Recreate selected native host objects from Speckle data where it is worth the maintenance.

    Typical behaviour:

    * Native walls, members, grids, or discipline-specific types where converters exist
    * Explicit scope: which types translate, which stay as reference geometry
    * Document what is **not** supported

    **Tradeoff:** Highest implementation and test burden. Still **not** round-trip: publish and load remain separate operations with different conversion logic.

    Speckle connectors (examples):

    * [Revit](/connectors/revit/revit) — native element load where supported by the connector
    * [Blocks as Families](/connectors/revit/blocks-to-families) — load block instances as Revit families (optional load setting)

    **Docs:** [Blocks as Families](/connectors/revit/blocks-to-families) · [Revit](/connectors/revit/revit) load FAQ
  </Step>
</Steps>

<Note>
  Connector depth varies by host and version. Use each connector’s user guide for supported publish
  types, load settings, and limitations—the lists above are illustrative, not exhaustive.
</Note>

## How depth maps to publish / load modes

| Mode | Integration depth usually in scope |
| - | - |
| Publish only (typical for new hosts) | Publish |
| Publish and load (desktop connectors with load) | Publish always; load-side depths only if load is a product requirement |
| Receive / load only (e.g. Power BI) | Consume published versions in the tool; no publish from that app |

## Product and engineering implications

* **Scope publish first.** Prove publish quality (units, stable ids, display values, analysis payloads) before investing in load converters.
* **Separate conversion codebases.** Publish converters and load converters should not assume symmetry; sharing utilities is fine, sharing 1:1 reversible mappings is not.
* **Set user expectations.** Document supported publish types, load types, and that edits in the host after load do not sync back via Speckle.
* **Prefer downstream consumption in Speckle** (viewer, dashboards, Automate, other connectors) instead of load when the goal is coordination only.

## Related

<CardGroup cols={2}>
  <Card title="Data & build order" icon="route" href="/developers/connectivity/data-and-build">
    Projects, models, versions, and suggested build sequence.
  </Card>

  <Card title="Desktop host" icon="desktop" href="/developers/connectivity/desktop-host">
    Add-ins and agents that implement publish and load.
  </Card>

  <Card title="Connector schemas" icon="database" href="/developers/data-schema/connector-index">
    Per-host data shapes for published objects.
  </Card>

  <Card title="Resources" icon="list" href="/developers/connectivity/resources">
    SDKs and reference repositories.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.