Change Tracking

Change Tracking gives you a continuous audit trail of what changed on every managed device. The Breeze agent monitors six categories of system changes — software installs and removals, Windows service modifications, startup item additions, network adapter changes, scheduled task updates, and user account mutations — and ships them to the API in compressed batches. Every change is fingerprinted with a SHA-256 hash to prevent duplicates, then stored with before/after snapshots so you can see exactly what was modified.

This feature is designed for compliance auditing, troubleshooting, and drift detection. When a user reports that something stopped working, you can pull up the device’s change timeline and see that a critical service was disabled 20 minutes earlier. When you need to prove to an auditor that no unauthorized software was installed, the change log provides cryptographically deduplicated evidence.

---

Key Concepts

Change Types

| Type | Description | |---|---| | software | Application installed, removed, or updated | | service | Windows service or system daemon added, removed, or modified | | startup | Startup program or launch agent added, removed, or changed | | network | Network adapter configuration changed (IP, DNS, gateway) | | scheduled_task | Scheduled task or cron job added, removed, or modified | | user_account | Local user account created, deleted, or modified |

Change Actions

| Action | Description | |---|---| | added | A new item was detected (software installed, user created, etc.) | | removed | An existing item was deleted (software uninstalled, user removed, etc.) | | modified | An existing item’s properties changed (service startup type, scheduled task trigger, etc.) | | updated | A version update was applied (software upgraded, definition file refreshed, etc.) |

Change Record Fields

| Field | Type | Description | |---|---|---| | id | UUID | Unique identifier for the change record | | deviceId | UUID | Device where the change was detected | | orgId | UUID | Organization the device belongs to | | fingerprint | string (64 chars) | SHA-256 hash for deduplication | | timestamp | datetime | When the change occurred on the device | | changeType | enum | One of the six change types above | | changeAction | enum | One of the four change actions above | | subject | string (max 500) | Human-readable description of what changed (e.g., “Google Chrome 122.0.6261.69”) | | beforeValue | JSON | State before the change (null for added actions) | | afterValue | JSON | State after the change (null for removed actions) | | details | JSON | Additional context (installer path, registry key, etc.) | | createdAt | datetime | When the record was stored in the database |

---

How Changes Are Collected

1. Agent detects a change. The agent periodically snapshots system state (installed software, services, startup items, etc.) and compares against the previous snapshot. Differences are formatted as change records.

2. Agent ships changes in a batch. Changes are serialized as JSON, gzip-compressed, and sent to the API via PUT /api/v1/agents/:id/changes. Up to 1,000 changes per request, with a 5 MB compressed body limit and 10 MB decompressed limit.

3. API deduplicates and stores. Each change is fingerprinted by hashing the combination of timestamp, change type, action, subject, before/after values, and details. A unique constraint on (deviceId, fingerprint) prevents the same change from being inserted twice. Changes are inserted in batches of 200.

4. Partial success handling. If some changes in a batch fail to insert (e.g., database error on a subset), the API returns HTTP 207 with a partial: true flag, the count of successfully inserted records, and the total submitted.

Tip

The gzip compression typically reduces payload size by 80-90%, making it practical for agents to ship hundreds of changes per batch even over constrained connections.

---

Querying Changes

The changes API supports filtering by device, time range, change type, and action, with cursor-based pagination for efficient iteration through large result sets.

Basic Query

curl "/api/v1/changes?deviceId=DEVICE_UUID&changeType=software&limit=50" \
  -H "Authorization: Bearer $TOKEN"

Available Filters

| Parameter | Type | Description | |---|---|---| | deviceId | UUID | Filter to a single device | | startTime | ISO 8601 datetime | Only changes at or after this time | | endTime | ISO 8601 datetime | Only changes at or before this time | | changeType | enum | One of: software, service, startup, network, scheduled_task, user_account | | changeAction | enum | One of: added, removed, modified, updated | | limit | integer | Results per page (1 — 500, default 100) | | cursor | string | Opaque cursor for the next page |

Response Format

