Skip to main content

Overview

The Speckle Server provides a comprehensive GraphQL API that powers most interactions with your data. The complete, up-to-date API reference is available through Apollo Studio.

Documentation

Access the full GraphQL API reference at: Apollo Studio - Speckle Server API This interactive documentation provides:
  • Complete Schema: Browse the entire GraphQL schema with detailed descriptions for all types, queries, mutations, and subscriptions
  • Field Documentation: Inline documentation for every field, argument, and return type
  • Interactive Explorer: Test queries directly in your browser with the built-in GraphQL explorer
  • Type Definitions: Full type definitions and relationships between objects

Changelog

The Apollo Studio reference also includes a changelog that tracks all changes to the GraphQL API. This allows you to:
  • Stay informed about new features and capabilities
  • Track breaking changes and deprecations
  • Plan updates to your integrations
  • Review the evolution of the API over time
Access the full changelog at: Apollo Studio - API Changelog

Using the API

Authentication

To authenticate your GraphQL requests, you’ll need a personal access token. Include it in your requests:

Endpoint

The GraphQL endpoint for app.speckle.systems is:
For self-hosted instances, replace the domain with your server’s address.

Example Query

Here’s a simple example query to get started:

Query user data

Query workspace projects data

Variable: workspace ID. You can find it under Workspace Settings > General.

Get element data from a version

Scripts, low-code flows (Power Automate, Zapier, n8n), and custom integrations that read element data through the API need to know which format a version uses. A version is either a bundle, the format that file uploads, cloud syncs, and 2026.9 connectors produce, or an object graph, published before 2026.9 or by an older connector. Element queries work differently for each. For the model behind the change, see Object model and Data model migration for developers.
Sending a bundle version’s referencedObject to the object endpoints (/objects/ {projectId}/{objectId}, Project.object(id)) returns 404 with error: "BUNDLE_REFERENCE_NOT_FOUND". Treat that as “this version is a bundle,” never as “empty model.”

Tell the two formats apart

You can tell which format a version uses from the shape of its referencedObject. Check the shape of referencedObject on the version you actually have. Do not assume it from the upload date alone.

What bundle versions do not support

For a version whose referencedObject is a bundle reference, these do not work. There is no GraphQL-level replacement for the filtering and selection behavior. See Read element properties for what to use instead.
  • Object.children(query:, select:, limit:): the server-side filter and select mechanism (for example, filtering by an IFC type and selecting a handful of property paths in one request).
  • Object.totalChildrenCount: there is no object tree to count against.
  • Project.object(id: referencedObject): the reference is not a content hash, so there is nothing to look up.
  • Reading geometry as JSON (the data field): bundle geometry is stored in a binary format read by the Viewer and SDKs, not served as a JSON payload.
  • The properties downloads (.../eav/download): they serve object-graph versions only. For a bundle version they return 404 with "Version not found or has no EAV artefact". The properties export (.../eav/query) serves both formats.

Read element properties

How you read element properties depends on the version’s format, not on your tooling.
  • Bundle: read the version’s bundle files. List them with the artifacts endpoint, which returns presigned URLs to the version’s parquet files, then read only the columns and rows you need. Or download the whole properties table with the properties export.
  • Object graph: filter and select with object.children, or download the whole properties table with the properties export.
PROJECT_ID, MODEL_ID, VERSION_ID, the referenced object id, and your token are already known.
Bundle
Properties are in the bundle’s eav Parquet files. Five of them hold everything the properties export returns: The values are value_string, value_double, and value_boolean, plus unit. To get every property of every object:
  1. Join eav to paths on path_index for the property names.
  2. Join object_type to type_eav on type_index, and add those rows to each object, so objects carry their type’s properties (most Revit type parameters live there).
  3. Join to objects on object_index to key each row by application_id.
The full layout is in What a bundle contains.

Query a bundle

Any Parquet reader can do those joins: pyarrow or Polars in Python, hyparquet in TypeScript, Parquet.Net in .NET. Power BI and Excel can load Parquet files with Power Query. Speckle’s examples use DuckDB, because the same SQL runs in every language and it reads the presigned URLs directly, with no download step. This query returns one row per property in the same columns as the properties export, with object_id holding the object’s applicationId. Replace each {placeholder} with the URL of the file it names:
To keep only some objects, wrap the query and filter it. For example, every IfcDoor:
In each, the artifacts URL is the endpoint above, and the query is the SQL above. The complete version of each, with error handling and tests, is in the example below.

From Power Automate, Zapier, or n8n Cloud

For a step-by-step setup aimed at flow builders, see Use model properties in low-code tools. These tools can call an HTTP endpoint but cannot read Parquet. They can call the properties export directly, which returns the whole properties table as JSON. To filter before the rows reach the flow, put the query above in a small function they call instead. examples/bundle-properties-function is that function as an Azure Function in Python, TypeScript, and C#. It takes a project, model, and version id, and returns the rows above as JSON. Its README covers running it locally, deploying it, and calling it from a Power Automate HTTP action. Take the directory on its own:
Because the rows match the properties export’s columns, a flow that filtered the export filters this the same way. The function returns every property of every object; on a large model, add a WHERE clause to its query so the flow receives only the rows it needs.

