Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.speckle.systems/llms.txt

Use this file to discover all available pages before exploring further.

This guide shows how to update an existing cloud integration sync using GraphQL. Use this when you need to change sync context values such as referencePoint or viewName, and optionally trigger a run immediately. The supported flow is:
  1. List syncs for a project
  2. Choose target sync IDs
  3. Update each sync with syncMutations.update
  4. Optionally trigger immediate execution for selected syncs

​
Pre-requisites

  • A personal access token with streams:read and streams:write scopes
  • Access to the target project with edit permissions
  • The target Speckle projectId string (retrieve from the web app URL, GraphQL project(id: …), or SpecklePy project helpers; listing patterns live under SpeckleClient → Resource Properties)
For all GraphQL calls, include: 
Authorization: Bearer YOUR_TOKEN
This flow is suitable for citizen developers. It uses standard PAT scopes and does not require server admin permissions.

​
Before you start: IDs and quick test

You need two IDs:
  • projectId: the Speckle project ID
  • sync.id: the sync entry you want to update
If you are not sure where to get projectId, list or fetch projects via your SDK (SpecklePy: workspace.get_projects, active_user.get_projects, then project.get; workspace vs personal hosts described on SpeckleClient). Sync row IDs still come from the Step 1 project.syncs query—until SpecklePy exposes them, call that query through execute_query or substitute YOUR_PROJECT_ID in the curl example and read items[].id from the response. Quick test with curl: 
curl -X POST "https://app.speckle.systems/graphql" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operationName":"ProjectSyncs",
    "variables":{"projectId":"YOUR_PROJECT_ID","limit":25,"cursor":null},
    "query":"query ProjectSyncs($projectId: String!, $limit: Int, $cursor: String) { project(id: $projectId) { syncs(limit: $limit, cursor: $cursor) { items { id fileName active context } cursor totalCount } } }"
  }'

​
Overview

Updating sync configuration is usually a two-call pattern:
  1. Query project.syncs to get the syncs you want to change
  2. Run syncMutations.update per sync with a new context payload
There is no dedicated bulk mutation for sync updates, so batching is done client-side.

​
Step 1: List syncs in the project

Use this to discover sync IDs before updating. POST /graphql Query: 
query ProjectSyncs($projectId: String!, $limit: Int, $cursor: String) {
  project(id: $projectId) {
    syncs(limit: $limit, cursor: $cursor) {
      items {
        id
        fileName
        integration {
          slug
        }
        active
        context
      }
      cursor
      totalCount
    }
  }
}
Variables example: 
{
  "projectId": "0d1f93ec13",
  "limit": 25,
  "cursor": null
}

​
Step 2: Update one sync

POST /graphql Mutation: 
mutation UpdateSync($input: UpdateSyncInput!) {
  syncMutations {
    update(input: $input) {
      id
      active
      context
      updatedAt
    }
  }
}
Variables example: 
{
  "input": {
    "id": "3d5085bbcc",
    "projectId": "0d1f93ec13",
    "context": {
      "referencePoint": "surveyPoint",
      "viewName": null
    },
    "triggerNow": false
  }
}
Input fields: UpdateSyncInput supports:
  • id (ID!): Sync identifier
  • projectId (String!): Owning project identifier
  • context (JSONObject): Integration-specific sync settings
  • triggerNow (Boolean): If true, requests an immediate execution

​
Context shape and enums

Typical context payload shape for ACC and ProjectWise syncs: 
{
  "referencePoint": "internalOrigin",
  "viewName": "3D Coordination"
}
referencePoint values:
  • internalOrigin
  • projectBasePoint
  • surveyPoint
viewName values:
  • Any string matching a valid source view name
  • null to clear view scoping
context is a JSON object. Keys are integration-specific conventions, not strongly typed GraphQL fields. Common keys in ACC and ProjectWise flows include referencePoint and viewName.
Response example: 
{
  "data": {
    "syncMutations": {
      "update": {
        "id": "3d5085bbcc",
        "active": true,
        "context": {
          "referencePoint": "surveyPoint",
          "viewName": null
        },
        "updatedAt": "2026-05-06T14:55:00.000Z"
      }
    }
  }
}

​
Step 3: Repeat for batch updates

For batch operations:
  1. Query project.syncs
  2. Filter target syncs in your client
  3. Run syncMutations.update once per sync
  4. Set triggerNow only where needed

​
Operational notes

  • If a sync is paused (active: false), updates with triggerNow: true can be rejected.
  • Use syncMutations.setActive to resume a sync before requesting immediate execution.
  • Keep context keys aligned with integration UI and backend conventions in your environment.
  • For large batches, page through syncs(cursor, limit) and apply updates in controlled chunks.
  • If a legacy ACC sync has not been migrated yet, run syncMutations.migrateLegacy first, then retry update.

​
What developers need to know

Use a personal access token with streams:read and streams:write. The GraphQL mutation is gated on streams:write. Listing syncs reads project data, so streams:read is needed for the query step. Your account also needs permission to manage cloud integration syncs for that project (the same capability you use in the web app to create or edit ACC or ProjectWise syncs).
The GraphQL projectId is the project’s id string (same value you see in URLs as /projects/{id}/).For other SDKs, see specklesharp (C#/.NET) and speckle.js and use whichever GraphQL or HTTP helpers those packages expose.
No. Use project.syncs with pagination (cursor, limit), filter the rows you need on the client, then call syncMutations.update once per sync. Set triggerNow only where you want an immediate run.
If triggerNow is true and the sync is paused (active: false), the server rejects the immediate run. Call syncMutations.setActive with active: true first, then update again with triggerNow: true, or omit triggerNow until you are ready to run.
New integrations use syncMutations for create, update, delete, pause, and legacy migration. Older accSyncItemMutations fields are deprecated in favour of syncMutations. Prefer syncMutations.update for changing sync context going forward.
Older ACC syncs may still exist only in legacy storage until migrated. Run syncMutations.migrateLegacy with the sync id and project id, then run syncMutations.update again. The web app may expose a migrate action for the same step.
Yes. SpecklePy does not yet expose dedicated sync mutation helpers, but you can run same GraphQL operations from Python. Authenticate with authenticate_with_token, then call execute_query or send direct POST requests to {host}/graphql with requests/httpx.
Last modified on May 7, 2026