Overview & Quickstart
Fervion is an API-first version-control system built for safe and deliberate collaboration between people and AI agents. It separates durable data storage, version snapshots, mutable pointer management, and history auditability.
These docs are for developers learning the model, integrating with the Fervion API, or building client workflows. Below is the core write loop explaining how clients commit changes to the system.
The 3-Step Write Loop
Writing data to Fervion is divided into three distinct operations. By separating content uploads, path trees, and mutable updates, the API protects against accidental overwrites and ensures history can always be audited.
1. Save Object
The client saves file content as an object. The Object API returns a sha256: hash. That hash is now the identity of the bytes, and the object cannot be changed in place.
2. Create Snapshot
Next, the client creates a snapshot. The snapshot maps file paths to object hashes. For example, readme.md points to the object hash returned by the previous write. The snapshot gets its own hash and becomes a frozen tree state.
3. Move Ref
Then the client moves a ref. The client first reads the ref to get its current version_token. It then writes the ref with the new snapshot hash and the expected token. If the token matches, the ref advances. If the token does not match, the write fails and the client must refetch before trying again.