Versioning

Every write in KiwiFS becomes a git commit, authored by the request’s actor. These endpoints read that history: list a file’s commits, fetch an old version, diff two versions, see who wrote each line, or follow every change across the workspace. All paths are relative to http://localhost:3333/api/kiwi. Blame and some diff modes depend on the versioning strategy; see Versioning.

List file versions

Returns the commits that touched a file, newest first. GET /versions

string

required

File path.

curl 'http://localhost:3333/api/kiwi/versions?path=concepts/auth.md'

string

The requested path.

object[]

Show version

string

Full commit hash.

string

Commit time, for example 2026-10-19 09:30:00 +0000.

string

The actor that made the write.

string

Commit subject.

Response

{
  "path": "concepts/auth.md",
  "versions": [
    {
      "hash": "e4f5a6b7c8d9e4f5a6b7c8d9e4f5a6b7c8d9e4f5",
      "date": "2026-10-19 09:30:00 +0000",
      "author": "agent:docs-writer",
      "message": "agent:docs-writer: concepts/auth.md"
    },
    {
      "hash": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
      "date": "2026-10-12 14:05:11 +0000",
      "author": "agent:importer",
      "message": "agent:importer: bulk write — 3 files"
    }
  ]
}

A file with no history returns an empty versions array.

Read a past version

Returns a file’s content as it was at a given commit. GET /version

string

required

File path.

string

required

Commit hash, full or abbreviated.

curl 'http://localhost:3333/api/kiwi/version?path=concepts/auth.md&version=a1b2c3d'

Response

# Authentication

Original content from the first commit.

The body is text/markdown. Returns 404 if the file did not exist at that commit.

Diff two versions

Returns a unified diff of one file between two commits, as plain text. GET /diff

string

required

File path.

string

required

Older commit hash.

string

required

Newer commit hash.

string

default:"line"

line for a unified diff or word for a word-level diff ([-removed-]{+added+} markers).

curl 'http://localhost:3333/api/kiwi/diff?path=concepts/auth.md&from=a1b2c3d&to=e4f5a6b'

curl 'http://localhost:3333/api/kiwi/diff?path=concepts/auth.md&from=a1b2c3d&to=e4f5a6b&granularity=word'

Response

diff --git a/concepts/auth.md b/concepts/auth.md
--- a/concepts/auth.md
+++ b/concepts/auth.md
@@ -1,3 +1,5 @@
 # Authentication

-Original content from the first commit.
+OAuth2 + JWT based authentication system.
+
+Supports refresh token rotation.

Returns 400 for any other granularity and 501 when the versioning strategy cannot produce a word diff.

Blame

Returns the commit, author, and date that last changed each line of a file. GET /blame

string

required

File path.

curl 'http://localhost:3333/api/kiwi/blame?path=concepts/auth.md'

string

The requested path.

object[]

Show line

integer

1-based line number.

string

Line content.

string

Commit that last changed the line.

string

Actor of that commit.

string

Commit time (RFC 3339).

Response

{
  "path": "concepts/auth.md",
  "lines": [
    {"line": 1, "author": "agent:importer", "date": "2026-10-12T14:05:11Z", "hash": "a1b2c3d4...", "text": "# Authentication"},
    {"line": 3, "author": "agent:docs-writer", "date": "2026-10-19T09:30:00Z", "hash": "e4f5a6b7...", "text": "OAuth2 + JWT based authentication system."}
  ]
}

Blame needs the git strategy. Copy-on-write and noop strategies return 501. An uncommitted file returns an empty lines array.

author is the X-Actor (or the key’s actor) from the original write, so blame shows which agent wrote each section.

Change feed

Lists recent commits across the whole workspace, newest first. Use it to sync external systems: poll with the last hash you saw, or long-poll to wait for the next change. GET /changes

string

Commit hash. Returns only commits after it. Omit to get the latest commits.

integer

default:"50"

Maximum changes to return, up to 500.

string

Set to longpoll to hold the request open until a change arrives when there are none yet.

string

default:"30s"

How long a long-poll waits, as a Go duration. Capped at 120s. Returns an empty list on timeout.

curl 'http://localhost:3333/api/kiwi/changes?limit=10'

curl 'http://localhost:3333/api/kiwi/changes?since=e4f5a6b7c8d9&feed=longpoll&timeout=60s'

object[]

Show change

string

Commit hash.

string

Path changed. Empty for bulk writes.

string

write, delete, or rename.

string

Commit author.

string

Commit time (RFC 3339).

string

Hash of the newest change in this response. Pass it as since next time. Empty when there are no changes.

Response

{
  "changes": [
    {"seq": "e4f5a6b7...", "path": "concepts/billing.md", "action": "delete", "actor": "agent:cleanup", "timestamp": "2026-10-19T12:01:00Z"},
    {"seq": "d3e4f5a6...", "path": "concepts/auth.md", "action": "write", "actor": "agent:docs-writer", "timestamp": "2026-10-19T12:00:00Z"}
  ],
  "last_seq": "e4f5a6b7..."
}

Returns 400 with unknown sequence when since is not a known commit, and 503 if the long-poll subscriber limit is reached. For a push stream instead of polling, use Server-Sent Events.

Optimistic concurrency

Use ETags and If-Match to avoid lost updates.

Versioning concepts

Git, copy-on-write, and noop strategies.

Real-time events

Subscribe to changes over SSE.

Drafts

Stage changes on a branch.

REST API

CLI

List file versions

Read a past version

Diff two versions

Blame

Change feed

Optimistic concurrency

Versioning concepts

Real-time events

Drafts

​List file versions

​Read a past version

​Diff two versions

​Blame

​Change feed

​Related

Optimistic concurrency

Versioning concepts

Real-time events

Drafts

List file versions

Read a past version

Diff two versions

Blame

Change feed

Related