Commit-based Versioning

PuppyOne uses Mut commits to provide automatic, project-wide versioning for every write operation.

Note: Folder snapshots have been deprecated. PuppyOne now uses Mut commit-based versioning, where every write to the Content API automatically creates a versioned commit. This provides the same safety guarantees as folder snapshots — with finer granularity and no manual snapshot step.

How it works

Every write operation through the Content API (write, mkdir, mv, rm) is recorded as a Mut commit in the mut_commits table. Each commit captures:

What changed — the mutations applied (file content, renames, deletions)
Who made the change — user email or agent identity
When it happened — precise timestamp
Commit message — optional description of the change

This means you get a complete, automatic version history without ever needing to create manual snapshots or backups.

Viewing commit history

Use the versions API to see the full history of changes to any file:

# View all commits for a file
curl -X GET "https://api.puppyone.ai/api/v1/content/{project_id}/versions?path=/research/notes.json" \
  -H "Authorization: Bearer {token}"

Example response:

{
  "versions": [
    {
      "version": 5,
      "created_at": "2025-03-09T15:30:00Z",
      "author": "Agent: data-sync",
      "message": "Synced latest research data"
    },
    {
      "version": 4,
      "created_at": "2025-03-09T14:00:00Z",
      "author": "[email protected]",
      "message": "Updated analysis section"
    }
  ]
}

Comparing versions

Compare any two versions to see exactly what changed:

curl -X GET "https://api.puppyone.ai/api/v1/content/{project_id}/diff?path=/research/notes.json&v1=3&v2=5" \
  -H "Authorization: Bearer {token}"

Rolling back

Restore a file to any historical version. The rollback creates a new commit, so the full history is preserved:

curl -X POST "https://api.puppyone.ai/api/v1/content/{project_id}/rollback" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"path": "/research/notes.json", "version": 3}'

Replacing the folder snapshot workflow

Previously, you would take a manual snapshot of a folder before a large batch operation. With commit-based versioning, this is no longer necessary:

Old workflow (folder snapshots)	New workflow (Mut commits)
Manually create a snapshot before batch operations	Every write automatically creates a commit
Restore the entire folder from a snapshot	Roll back individual files to any version
Snapshot data stored in `folder_snapshots` table	Commit data stored in `mut_commits` table
Required explicit API call to create	Fully automatic — no extra steps

Safe batch operations

Before running a large sync or agent operation, simply note the current version numbers. If something goes wrong, roll back the affected files:

# 1. Check current versions before the operation
curl -X GET "https://api.puppyone.ai/api/v1/content/{project_id}/versions?path=/research/notes.json" \
  -H "Authorization: Bearer {token}"
 
# 2. Run the batch operation (sync, agent task, etc.)
 
# 3. If the result is not what you want, roll back
curl -X POST "https://api.puppyone.ai/api/v1/content/{project_id}/rollback" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"path": "/research/notes.json", "version": 4}'

Next steps

Version History and Rollback - Manage versions for individual files
Version Diff - Compare different versions of a file

File Version History and Rollback Version Diff