English
Version Control
Version Diff

Version Diff

Compare any two versions side by side and inspect every change precisely.

What is version diff

Version diff lets you compare any two historical versions of the same file line by line, clearly showing:

  • Added content (green)
  • Deleted content (red)
  • Modified content (yellow)

Whether the file is a JSON document, a Markdown file, or another supported type, version diff is available.

View a version diff

Dashboard

  1. Open your Project -> select a file
  2. Click the History tab to open the version history panel
  3. Select the two versions you want to compare
  4. Click Compare to open the diff view

API

# Compare version 2 and version 5
curl -X GET "https://api.puppyone.ai/api/v1/content/{project_id}/diff?path=/docs/readme.md&v1=2&v2=5" \
  -H "Authorization: Bearer {token}"

Example response:

{
  "path": "/docs/readme.md",
  "v1": 2,
  "v2": 5,
  "diff": {
    "additions": 8,
    "deletions": 3,
    "modifications": 2,
    "patches": [
      {
        "path": "/title",
        "op": "unchanged",
        "value": "Product Documentation"
      },
      {
        "path": "/sections/0/heading",
        "op": "replace",
        "old_value": "Feature Overview",
        "new_value": "Core Features"
      }
    ]
  }
}

Common use cases

Review an agent's changes

After an agent completes a write, compare the versions before and after the write to confirm the result matches expectations:

# View recent version history
curl -X GET "https://api.puppyone.ai/api/v1/content/{project_id}/versions?path=/docs/product-spec.md" \
  -H "Authorization: Bearer {token}"
 
# Compare the versions before and after the agent change
curl -X GET "https://api.puppyone.ai/api/v1/content/{project_id}/diff?path=/docs/product-spec.md&v1=7&v2=8" \
  -H "Authorization: Bearer {token}"

If the change is not what you want, you can roll back directly to the earlier version.

Compare changes before and after sync

After syncing from an external data source, inspect exactly what the sync introduced:

# Before syncing, note the current version number (for example v12)
curl -X GET "https://api.puppyone.ai/api/v1/content/{project_id}/versions?path=/research/notion-data.json" \
  -H "Authorization: Bearer {token}"
 
# Run the sync via the access management API
 
# Compare before and after sync
curl -X GET "https://api.puppyone.ai/api/v1/content/{project_id}/diff?path=/research/notion-data.json&v1=12&v2=13" \
  -H "Authorization: Bearer {token}"

Track how data changes over time

Compare two versions far apart in time to understand how the data evolved overall:

# Compare the version from a week ago to the current one
curl -X GET "https://api.puppyone.ai/api/v1/content/{project_id}/diff?path=/analytics/metrics.json&v1=3&v2=15" \
  -H "Authorization: Bearer {token}"

Diff format explained

For text-based content, the diff uses the standard unified diff format:

MarkerMeaning
--- / +++Identify the old version and the new version
Lines starting with -Present in the old version but deleted in the new one
Lines starting with +Added in the new version
Lines with no prefixContent that is the same in both versions (context)

For JSON files, the API diff also includes structured change paths (JSON Patch format) for programmatic handling.

Next steps

Folder SnapshotsOverview