API reference

Access the complete GraphQL schema and API documentation for the Speckle Server

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

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