Compare a Pipe Sandbox to Production

Read the sandbox-versus-production comparison for a pipe version, grouped into the deploy review categories.

⚠️

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 production pipe this version belongs to. A token that does not returns PERMISSION_DENIED.
  3. An open sandbox: The pipe needs a version from Open a Pipe Sandbox Version. Read the comparison on that production pipe. There is no root field, and you do not pass a version id or a snapshot id.
  4. A snapshot on both sides: the comparison reads the latest uploaded snapshot of the production pipe and of the draft. Opening a sandbox snapshots production only, so the draft has none until you create one (Step 1).

Step 1: Snapshot the Draft

Create a snapshot of the draft pipe (clonedRepoId) after the edits you want to review. The comparison never takes one itself, so an edit made after the draft's latest snapshot does not appear.

mutation {
  createRepoSnapshot(input: { repoId: 456 }) {
    repoSnapshot { id status }
  }
}

The snapshot is generated asynchronously: it starts as pending and is read by the comparison only once it is uploaded. See Create a pipe snapshot. Until the draft has an uploaded snapshot, Step 2 returns PIPEFY_RUNTIME.

Step 2: Read the Comparison

compareToProduction returns the comparison for this version as one JSON value: a summary plus categories. categories is always the eight groups in this order: pipe_configuration, phases_and_fields, conditional_fields, automations, email_templates, connections, webhooks, labels.

query {
  pipe(id: 123) {
    repoVersion {
      compareToProduction(filter: ALL)
    }
  }
}

Input Explanation:

  • pipe.id (required): The production pipe whose open sandbox you are reviewing.
  • filter (optional): ALL returns every row and property, including unchanged ones. TOUCHED returns only the changed rows, plus the unchanged rows needed to place them (a phase whose field changed), and each returned row keeps all its properties, the unchanged ones with status: "unchanged", so a client can show the full item and hide what did not change. A pipe configuration section keeps all its properties when at least one changed and comes back empty otherwise. Omitting the argument and passing an explicit null both behave as ALL.

Sample Response (TOUCHED: a phase renamed, a phase jump added and a pipe preference changed in the sandbox; the unchanged properties are trimmed to one or two per item):

{
  "data": {
    "pipe": {
      "repoVersion": {
        "compareToProduction": {
          "summary": {
            "created": 1,
            "updated": 2,
            "deleted": 0,
            "total": 3
          },
          "categories": [
            {
              "key": "pipe_configuration",
              "changes": 1,
              "sections": [
                {
                  "key": "pipe_settings",
                  "properties": [
                    { "key": "repos.public", "status": "unchanged", "from": false, "to": false },
                    { "key": "repo_preferences.hidden_top_buttons", "status": "updated", "from": [], "to": ["PDF"] }
                  ]
                },
                { "key": "start_form_sharing", "properties": [] },
                { "key": "public_form", "properties": [] },
                { "key": "pipe_email", "properties": [] }
              ]
            },
            {
              "key": "phases_and_fields",
              "changes": 1,
              "rows": [
                {
                  "entity": "phases",
                  "id": "344166802",
                  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                  "title": "Second look",
                  "color": "blue",
                  "status": "updated",
                  "properties": [
                    { "key": "phases.name", "status": "updated", "from": "Review", "to": "Second look" },
                    { "key": "phases.done", "status": "unchanged", "from": false, "to": false },
                    { "key": "phase_jumps", "status": "updated", "summary": { "created": 1 } }
                  ]
                }
              ]
            },
            { "key": "conditional_fields", "changes": 0, "rows": [] },
            { "key": "automations", "changes": 0, "rows": [] },
            { "key": "email_templates", "changes": 0, "rows": [] },
            { "key": "connections", "changes": 0, "rows": [] },
            { "key": "webhooks", "changes": 0, "rows": [] },
            { "key": "labels", "changes": 0, "rows": [] }
          ]
        }
      }
    }
  }
}

Response Fields

  • summary: Counts of created, updated, and deleted table rows across every versioned entity, plus total. It also counts rows that only appear as a collection count (such as phase_jumps), so it does not add up to the changes of the categories. It is the same for both filters.
  • categories: The eight groups listed above, in that order. Each entry has a key, a changes count, and either sections (pipe_configuration: pipe_settings, start_form_sharing, public_form, pipe_email) or rows.
  • Row: entity, id, uuid, title, status (created, updated, deleted or unchanged), properties, and, on phases, child rows for fields. Fields and labels also carry a subtitle; phases and labels a color. The id is the production id, except for a row created in the sandbox, whose draft id is only valid within this response. Every row includes uuid; it is null for entities without a uuid column (such as connections). For rows that exist in production, uuid is the production entity's uuid. For a row created in the sandbox, uuid is the draft entity's uuid in the sandbox only — after publish the entity receives a new production uuid, not this one.
  • Column property: key is <entity>.<column>, with from (production) and to (sandbox). A created row has from: null; a deleted row has to: null. JSON columns are compared and returned whole.
  • Collection property: key is the entity name and summary counts the collection's rows by status. An unchanged collection comes with status: "unchanged" and an empty summary.

Key Notes

  • One JSON value: compareToProduction returns a single JSON object. It is not a list, so it cannot be paginated.

  • Production pipe is authorized: the token must administer the production pipe this version belongs to. A token that does not receives PERMISSION_DENIED.

  • Missing draft: a version whose sandbox was torn down, or whose clone was never recorded, returns RESOURCE_NOT_FOUND.

  • Service failure: a missing snapshot on either side or an unreadable checkpoint returns PIPEFY_RUNTIME with the comparison service message. Handle errors by code, not by message: the message is translated to the caller's locale.

  • Snapshots, not live data: the comparison is as fresh as the latest uploaded snapshot of each side, and it compares two states. A change made in production after the sandbox opened shows as if the sandbox had made the opposite change.

  • Not compared as property diffs: the pipe name, timestamps, uuids and other identity columns (each row still carries uuid at the top level, not under properties), the start form's public slug, AI agents and pipe tags.

  • Internal columns are left out: a column that changes as a side effect of ordinary edits and has no effect on access, exposure or what the pipe does is never a property, does not make its row updated, and does not count in changes or summary. Publishing still carries it to production. The list lives in RepoSnapshots::Comparison::Catalog::INTERNAL:

    • repo_preferences: custom_sorting_enabled, custom_sorting_preferences (legacy display preference)
    • phases: cloned_from_phase_uuid (clone bookkeeping)
    • fields: slug (identifier set once at creation), cloned_from_id, cloned_from_field_uuid (clone bookkeeping)
    • automations: updated_by_id (last editor)

    Every other column stays a property, including the ones no screen sets, because publishing carries a change to them (made through the API, or made in production after the sandbox opened, which publishing reverts). That covers columns that change access or exposure (repos.authorization, repos.anyone_can_create_card, phases.only_admin_can_move_to_previous, repo_preferences.enable_external_guests, repo_preferences.guests_can_follow_tickets, repo_preferences.inbox_email_enabled, visibilities.resource_type, visibilities.resource_id, public_forms.html, public_forms.css, public_forms.display_pipefy_logo), what an automation or email does (automations.created_by_id, email_templates.smtp_configuration_id, email_templates.insecure_content) and webhooks.email.

  • Null filter: an explicit null filter behaves as ALL.