Speckle Core API

speckle-core-api

Quick Reference

API Surface Overview

Terminology Mapping (CRITICAL)

ALWAYS use current terminology (Project, Model, Version) in new code. The legacy types exist for backward compatibility and will be removed in a future release.

Authentication Header Format

Authorization: Bearer <YOUR_TOKEN>

This format applies to BOTH Personal Access Tokens and OAuth2 access tokens, for BOTH GraphQL and REST endpoints.

Auth Scope Table

Critical Warnings

NEVER use legacy queries (stream, branch, commit) in new code -- ALWAYS use current queries (project, model, version). Legacy queries are deprecated and will be removed.

NEVER embed Personal Access Tokens in client-side (browser) JavaScript -- ALWAYS use OAuth2 flow for browser applications. PATs are for server-side scripts and automation only.

NEVER commit tokens to version control -- ALWAYS store tokens in environment variables or secret managers.

NEVER hardcode https://app.speckle.systems/graphql -- ALWAYS make the server URL configurable. Users may run self-hosted Speckle servers.

NEVER use project.object.data GraphQL queries for large object trees -- ALWAYS use the REST endpoint GET /objects/:projectId/:objectId which supports gzip streaming.

NEVER use display names (version_create, model_update) as webhook trigger strings -- ALWAYS use internal legacy names (commit_create, branch_update).

NEVER ignore 429 responses -- ALWAYS read the Retry-After header and implement exponential backoff.

NEVER skip pagination -- ALWAYS implement cursor-based pagination for collections. There is no unlimited query.

GraphQL Endpoint

Connection URL

• Speckle Cloud: https://app.speckle.systems/graphql
• Self-hosted: https://<your-server-domain>/graphql

The endpoint accepts standard GraphQL POST requests with JSON body containing query, variables, and optional operationName. An Apollo Sandbox explorer is available when accessing the URL in a browser.

Server Discovery

ALWAYS query serverInfo first to discover server capabilities:

query ServerInfo {
  serverInfo {
    name
    version
    canonicalUrl
    automateUrl
    configuration {
      objectSizeLimitBytes
      objectMultipartUploadSizeLimitBytes
    }
    scopes { name description }
    authStrategies { id name }
    workspaces { workspacesEnabled }
  }
}

This query does NOT require authentication.

Authentication

Decision Tree: PAT vs OAuth2

Is this a server-side script, CLI tool, or CI/CD pipeline?
├─ YES → Use Personal Access Token (PAT)
│        - Simple: one header, no flow
│        - Scope to minimal permissions
│        - Rotate periodically
└─ NO → Is this a browser/desktop app with user interaction?
         ├─ YES → Use OAuth2 + Challenge flow
         │        - Register an OAuth app on the server
         │        - Redirect user for consent
         │        - Exchange code + challenge for token
         └─ NO → Is this a Speckle Automate function?
                  └─ YES → Token is injected by the Automate runtime
                           - Use the provided token directly

Personal Access Tokens (PATs)

Create: Profile > Settings > Developer > Access Tokens > "New Token"

Use: Include in every request header:

Authorization: Bearer <token>

Resource-scoped tokens: Tokens can be limited to specific projects or workspaces via the limitResources parameter in ApiTokenCreateInput. This restricts the token to only operate on the specified resources.

Security rules:

• ALWAYS apply principle of least privilege (minimal scopes)
• ALWAYS store in environment variables or secret managers
• ALWAYS rotate periodically
• ALWAYS revoke immediately if compromised

OAuth2 + Challenge Flow

Speckle implements a custom OAuth2 variant with a challenge parameter (similar to PKCE).

Flow summary:

1. Register app on server (get App ID + App Secret)
2. Generate random challenge string, store locally
3. Redirect user to https://<server>/authn/verify/<appId>/<challenge>
4. User authorizes; Speckle redirects to your URI with access_code
5. Exchange code for tokens via POST /auth/token
6. Use access token; refresh when expired

See references/examples.md for complete code examples.

REST API

The REST API handles ONLY object upload/download. All other operations MUST use GraphQL.

Download Objects (with children)

GET /objects/:projectId/:objectId
Authorization: Bearer <token>
Accept: application/json

Returns the root object AND all children as gzip-compressed stream. Use the referencedObject from a Version to get the full data tree.

Download Single Object

GET /objects/:projectId/:objectId/single
Authorization: Bearer <token>

Returns ONLY the requested object (no children). Useful for inspecting metadata without downloading the tree.

Upload Objects

POST /objects/:projectId
Authorization: Bearer <token>
Content-Type: application/gzip | text/plain | application/json

Returns HTTP 201 on success. ALWAYS check serverInfo.configuration.objectMultipartUploadSizeLimitBytes before uploading.

Standard Send/Receive Workflow

1. Authenticate (PAT or OAuth2)
2. [Send] Serialize objects → POST /objects/:projectId (REST)
3. [Send] Create version → versionMutations.create (GraphQL)
4. [Receive] Get version → project.version (GraphQL) → get referencedObject
5. [Receive] Download objects → GET /objects/:projectId/:objectId (REST)
6. [Receive] Deserialize objects

Pagination

Speckle uses cursor-based pagination for ALL collections:

type SomeCollection {
  totalCount: Int!
  cursor: String       # null when no more pages
  items: [SomeType!]!  # "objects" for ObjectCollection
}

Rules:

• ALWAYS specify limit -- there is no default unlimited query
• When cursor is null in response, there are no more pages
• ObjectCollection uses objects instead of items (schema inconsistency)
• Typical limits: 25 for models/versions, 100 for objects

Rate Limiting

• Identification priority: User ID > Token ID > IP address > "unknown"
• Batched GraphQL: Each operation in a batch counts separately
• Response headers on 429:
  • Retry-After: milliseconds until next request
  • X-RateLimit-Reset: ISO timestamp of reset
  • X-RateLimit-Remaining: available points (on success)

Error Handling

GraphQL Errors

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

REST API Errors

GraphQL Schema Directives

The schema uses custom directives for authorization:

Webhook Trigger Terminology (CRITICAL)

Webhook triggers STILL use legacy internal names. The display names in the UI differ:

API Version Differences (Server 2.x vs 3.x)

ALWAYS query serverInfo.version to determine which features are available.

Reference Links

• references/methods.md -- GraphQL schema: queries, mutations, subscriptions
• references/examples.md -- Working GraphQL + REST examples
• references/anti-patterns.md -- API misuse patterns

Official Sources

• https://docs.speckle.systems/
• https://github.com/specklesystems/speckle-server
• https://github.com/specklesystems/specklepy
• https://speckle.guide/dev/apps.html (legacy OAuth docs)