{
  "changes": [
    {
      "id": "uuid",
      "deviceId": "uuid",
      "hostname": "DESKTOP-ABC123",
      "timestamp": "2026-02-15T14:30:00.000Z",
      "changeType": "software",
      "changeAction": "added",
      "subject": "Visual Studio Code 1.96.2",
      "beforeValue": null,
      "afterValue": {
        "version": "1.96.2",
        "vendor": "Microsoft Corporation",
        "installLocation": "C:\\Program Files\\Microsoft VS Code"
      },
      "details": null
    }
  ],
  "total": 1847,
  "showing": 50,
  "hasMore": true,
  "nextCursor": "eyJ0aW1lc3RhbXAiOiIyMDI2..."
}

Cursor-Based Pagination

The API uses cursor-based pagination for stable results when new changes arrive during iteration. The nextCursor field is a base64url-encoded JSON object containing the timestamp and ID of the last returned record. Pass it as the cursor query parameter to get the next page.

# First page
curl "/api/v1/changes?deviceId=DEVICE_UUID&limit=100" \
  -H "Authorization: Bearer $TOKEN"

# Next page (using nextCursor from the previous response)
curl "/api/v1/changes?deviceId=DEVICE_UUID&limit=100&cursor=eyJ0aW1lc3RhbXAi..." \
  -H "Authorization: Bearer $TOKEN"

---

Agent Ingest Endpoint

The agent pushes changes directly to the API using bearer token authentication.

PUT /api/v1/agents/:agentId/changes
Content-Type: application/json
Content-Encoding: gzip
Authorization: Bearer AGENT_TOKEN

{
  "changes": [
    {
      "timestamp": "2026-02-15T14:30:00.000Z",
      "changeType": "software",
      "changeAction": "added",
      "subject": "Visual Studio Code 1.96.2",
      "afterValue": {
        "version": "1.96.2",
        "vendor": "Microsoft Corporation"
      }
    }
  ]
}

Ingest Response Codes

| Status | Meaning | |---|---| | 200 | All changes accepted (or empty batch) | | 207 | Partial success — some changes inserted, some failed | | 400 | Invalid request body or decompression failure | | 404 | Agent/device not found | | 413 | Request body exceeds 5 MB compressed or 10 MB decompressed | | 500 | All changes failed to insert |

---

Fingerprint Deduplication

Every change is assigned a SHA-256 fingerprint computed from a stable concatenation of:

1. Canonical ISO 8601 timestamp
2. Change type
3. Change action
4. Subject
5. Stable-sorted JSON of beforeValue
6. Stable-sorted JSON of afterValue
7. Stable-sorted JSON of details

This fingerprint is stored in a VARCHAR(64) column with a unique index on (deviceId, fingerprint). When the agent ships the same change twice (e.g., after a retry), the database ON CONFLICT DO NOTHING clause silently skips the duplicate.

Within a single request, the API also deduplicates by fingerprint before attempting insertion, so batch payloads with repeated entries are handled efficiently.

---

API Reference

| Method | Path | Description | |---|---|---| | GET | /api/v1/changes | List changes with filters and cursor pagination | | PUT | /api/v1/agents/:id/changes | Agent ingest endpoint for shipping change batches |

---

Troubleshooting

Changes not appearing for a device Verify the agent is enrolled and the device exists in the platform. The ingest endpoint looks up the device by agentId, not by device UUID. If the agent is not enrolled, the endpoint returns 404.

Duplicate changes appearing This should not happen due to fingerprint deduplication. If you see exact duplicates, check whether the agent is sending changes with different timestamps for the same event (e.g., using local time vs. UTC). The fingerprint includes the timestamp, so a one-second difference produces a different hash.

Large change volumes after a software deployment This is expected. Mass deployments (e.g., pushing a new application to 500 devices) will generate 500 software:added change records. Use the changeType and changeAction filters to focus on specific categories, and cursor pagination to iterate efficiently.

207 partial success responses A 207 means some changes in the batch were inserted and some failed. This can happen if the database has transient issues. The agent should not retry the entire batch because the successfully inserted changes would be deduplicated anyway. Check server logs for the underlying database error.

Request body too large (413) The ingest endpoint limits compressed payloads to 5 MB and decompressed payloads to 10 MB. If agents are hitting this limit, reduce the batch size or increase the shipping frequency. These limits can be tuned with the CHANGE_INGEST_MAX_BODY_BYTES and CHANGE_INGEST_MAX_DECOMPRESSED_BYTES environment variables.