Updating Cloud Integration Syncs via GraphQL

This guide shows how to update an existing cloud integration sync using GraphQL, and how to import earlier versions of an ACC file into it. 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:

List syncs for a project
Choose target sync IDs
Update each sync with syncMutations.update
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:

Query project.syncs to get the syncs you want to change
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.

Keys the server owns on SharePoint syncs

A SharePoint sync’s context also carries keys the server sets and maintains:

tenantId, siteId, driveId, and itemId locate the file in Microsoft 365.
checkpoint identifies the last published content Speckle synced.
lastPolledAt is when Speckle last checked the file.
consecutiveMisses, consecutiveProbeFailures, and pauseReason track failed checks and why the sync paused.

syncMutations.update drops these keys from the context you send, without an error. Send only the settings keys, such as referencePoint. 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:

Query project.syncs
Filter target syncs in your client
Run syncMutations.update once per sync
Set triggerNow only where needed

Import earlier versions of an ACC file

An ACC sync starts at the file version current when it was created. To bring earlier versions into the same model, list the file’s version history on the sync and import the ones you want. Each imported version is dated at its ACC creation time, so it slots into the model’s history and never becomes the latest version. ACC syncs only; the field is null for integrations that cannot list versions. Check first whether the caller may import, with the project permission check:

query CanImport($projectId: String!) {
  project(id: $projectId) {
    permissions {
      canImportSyncSourceVersions {
        authorized
        code
        message
      }
    }
  }
}

List the versions, each paired with the latest sync run for it (syncItem is null for a version never synced):

query SyncSourceVersions($projectId: String!, $syncId: ID!) {
  project(id: $projectId) {
    sync(id: $syncId) {
      sourceVersions {
        id
        number
        name
        createdAt
        createdBy
        syncItem {
          id
        }
      }
    }
  }
}

Import the chosen versions by id:

mutation ImportSourceVersions($input: ImportSourceVersionsInput!) {
  syncMutations {
    importSourceVersions(input: $input) {
      id
    }
  }
}

{
  "input": {
    "id": "3d5085bbcc",
    "projectId": "0d1f93ec13",
    "sourceVersionIds": [
      "urn:adsk.wipprod:fs.file:vf.abc123?version=2",
      "urn:adsk.wipprod:fs.file:vf.abc123?version=3"
    ]
  }
}

One sync run is queued per version, oldest first. The mutation is rejected as a whole, and nothing is queued, when:

more than five distinct ids are passed (SYNC_SOURCE_VERSION_IMPORT_LIMIT); import a longer history in rounds
the sync is paused (SYNC_PAUSED); resume it with syncMutations.setActive first
an id is not in the file’s version list (SYNC_SOURCE_VERSION_NOT_FOUND)
a version predates the version history the workspace plan keeps (SYNC_SOURCE_VERSION_BEYOND_HISTORY_LIMIT)
ACC reports no creation time for a version (SYNC_SOURCE_VERSION_UNDATED)
the workspace runs in compatibility mode (SYNC_SOURCE_VERSION_IMPORT_UNSUPPORTED_ON_RAIL)

Importing a version that already synced is allowed and creates a second Speckle version. Like any import it is dated at the ACC creation time, so it does not become the latest version. The web app greys those versions out, so check syncItem before you import.

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

Which token scopes and permissions do I need?

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).

How do I find my project ID?

The GraphQL projectId is the project’s id string (same value you see in URLs as /projects/{id}/).

Web app: copy {id} from /projects/{id}/.
GraphQL: run project(id: "...") { id }.
SpecklePy: list/fetch projects via workspace.get_projects, active_user.get_projects, and project.get (see SpeckleClient → Resource Properties).
Sync ids: get items[].id from Step 1 project.syncs. Use execute_query if you are scripting in Python.

For other SDKs, see specklesharp (C#/.NET) and speckle.js and use whichever GraphQL or HTTP helpers those packages expose.

Is there a bulk update mutation for many syncs?

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.

Why does immediate run fail after my update?

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.

What is the difference between syncMutations and accSyncItemMutations?

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.

What if my ACC sync errors about migration?

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.

Which GraphQL error codes should I handle?

Code	When
`BAD_REQUEST_ERROR`	`create` with an `integration` slug the server does not know. The slugs are `acc`, `projectWise`, `sharePoint`, and `trimbleConnect`. Also returned when the integration is turned off on the server.
`NOT_FOUND_ERROR`	`update`, `delete`, or `setActive` with an `id` that matches no sync, for a caller who can read the project’s syncs.
`FORBIDDEN`	The workspace plan does not include the integration, or the caller’s project role is below Contributor. A caller who cannot read the project’s syncs also gets this code for an unknown `id`, so the code does not reveal whether the sync exists.
`UNAUTHORIZED`	The request has no valid token.
`SHAREPOINT_NOTHING_PUBLISHED`	`update` with `triggerNow: true` on a SharePoint sync whose current content is a draft or an empty file. The server saves none of the `context` sent in the same call.

Can I automate sync updates with SpecklePy?

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.

GraphQL

REST

Webhooks

Guides

Updating Cloud Integration Syncs via GraphQL

Pre-requisites

Before you start: IDs and quick test

Overview

Step 1: List syncs in the project

Step 2: Update one sync

Context shape and enums

Keys the server owns on SharePoint syncs

Step 3: Repeat for batch updates

Import earlier versions of an ACC file

Operational notes

What developers need to know

​Pre-requisites

​Before you start: IDs and quick test

​Overview

​Step 1: List syncs in the project

​Step 2: Update one sync

​Context shape and enums

​Keys the server owns on SharePoint syncs

​Step 3: Repeat for batch updates

​Import earlier versions of an ACC file

​Operational notes

​What developers need to know

Pre-requisites

Before you start: IDs and quick test

Overview

Step 1: List syncs in the project

Step 2: Update one sync

Context shape and enums

Keys the server owns on SharePoint syncs

Step 3: Repeat for batch updates

Import earlier versions of an ACC file

Operational notes

What developers need to know