Rename a Pipe 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

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 that owns the snapshot. See Get resource IDs.
4. Snapshot version ID: The versionId returned by Create a Pipe Snapshot, or read from the pipe's snapshots list.

Step 1: Rename the Snapshot

A snapshot is identified by its versionId and ordered by its sequenceIndex, neither of which says anything about why the snapshot was taken. Use renameRepoSnapshot to attach a label that does, so a later audit or restore can pick the right one.

mutation {
  renameRepoSnapshot(input: {
    repoId: 123,
    versionId: "9f1c2d34-5678-49ab-bcde-0123456789ab",
    label: "Before the Q3 automation rework"
  }) {
    repoSnapshot {
      id
      versionId
      label
      sequenceIndex
      status
      createdAt
    }
  }
}

Input Explanation:

• repoId (required): The ID of the pipe that owns the snapshot.
• versionId (required): The versionId (UUID) of the snapshot to rename.
• label (optional): The new label, up to 255 characters. Surrounding whitespace is trimmed. Omit it, or pass null or a blank string, to clear the label.

Sample Response:

{
  "data": {
    "renameRepoSnapshot": {
      "repoSnapshot": {
        "id": "456",
        "versionId": "9f1c2d34-5678-49ab-bcde-0123456789ab",
        "label": "Before the Q3 automation rework",
        "sequenceIndex": 3,
        "status": "UPLOADED",
        "createdAt": "2026-06-25T12:34:56Z"
      }
    }
  }
}

Step 2: Read the Labels Back

The label is returned on every snapshot, so you can list a pipe's snapshots and pick one by name:

query {
  pipe(id: 123) {
    snapshots {
      versionId
      label
      sequenceIndex
      status
    }
  }
}

Snapshots that were never renamed return label: null.

Step 3: Clear a Label

The label argument is optional. Omit it to drop the label back to null, which leaves the snapshot in the same state as one that was never named:

mutation {
  renameRepoSnapshot(input: {
    repoId: 123,
    versionId: "9f1c2d34-5678-49ab-bcde-0123456789ab"
  }) {
    repoSnapshot {
      versionId
      label
    }
  }
}

Passing label: null or a blank string does the same thing.

Key Notes

• Renaming only changes the label: the snapshot content, versionId, sequenceIndex, status and stored JSON are untouched. Renaming is not a new snapshot and does not trigger generation.
• Any status can be renamed: PENDING, UPLOADED and FAILED snapshots all accept a label, which is useful for annotating why a generation failed.
• Labels are not unique: two snapshots of the same pipe may carry the same label. Use versionId when you need to address one unambiguously.
• Clearing a label: label is optional. Omitting it, or passing null or a blank string, sets the label back to null. A blank string is never stored as-is.
• Too long is rejected: a label over 255 characters returns an INVALID_INPUT error.
• Wrong pipe: a versionId that does not belong to the given repoId returns a RESOURCE_NOT_FOUND error, so a snapshot cannot be renamed from another pipe.
• Admin only: only pipe admins can rename snapshots. 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.