Snapshots and diff

Overview

Every time Configly syncs your Zendesk instance, it creates a snapshot: a point-in-time record of all config objects. Each snapshot is identified by a version string, which is the primary public identifier you use when comparing changes over time.

The diff endpoints let you compare any two snapshots to see exactly what was added, removed, or modified between them.

List snapshots

GET /v1/connections/:connectionId/snapshots

Returns a paginated list of available snapshot versions, newest first. Each entry includes the version string, creation timestamp, and which config types were captured.

Query parameters

Example request

curl https://api.configly.app/v1/connections/YOUR_CONNECTION_ID/snapshots?page=1&limit=5 \
  -H "Authorization: Bearer cly_your_key"

Example response

{
  "data": [
    {
      "version": "2026-04-16T08:00:00.000Z",
      "createdAt": "2026-04-16T08:00:12.345Z",
      "configTypes": ["triggers", "macros", "views", "ticket_fields"]
    },
    {
      "version": "2026-04-15T08:00:00.000Z",
      "createdAt": "2026-04-15T08:00:09.876Z",
      "configTypes": ["triggers", "macros", "views", "ticket_fields"]
    }
  ],
  "meta": {
    "page": 1,
    "limit": 5,
    "total": 42,
    "totalPages": 9
  }
}

Compare against previous version

GET /v1/connections/:connectionId/diff/previous/:version

Compares the specified version against its immediate predecessor. Returns 404 if no earlier version exists (the supplied version is the first snapshot for the connection).

Example request

curl https://api.configly.app/v1/connections/YOUR_CONNECTION_ID/diff/previous/2026-04-16T08%3A00%3A00.000Z \
  -H "Authorization: Bearer cly_your_key"

Compare two versions

GET /v1/connections/:connectionId/diff/versions?version1=X&version2=Y

Compares two specific versions by their version strings. Both parameters are required and must be different from each other.

Example request

curl "https://api.configly.app/v1/connections/YOUR_CONNECTION_ID/diff/versions?version1=2026-04-15T08%3A00%3A00.000Z&version2=2026-04-16T08%3A00%3A00.000Z" \
  -H "Authorization: Bearer cly_your_key"

Compare by snapshot IDs

GET /v1/connections/:connectionId/diff?snapshot1=X&snapshot2=Y

Compares two snapshots using their internal IDs rather than version strings. Both parameters are required and must be different. The response still uses version strings as identifiers, not snapshot IDs.

Diff response shape

All three diff endpoints return the same response structure:

{
  "data": {
    "version1": "2026-04-15T08:00:00.000Z",
    "version2": "2026-04-16T08:00:00.000Z",
    "types": [
      {
        "configType": "triggers",
        "added": [
          { "id": 999, "title": "New trigger" }
        ],
        "removed": [],
        "modified": [
          {
            "id": 12345,
            "title": "Auto-close solved tickets",
            "changes": { "...": "..." }
          }
        ]
      }
    ],
    "summary": {
      "total": {
        "added": 1,
        "removed": 0,
        "modified": 1,
        "unchanged": 45
      },
      "byType": {
        "triggers": { "added": 1, "removed": 0, "modified": 1, "unchanged": 20 }
      }
    },
    "createdAt": "2026-04-16T08:00:12.345Z"
  }
}

The types array contains one entry per config type that has changes. Each entry lists the items that were added, removed, or modified between the two versions. The summary object provides totals and a per-type breakdown.

Error codes