API reference

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:

Authorization: Bearer YOUR_TOKEN

Endpoint

The GraphQL endpoint for app.speckle.systems is:

https://app.speckle.systems/graphql

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 {
  activeUser {
    id
    name
    email
  }
}

Query workspace projects data

query ($workspaceId: String!) {
  workspace(id: $workspaceId) {
    projects {
      totalCount
      items {
        id
        name
        createdAt
      }
    }
  }
}

{
  "workspaceId": "your-workspace-id"
}

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

Response Example

{
"data": {
 "workspace": {
   "projects": {
     "totalCount": 4,
     "items": [
       {
         "id": "ad9c9929e6",
         "name": "Speckle First Project",
         "createdAt": "2025-10-15T12:06:46.315Z"
       },
       {
         "id": "6399c298d",
         "name": "Speckle Tower",
         "createdAt": "2026-02-04T16:30:57.240Z"
       },
       {
         "id": "e98ab96c9e",
         "name": "Speckle Demo Project",
         "createdAt": "2026-01-29T17:17:07.451Z"
       },
       {
         "id": "0387c91dvb",
         "name": "My amazing project",
         "createdAt": "2026-01-29T13:49:59.154Z"
       },
     ]
   }
 }
}
}

Query object data:

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:) is on its way out, not just an example to use carefully. It already doesn’t work for any version stored in the 2026.9 bundle format, and after 1 November 2026 every workspace moves to that format — at that point this pattern stops working project-wide, with no GraphQL-level replacement. See Get element data without object.children in 2026.9 for what to use instead, and Data model migration for developers for the timeline.

query Query($projectId: String!, $objectId: String!, $select: [String], $query: [JSONObject!]) {
  project(id: $projectId) {
    object(id: $objectId) {
      children(select: $select, query: $query) {
        objects {
          data
        }
      }
    }
  }
}

{
  "projectId": "your-project-id",
  "objectId": "your-object-id",
  "select": [
    "category",
    "level",
    "name",
    "properties.elementId",
    "properties.Parameters.Instance\\ Parameters.Dimensions.Length.value"
  ],
  "query": [
    {
      "field": "category",
      "value": "Structural Columns",
      "operator": "="
    }
  ]
}

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.

Response example

{
"data": {
 "project": {
   "object": {
     "children": {
       "objects": [
         {
           "data": {
             "category": "Structural Columns",
             "level": "Level 14",
             "name": "Structural Columns - Circular-Column",
             "properties": {
               "elementId": "382271",
               "Parameters": {
                 "Instance\\ Parameters": {
                   "Dimensions": {
                     "Length": {
                       "value": 7529.999999999986
                     }
                   }
                 }
               }
             }
           }
         },
         {
           "data": {
             "category": "Structural Columns",
             "level": "Level 6",
             "name": "Structural Columns - Circular-Column",
             "properties": {
               "elementId": "382321",
               "Parameters": {
                 "Instance\\ Parameters": {
                   "Dimensions": {
                     "Length": {
                       "value": 469.9999999999971
                     }
                   }
                 }
               }
             }
           }
         },
         {
           "data": {
             "category": "Structural Columns",
             "level": "Level 12",
             "name": "Structural Columns - Circular-Column",
             "properties": {
               "elementId": "382131",
               "Parameters": {
                 "Instance\\ Parameters": {
                   "Dimensions": {
                     "Length": {
                       "value": 3529.999999999986
                     }
                   }
                 }
               }
             }
           }
         }
       ]
     }
   }
 }
}
}

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

GraphQL

REST

Webhooks

Guides

Overview

Documentation

Changelog

Using the API

Authentication

Endpoint

Example Query

Query user data

Query workspace projects data

Query object data:

Additional Resources

​Overview

​Documentation

​Changelog

​Using the API

​Authentication

​Endpoint

​Example Query

​Query user data

​Query workspace projects data

​Query object data:

​Additional Resources

Overview

Documentation

Changelog

Using the API

Authentication

Endpoint

Example Query

Query user data

Query workspace projects data

Query object data:

Additional Resources