Properties export

For any version, bundle or object graph, the properties export returns every indexed property on every element, one row per property, rather than a pre-filtered result:
To reproduce the “every IfcDoor” filter from the object-graph query, filter that array yourself:
1

Find matching object ids

Filter the rows for path == "ifcType" and value_text == "IfcDoor", and collect their object_id values. The outcome is the id of every door in the model.
2

Pull their other properties

Filter the full array again for rows whose object_id is one of those ids. The outcome is every property row belonging to a matching element.
3

Group by object_id

Group the result by object_id to get one record per door with its properties. The outcome matches what select returns, without the size limit.
In a low-code tool, that is two filter steps in sequence: two Filter array actions in Power Automate, or two Filter nodes in n8n. There is also a GET .../versions/{versionId}/eav/download variant for a plain download, and a GET .../models/{modelId}/eav/download variant that serves the model’s latest version. Unlike the export, both serve object-graph versions only.
The properties export does not accept filter parameters. It always returns the whole properties table, and you filter after receiving it. That is fine at door-count scale, and slow on a model with hundreds of thousands of elements.

From an SDK instead of raw HTTP

For anything that can run code rather than a low-code flow, an SDK reads the bundle directly instead of downloading the full properties table yourself:

Query an object graph with object.children

For a version whose referencedObject is a hex string, children(select:, query:) still works. In this example, we query the children of a specific object, using the GraphQL arguments select and query to filter and return specific fields. We filter for objects with the category “Structural Columns” and retrieve the following information for each child: category, level, name, element ID, length dimension
children(select:, query:) works only on object graphs. Do not build new work on it: file uploads, cloud syncs, and 2026.9 connector publishes are bundles. Use Read element properties for bundle versions.
Variables: Project ID & Object ID
  • Project ID: This identifies your project. Find it in the project URL: https://app.speckle.systems/projects/{projectId}/...
  • Object ID: Unique identifier for the object. To find it: open Dev Mode in the Speckle Web App, then inspect the object’s data.
The root object ID is the first ID shown in Dev Mode. Use it to query the full model. Bundle versions have no root object.

Element data FAQ

Probably not. If the failure happens at upload time, with a 400 error and code UNSUPPORTED_FILE_TYPE, you are almost certainly still calling the removed startFileImport mutation, which the server rejects as of the 2026.9 release (1 September 2026). See File uploads to switch to startFileIngestion. This section covers a different symptom: uploads that succeed, but querying elements back afterward returns null or empty.
The version you queried is a bundle. Check whether referencedObject is a bundle. reference (see Tell the two formats apart). This is not a bug or a temporary gap: server-side filtering over the object tree does not apply to bundles. Read the bundle instead; see Read element properties.
Yes, unchanged. Nothing in this section affects a version whose referencedObject is a hex string. The two formats can coexist, so check the version you actually have rather than assuming based on project or workspace.
Probably not. A version’s id is reserved as soon as ingestion starts, but the version and its properties do not exist until ingestion succeeds, which can take from several seconds to around a minute depending on the file. Querying immediately after upload legitimately shows nothing. Poll Model.latestIngestion.statusData until it reports ModelIngestionSuccessStatus, then query the version it names. Do not fire the read on a timer or a webhook that is not tied to ingestion completion.
Yes. eav/query returns the same columns for bundle and object-graph versions. The eav/download variants serve object-graph versions only, and return 404 with "Version not found or has no EAV artefact" for a bundle version. A version still being processed returns the same 404 from both.
For bundle versions, count the rows in the version’s .eav.objects.parquet file, or use an SDK’s native accessors (see From an SDK instead of raw HTTP).
Not natively, in most cases. Power Automate and Zapier have no built-in way to parse Parquet. n8n is a partial exception: its Code node cannot import external npm packages on n8n Cloud, so the same limitation applies there, but a self-hosted n8n instance can read Parquet if you enable external modules (NODE_FUNCTION_ALLOW_EXTERNAL) or install a community node built for it. That is a deliberate setup step, not the default. Tools that cannot run DuckDB or read Parquet can call the properties export instead, or a small function that reads the bundle. See From Power Automate, Zapier, or n8n Cloud.
How much of the table you need decides it. The properties export always returns every property of every element, for either format. To read only some columns or rows of a bundle version, read the bundle; for an object-graph version, use object.children. Check referencedObject on the version you are reading (see Tell the two formats apart).
Yes. Format is decided per version, when it is created, not per project or workspace. Older versions can be hex-referenced while newer versions on the same model are bundle-referenced. Always check the version you are reading, never assume from a sibling version or from when the project was created.

Additional Resources

Last modified on November 17, 2026