Create 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 you want to snapshot. See Get resource IDs.

Step 1: Create the Snapshot

Use the createRepoSnapshot mutation to capture the current state of a pipe's versioned structure (phases, fields, automations, conditions, and related entities). The snapshot is stored and can be retrieved later for auditing or diffing purposes.

mutation {
  createRepoSnapshot(input: {
    repoId: 123
  }) {
    repoSnapshot {
      id
      versionId
      sequenceIndex
      status
      metrics
      error
      signedUrl
      uploadedAt
      createdAt
    }
  }
}

Input Explanation:

• repoId (required): The ID of the pipe to snapshot.

Sample Response:

The mutation returns immediately with a PENDING snapshot. Generation runs in the background, so metrics is empty and signedUrl/uploadedAt are null until it finishes.

{
  "data": {
    "createRepoSnapshot": {
      "repoSnapshot": {
        "id": "456",
        "versionId": "9f1c2d34-5678-49ab-bcde-0123456789ab",
        "sequenceIndex": null,
        "status": "PENDING",
        "metrics": {},
        "error": null,
        "signedUrl": null,
        "uploadedAt": null,
        "createdAt": "2026-06-25T12:34:56Z"
      }
    }
  }
}

Once generation completes, the same snapshot reaches UPLOADED, metrics is populated, and the signedUrl becomes available:

{
  "id": "456",
  "versionId": "9f1c2d34-5678-49ab-bcde-0123456789ab",
  "sequenceIndex": 3,
  "status": "UPLOADED",
  "metrics": {
    "entity_counts": { "phases": 5, "fields": 42, "automations": 3 },
    "byte_size": 184320,
    "compressed_byte_size": 20480
  },
  "error": null,
  "signedUrl": "https://files.pipefy.com/org/org-uuid-here/repo_snapshots/pipe-uuid-here/9f1c2d34-5678-49ab-bcde-0123456789ab.json?signature=...",
  "uploadedAt": "2026-06-25T12:35:01Z",
  "createdAt": "2026-06-25T12:34:56Z"
}

Response Fields

• versionId: Unique identifier for this snapshot version, generated by the database.
• sequenceIndex: Monotonic per-pipe ordering position among uploaded snapshots, starting at 1. Assigned only when the upload completes, so it is null while a snapshot is PENDING and stays null for a snapshot that FAILED before uploading.
• status: Lifecycle state of the snapshot:
  • PENDING: created and queued; generation has not finished yet.
  • UPLOADED: generated and stored; the signedUrl is available.
  • FAILED: generation failed permanently; see error for details.
• metrics: Generation metrics, empty ({}) while the snapshot is PENDING. Once UPLOADED it contains entity_counts (a per-entity record count), byte_size (uncompressed JSON size in bytes), and compressed_byte_size (stored gzipped size in bytes).
• error: Explanation of why generation failed. Null unless status is FAILED.
• signedUrl: Temporary pre-signed URL to download the snapshot JSON. Null until the snapshot is UPLOADED.

Key Notes

• Idempotent creation: Only one in-flight (PENDING) snapshot exists per pipe at a time. Calling the mutation again while a fresh snapshot is still generating returns that same snapshot instead of creating a duplicate, so repeated or retried calls are safe. If a pending snapshot is left behind by a lost job, a later call retires it (marking it FAILED) and creates a new one.
• Asynchronous generation: The mutation returns a PENDING snapshot right away. Poll the same versionId through the pipe's snapshot(versionId:) field until status becomes UPLOADED to obtain the signedUrl, or FAILED to read the error. See Read a Pipe's Snapshots and Operations.
• Observable failures: A permanently failed snapshot is kept (not deleted) with status: FAILED and an error, so failures stay auditable. Since it never uploaded, its sequenceIndex is null.
• Admin only: Only pipe admins can generate 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.
• Snapshot content: The snapshot captures the pipe's own attributes alongside its versioned entities, serialized as a single JSON document.