Restore a Pipe to a Snapshot

Before You Begin

🔗 Use the GraphQL Playground to execute the queries in this guide.

➡️ New to GraphQL? Learn how to navigate the Playground with our Playground Basics Guide.

Prerequisites

Authentication: Use a Service Account token (Personal Access Tokens are deprecated).
Permissions: Your token must have Admin (manage) permission on the target pipe.
Pipe ID: The ID of the pipe you want to restore. See Get resource IDs.
Snapshot version: The versionId of the snapshot to restore to. It must be the pipe's latest uploaded snapshot. Create one with the createRepoSnapshot mutation (Create a Pipe Snapshot) and use the versionId it returns once the snapshot reaches UPLOADED.

Step 1: Restore the Pipe

Use the restoreRepoToSnapshot mutation to reconcile a pipe's versioned structure (phases, fields, automations, conditions, and related entities) back to a snapshot. The restore runs in the background: the mutation validates the request, acknowledges it, and returns the snapshot the pipe is being restored to.

mutation {
  restoreRepoToSnapshot(input: {
    repoId: 123
    versionId: "9f1c2d34-5678-49ab-bcde-0123456789ab"
  }) {
    repoSnapshot {
      id
      versionId
      sequenceIndex
      status
    }
  }
}

Input Explanation:

repoId (required): The ID of the pipe to restore.
versionId (required): The versionId (UUID) of the snapshot to restore to. It must be the pipe's latest uploaded snapshot.

Sample Response:

The mutation returns the target snapshot as confirmation of the version the pipe is being restored to. The restore itself is applied in the background.

{
  "data": {
    "restoreRepoToSnapshot": {
      "repoSnapshot": {
        "id": "456",
        "versionId": "9f1c2d34-5678-49ab-bcde-0123456789ab",
        "sequenceIndex": 3,
        "status": "UPLOADED"
      }
    }
  }
}

Key Notes

Latest snapshot only: You can only restore to the pipe's most recent uploaded snapshot (the one with the highest sequenceIndex). Passing any other versionId (an older snapshot, an unknown version, or a pipe with no uploaded snapshot) returns a SNAPSHOT_NOT_LATEST error and applies nothing. To restore to the current structure, take a fresh snapshot first with createRepoSnapshot and restore to that versionId.
Asynchronous restore: The mutation does not apply the changes inline. It validates the request and enqueues the restore, which computes the difference between the live pipe and the snapshot and reconciles the pipe to match. The mutation returns the target snapshot rather than an operation handle, but the restore is recorded as a RESTORE change-management operation: read its status through the pipe's operations field or the snapshot's own operations connection. See Read a Pipe's Snapshots and Operations.
One restore at a time: While a restore of the pipe's latest snapshot is still pending or running, a new request for the same snapshot returns a RESTORE_ALREADY_IN_PROGRESS error and enqueues nothing. Wait for the in-flight restore to finish rather than retrying immediately.
Full structural restore, no preview: The restore reconciles the pipe's versioned structure to the snapshot. This delivery has no force argument and no impact preview: the restore is applied directly, without a dry run of the changes it will make.
Admin only: Only pipe admins can restore a pipe. Tokens without Admin (manage) permission on the pipe receive a PERMISSION_DENIED error.
Pipe not found: An invalid or non-existent repoId returns a RECORD_NOT_FOUND error.
Gradual rollout: This operation is being rolled out behind a feature flag and may not yet be available for every organization.
Related operations: Create a Pipe Snapshot, Read a Pipe's Snapshots and Operations and Open a Pipe Sandbox Version.