English
Version Control
File Version History and Rollback

Version History and Rollback

Every write creates a versioned commit automatically, so you can inspect history and restore any point in time whenever needed.

Automatic versioning

Whenever a file (JSON, Markdown, or other content) is modified through the Content API, PuppyOne automatically:

  1. Creates a new commit with the current content
  2. Records when the change happened and who made it (human user or agent)
  3. Preserves the full chain of historical commits

No manual saving or commit is required. Whether the change comes from the Dashboard, API, or an agent writing through MCP, every update is tracked.

View version history

Dashboard

  1. Open your Project -> select a file
  2. Click the History tab in the right panel
  3. Review the version list, including version number, timestamp, and author

API

# Get the version history of a file
curl -X GET "https://api.puppyone.ai/api/v1/content/{project_id}/versions?path=/docs/product-spec.md" \
  -H "Authorization: Bearer {token}"

Example response:

{
  "versions": [
    {
      "version": 5,
      "created_at": "2025-03-09T15:30:00Z",
      "author": "Agent: data-sync",
      "size": 2048
    },
    {
      "version": 4,
      "created_at": "2025-03-09T14:00:00Z",
      "author": "[email protected]",
      "size": 1856
    }
  ]
}

View the content of a specific version

API

# Get the full contents of version 3
curl -X GET "https://api.puppyone.ai/api/v1/content/{project_id}/versions?path=/docs/product-spec.md&version=3" \
  -H "Authorization: Bearer {token}"

The response returns the complete file contents for that version, which you can use for previewing or manually restoring partial data.

Roll back to a historical version

Rollback restores the file to the contents of a specific version. The rollback operation itself also creates a new commit, so the history is never lost.

Dashboard

  1. Open the file's History panel
  2. Select the version you want to restore
  3. Click Restore
  4. Confirm the rollback

API

# Roll back to version 3
curl -X POST "https://api.puppyone.ai/api/v1/content/{project_id}/rollback" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"path": "/docs/product-spec.md", "version": 3}'

Real scenario: recovering from an agent mistake

Suppose you asked an agent to update a product document, but it accidentally overwrote the entire file:

# 1. Check version history to confirm the problem
curl -X GET "https://api.puppyone.ai/api/v1/content/{project_id}/versions?path=/docs/product-spec.md" \
  -H "Authorization: Bearer {token}"
 
# Output shows v8 is the bad write by the agent
# v7 is the correct version
 
# 2. Compare versions to confirm the diff
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}"
 
# 3. Roll back to the correct version
curl -X POST "https://api.puppyone.ai/api/v1/content/{project_id}/rollback" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"path": "/docs/product-spec.md", "version": 7}'

The full recovery takes less than a minute, with zero data loss.

Notes

  • Rollback never deletes historical versions; it creates a new commit with the content of the target version
  • Version numbers always increase, even after rollback
  • Each file manages its version history independently, so changing one file does not affect others
  • Version history records the author, so you can trace changes later in the Audit Log

Next steps

OverviewFolder Snapshots