docs menu

Comments and history

People and agents talk about content where it lives: on a document, on one field of it, or on a whole branch. Every change is kept as a version with its author, so you can see who did what, compare two versions and bring an old one back.

Comments#

In the studio, open the comments panel of a document, or the review page of a branch. Agents and scripts use the comment tool:

bash
curl https://api.galerne.cloud/p/acme/v1/comments \
  -H "Authorization: Bearer gal_…" -H "content-type: application/json" \
  -d '{"branch":"agent/translate-de","id":"harbours","path":"title.de","body":"@[Marie] is Häfen the word we use in the glossary?"}'
InputWhat it does
branchThe branch the comment belongs to, main by default
idThe document. Leave it out to comment on the branch itself
pathA field path inside the document, such as seo.description or content[k3f9].heading
parentIdReplies to a comment; replies form a thread
bodyThe text, up to 10,000 characters
assigneeA member id: the comment becomes a task
dueAtA due date for the task, ISO 8601 with an offset

Mention people with @email (@ada@example.com) or @[Name] (@[Alt-text bot]). A mentioned person, and the assignee of a task, get an email; agents and the author get none. Every new comment sends the comment.created event.

Threads and tasks#

update_comment (PATCH /p/<project>/v1/comments/<id>) edits your own comment, resolves or reopens a thread with resolved, marks a task done with done, and changes its assignee or dueAt (null clears them). delete_comment deletes a comment and its replies: authors delete their own, admins any.

list_comments (GET /p/<project>/v1/comments?branch=<branch>&id=<doc>) returns the comments of a document or a branch. Resolved threads are left out unless you pass includeResolved=true, and openTasks=true keeps only tasks that are not done. The studio home page lists the tasks assigned to you.

Commenting is open to every role, viewers included. Agents read the reviewers' comments with list_comments or branch_changes and fix what they ask.

History#

Every write records a version: who made it (person, agent, token or the system), when, on which branch, and what kind of change it was: create, edit, publish, unpublish, delete, restore, promote, rebase (an update from main) or rollback. Edits by the same author within 10 minutes fold into one version, so a session of typing makes one version.

In the studio, the history panel of a document lists the latest versions, and history opens the full page: versions grouped by day, with the field diff of each one.

bash
curl "https://api.galerne.cloud/p/acme/v1/docs/harbours/history?limit=20" -H "Authorization: Bearer gal_…"
json
{ "versions": [{ "seq": 912, "branch": "main", "kind": "edit", "author": "human:acc_…", "authorName": "Marie", "authorKind": "human", "published": false, "from": "2026-10-16T09:02:10.000Z", "at": "2026-10-16T09:09:55.000Z" }] }

On a branch, get_history with branch lists the versions of the branch and of main. To compare two versions, pass diff: { "from": 880, "to": 912 } returns the change of each field between them, and without to it compares with the current draft. Over REST, diff goes in the query string as JSON.

Restore#

restore_version brings back a past version, as a new change on top of the history:

json
{ "branch": "main", "id": "harbours", "seq": 880, "paths": ["title", "seo.description"] }

Without paths, the whole document returns to that version. With paths, only those fields do, and the rest keeps its current values. The restored values land in the draft; publish to put them online. The studio's history page has a restore button for the whole version and one per field.

To undo a whole promotion or release, see roll back.

How long history is kept#

PlanHistory kept
Free7 days
Pro90 days
Business1 year

Older versions are removed every few hours, except the latest version of each document on each branch. The audit log of Business projects keeps the same length of time.