Restore a Pipe to a Snapshot

⚠️

BETA - This API is currently in beta testing. If you encounter issues or have feedback, contact our support team.

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

1. Authentication: Use a Service Account token (Personal Access Tokens are deprecated).
2. Permissions: Your token must have Admin (manage) permission on the target pipe.
3. Pipe ID: The ID of the pipe you want to restore. See Get resource IDs.
4. Snapshot version: The versionId of an uploaded snapshot of the pipe. List them with Read a Pipe's Snapshots and Operations, or create one with Create a Pipe Snapshot and use its versionId once it 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 uploaded snapshot of the pipe to restore to.

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

• Any uploaded version: You can restore to any UPLOADED snapshot of the pipe, not only the latest. A versionId that is unknown, belongs to another pipe, or is still PENDING or FAILED returns a SNAPSHOT_NOT_RESTORABLE error and applies nothing. While restoring older versions is still being rolled out to your organization, only the latest uploaded snapshot is accepted, and any other returns the same error.
• Every restore adds a version: When the restore finishes, the restored structure is saved as a new version at the top of the history, and its restoredFromSnapshot names the version you restored. Existing versions are never changed.
• Older versions restore what they recorded: A version taken before some configuration became part of versioning does not include it, and that part of the pipe is kept as it is.
• 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 change at a time: While a restore of the pipe, to any version, or a Sandbox deploy is pending or running, a new request returns a RESTORE_ALREADY_IN_PROGRESS error and enqueues nothing. Wait for it to finish rather than retrying immediately.
• No restore with an open Sandbox: While the pipe has an open Sandbox, or one is being created, the request returns a REPO_VERSION_OPEN error. Publish or discard the Sandbox first.
• 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.