Open a Pipe Sandbox Version

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 a sandbox for. See Get resource IDs.
A published pipe: the target must be a real pipe, not a sandbox clone. A draft pipe cannot have a version of its own.

Step 1: Open the Sandbox

A sandbox version is an editable copy of the pipe's structure, cloned from a snapshot into a separate draft pipe. You change phases, fields and automations on the clone without touching the pipe your users work in.

Use createRepoVersion to open it. The same call both starts the build and reports on it, so there is one operation to learn instead of two.

mutation {
  createRepoVersion(input: {
    repoId: 123
  }) {
    status
    repoVersion {
      id
      repoId
      clonedRepoId
      previousSnapshotId
      publishedSnapshotId
      createdAt
      updatedAt
    }
  }
}

Input Explanation:

repoId (required): The ID of the pipe to open an editable version for.

Sample Response:

Building the clone is asynchronous, so the first call returns with the build queued and no version yet:

{
  "data": {
    "createRepoVersion": {
      "status": "PENDING",
      "repoVersion": null
    }
  }
}

Step 2: Poll the Same Mutation Until the Build Finishes

The mutation is idempotent: called while a build is already in flight it reports that build and starts nothing new, and called while a version is already open it returns that version. So you poll by repeating the exact same call.

{
  "data": {
    "createRepoVersion": {
      "status": "SUCCEEDED",
      "repoVersion": {
        "id": "77",
        "repoId": "123",
        "clonedRepoId": "5581",
        "previousSnapshotId": "456",
        "publishedSnapshotId": null,
        "createdAt": "2026-06-25T13:00:09Z",
        "updatedAt": "2026-06-25T13:00:09Z"
      }
    }
  }
}

status tells you where the build is:

PENDING: queued, the clone has not started. repoVersion is null.
RUNNING: cloning. repoVersion is null.
SUCCEEDED: the sandbox is ready and editable. repoVersion is present.
FAILED: the build produced no usable version, and the reason is recorded on the change-management operation.

A version that was already open reports SUCCEEDED, since that is the state of the build that produced it.

Step 3: Edit the Sandbox Through Its Cloned Pipe

clonedRepoId is the ID of the draft pipe holding the cloned structure. That is the pipe you address for every sandbox edit: pass it as the repoId/pipeId of the ordinary pipe, phase, field and automation mutations.

query {
  pipe(id: 5581) {
    id
    name
    phases {
      id
      name
    }
  }
}

Only the original pipe's admins are carried over to the clone, both users and groups. A normal, member or guest role on the original grants nothing on the sandbox.

Step 4: Read the Build's Own Record

The build is a change-management operation of kind GENERATE_ENVIRONMENT, so it shows up in the pipe's operations list with its status and, when it failed, the reason:

query {
  pipe(id: 123) {
    operations(status: [PENDING, RUNNING, FAILED]) {
      id
      kind
      status
      error
      createdAt
    }
  }
}

See Read a Pipe's Snapshots and Operations for the full field reference.

Response Fields

status: State of the build that produces the version, not a state of the version itself.
repoVersion.id: The version ID.
repoVersion.clonedRepoId: ID of the draft pipe holding the cloned structure. This is the pipe the sandbox edits are made on.
repoVersion.previousSnapshotId: ID of the snapshot the sandbox structure was cloned from.
repoVersion.publishedSnapshotId: ID of the snapshot produced when the version was deployed back onto the pipe. null while the version is still the pipe's open sandbox.

Key Notes

One open sandbox per pipe: a pipe has at most one unpublished version. While one is open, every call returns it, so there is no way to end up with two competing sandboxes of the same pipe.
Safe to call repeatedly: concurrent or retried calls do not start a second clone. This is what makes the same call usable as both the entry point and the poll.
No snapshot needed up front: if the pipe has never been snapshotted, the build takes one itself and clones from it. The snapshot it used is reported as previousSnapshotId.
A failed build can be retried: a build that ended FAILED leaves the sandbox slot free, so calling the mutation again starts a fresh build.
Blocked while the pipe is being rewritten: if a restore or a deploy is in progress for the pipe, the build is refused with a PIPEFY_RUNTIME error explaining that change management is in progress. Check operations(status: [PENDING, RUNNING]) first, or retry once the in-flight operation finishes.
Draft pipes are rejected: passing the ID of a sandbox clone returns a PIPEFY_RUNTIME error, since a draft pipe cannot have a version of its own. Pass the original pipe's ID.
Admin only: only pipe admins can open a sandbox. 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. When the flag is off, the mutation is absent from the schema and the request fails with an error naming createRepoVersion.