Speckle API Skill

This skill provides access to the Speckle GraphQL API for managing AEC (Architecture, Engineering, Construction) data.

Requirements

Environment Variable Required: SPECKLE_ACCESS_TOKEN

Before using this skill, ensure the SPECKLE_ACCESS_TOKEN environment variable is set with a valid Speckle personal access token. You can create one at https://app.speckle.systems/profile under "Developer Settings" > "Access Tokens".

Optional: Set SPECKLE_SERVER_URL to use a different Speckle server (default: https://app.speckle.systems).

Available Scripts

All scripts are located in .claude/skills/speckle/scripts/ relative to the project root.

Generic GraphQL Client

bash

node .claude/skills/speckle/scripts/speckle-client.js query "<graphql-query>" '[variables-json]'
node .claude/skills/speckle/scripts/speckle-client.js mutation "<graphql-mutation>" '[variables-json]'

Verification

bash

node .claude/skills/speckle/scripts/speckle-verify.js    # Verify connection and token

User Operations

bash

node .claude/skills/speckle/scripts/speckle-user.js me                     # Get current user info
node .claude/skills/speckle/scripts/speckle-user.js get <user-id>          # Get another user's info
node .claude/skills/speckle/scripts/speckle-user.js search <query>         # Search users
node .claude/skills/speckle/scripts/speckle-user.js workspaces [limit]     # List workspaces

Project Operations

bash

node .claude/skills/speckle/scripts/speckle-projects.js list [limit]                              # List projects
node .claude/skills/speckle/scripts/speckle-projects.js get <project-id>                          # Get project details
node .claude/skills/speckle/scripts/speckle-projects.js create <name> [description] [visibility]  # Create project
node .claude/skills/speckle/scripts/speckle-projects.js models <project-id> [limit]               # List models
node .claude/skills/speckle/scripts/speckle-projects.js versions <project-id> <model-id> [limit]  # List versions

Workspace Operations

bash

node .claude/skills/speckle/scripts/workspace-projects.js <workspace-id> [limit]   # List workspace projects

Object Operations

bash

node .claude/skills/speckle/scripts/speckle-objects.js get <project-id> <object-id> [depth]       # Get object data
node .claude/skills/speckle/scripts/speckle-objects.js children <project-id> <object-id> [limit]  # Get children

Speckle Data Model

Understanding the hierarchy:

code

Workspace (organization)
└── Project (container for design data)
    └── Model (branch/category, e.g., "Architecture", "Structure")
        └── Version (snapshot/commit)
            └── Object (actual geometry/data with referencedObject ID)

Common GraphQL Queries

Get Current User

graphql

{
  activeUser {
    id
    name
    email
    projects { totalCount }
  }
}

List Projects with Models

graphql

{
  activeUser {
    projects(limit: 10) {
      items {
        id
        name
        models { items { id name } }
      }
    }
  }
}

Get Project Details

graphql

query($id: String!) {
  project(id: $id) {
    id
    name
    description
    visibility
    team { id name role }
    models { items { id name versions { totalCount } } }
  }
}

Get Model Versions

graphql

query($projectId: String!, $modelId: String!) {
  project(id: $projectId) {
    model(id: $modelId) {
      name
      versions(limit: 10) {
        items {
          id
          message
          createdAt
          referencedObject
          authorUser { name }
        }
      }
    }
  }
}

Get Workspace Projects

graphql

query($id: String!, $limit: Int!) {
  workspace(id: $id) {
    name
    projects(limit: $limit) {
      items {
        id
        name
        visibility
        models { totalCount }
        versions { totalCount }
      }
    }
  }
}

Get Object Data

graphql

query($projectId: String!, $objectId: String!) {
  project(id: $projectId) {
    object(id: $objectId) {
      id
      speckleType
      totalChildrenCount
      data
      children(depth: 1, limit: 50) {
        objects { id speckleType data }
      }
    }
  }
}

Common Mutations

Create Project

graphql

mutation($input: ProjectCreateInput!) {
  projectMutations {
    create(input: $input) {
      id
      name
    }
  }
}
# Variables: {"input": {"name": "My Project", "visibility": "PRIVATE"}}

Update Project

graphql

mutation($update: ProjectUpdateInput!) {
  projectMutations {
    update(update: $update) {
      id
      name
    }
  }
}
# Variables: {"update": {"id": "project-id", "name": "New Name"}}

Create Model

graphql

mutation($input: CreateModelInput!) {
  modelMutations {
    create(input: $input) {
      id
      name
    }
  }
}
# Variables: {"input": {"projectId": "...", "name": "Architecture"}}

Invite User to Project

graphql

mutation($projectId: ID!, $input: ProjectInviteCreateInput!) {
  projectMutations {
    invites {
      create(projectId: $projectId, input: $input)
    }
  }
}
# Variables: {"projectId": "...", "input": {"email": "user@example.com", "role": "STREAM_CONTRIBUTOR"}}

Key Enums

•ProjectVisibility: PRIVATE, UNLISTED, PUBLIC, WORKSPACE
•StreamRole: STREAM_OWNER, STREAM_CONTRIBUTOR, STREAM_REVIEWER
•WorkspaceRole: ADMIN, MEMBER, GUEST

Error Handling

All scripts return JSON. Check for errors array in the response:

json

{
  "errors": [
    {
      "message": "You do not have access to this resource",
      "extensions": { "code": "FORBIDDEN" }
    }
  ]
}

Tips

•Finding Object IDs: Get the referencedObject from a Version to access the root object
•Pagination: Most collections support limit and cursor parameters
•Workspace vs Personal: Projects can belong to workspaces or be personal (check workspaceId)
•Object Data: The data field contains the full object properties as JSON (can be large)