11 September 2026

Link a document to an earlier one, and see what changed

A push can now say it is a new version of an earlier document — ?replaces= in the API, --replaces from the CLI, a replaces input in the Action. It is opt-in: nothing links documents on its own, and a plain push stays the unrelated document it has always been. Linked documents get a chain icon in the history and a line-by-line diff against the version before them.

Every push here makes a brand-new document, and that is not an accident to be fixed: a link somebody pasted into a comment three weeks ago has to keep showing what that commit said. But a release note pushed every Friday really is the same document seven times, and nothing could say so. Now something can.

Saying it

One parameter, on the push that creates the newer document:

curl -H "Authorization: Bearer tp_live_…" --data-binary @v2.md \
  "https://transformpipe.com/api/v1/documents?name=notes.md&replaces=<id>"

The CLI spells it --replaces <id>, and the GitHub Action takes a replaces input. The id of the earlier document is what tp list prints, and what the Action's documents output carries. It has to be a document on the same account, or the request comes back 404 rather than linking to something you cannot see.

What you get

In the history, a linked document carries a chain icon. Opening it lists the whole chain oldest first, and any entry with something before it can be compared against it: a line-level diff, computed in your browser from the two sources it already fetched, so nothing on the server is doing the comparing.

From a program, GET /api/v1/documents/:id/versions — or tp versions <id> — answers with the chain from any member of it — the ancestors it replaces, and everything that went on to replace those — each with its id, name, created_at and its own replaces. The assistant connector exposes the same thing as tp_document_versions. Every document in a list also carries replaces, so a client with the list in hand can work out the chains without a request per row.

Why nothing is inferred

A converter that guessed would be wrong in the way that costs you something. Two files with the same name are often not versions of each other — a README.md from two different repositories, the same report for two different months — and a tool that chained them would quietly present one as the successor of the other. So the name means nothing here, the conversion means nothing, and the time means nothing: a document is a version of another one because somebody said so, one document at a time.

What it is not

It is not automatic history. Nothing in this app edits a document in place, so no version appears without a push, and there is no revert: an older version is still its own document, at its own address, with its own share link. Deleting an older one does not delete the newer — the link simply goes away, and what is left is the unrelated document it would have been anyway.