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
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 forapp.speckle.systems is:
Example Query
Here’s a simple example query to get started:Query user data
Query workspace projects data
Response Example
Response Example
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.Tell the two formats apart
You can tell which format a version uses from the shape of itsreferencedObject.
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 whosereferencedObject 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
datafield): 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
- Object graph
eav Parquet files. Five of them hold everything the properties
export returns:
value_string, value_double, and value_boolean, plus unit. To get every
property of every object:
- Join
eavtopathsonpath_indexfor the property names. - Join
object_typetotype_eavontype_index, and add those rows to each object, so objects carry their type’s properties (most Revit type parameters live there). - Join to
objectsonobject_indexto key each row byapplication_id.
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, withobject_id holding the object’s
applicationId. Replace each {placeholder} with the URL of the file it names:
IfcDoor:
- Python
- TypeScript
- C#
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: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:IfcDoor” filter from the object-graph query, filter that array yourself:
Find matching object ids
path == "ifcType" and value_text == "IfcDoor", and collect their
object_id values. The outcome is the id of every door in the model.Pull their other properties
object_id is one of those ids. The outcome is every
property row belonging to a matching element.Group by object_id
object_id to get one record per door with its properties. The outcome
matches what select returns, without the size limit.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.
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:- Python:
operations.receive3gives direct, filtered property access (model.objects_with("ifcType")). See Migrate a specklepy script to 2026.9. - .NET:
Receive3gives the same access. See Migrate a Speckle.Sdk script to 2026.9.
Query an object graph with object.children
For a version whosereferencedObject 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
- 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.
Response example
Response example
Element data FAQ
My upload fails outright with an error. Is that this section?
My upload fails outright with an error. Is that this section?
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.Why did my object.children query suddenly return null?
Why did my object.children query suddenly return null?
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.Can I still use object.children for versions created before 2026.9?
Can I still use object.children for versions created before 2026.9?
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.I just uploaded a file and the version and properties endpoints return nothing yet. Is something wrong?
I just uploaded a file and the version and properties endpoints return nothing yet. Is something wrong?
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.Does the properties export work for bundle versions?
Does the properties export work for bundle versions?
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.How do I get a total element count without walking the whole properties table?
How do I get a total element count without walking the whole properties table?
.eav.objects.parquet file, or use an
SDK’s native accessors (see From an SDK instead of raw
HTTP).Can a low-code tool like Power Automate, Zapier, or n8n read the bundle artifacts directly?
Can a low-code tool like Power Automate, Zapier, or n8n read the bundle artifacts directly?
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 do I decide between the properties export and reading the bundle?
How do I decide between the properties export and reading the bundle?
object.children. Check referencedObject on the
version you are reading (see Tell the two formats apart).Can one project have both hex-reference and bundle-reference versions?
Can one project have both hex-reference and bundle-reference versions?
Additional Resources
- Project metadata — Workspace schemas and per-project metadata values
- GraphQL Subscriptions - Real-time event notifications using WebSocket connections
- GraphQL Official Documentation - Learn GraphQL fundamentals
- Apollo Client Documentation - If you’re building a client application