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:
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?"}'| Input | What it does |
|---|---|
branch | The branch the comment belongs to, main by default |
id | The document. Leave it out to comment on the branch itself |
path | A field path inside the document, such as seo.description or content[k3f9].heading |
parentId | Replies to a comment; replies form a thread |
body | The text, up to 10,000 characters |
assignee | A member id: the comment becomes a task |
dueAt | A 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.
curl "https://api.galerne.cloud/p/acme/v1/docs/harbours/history?limit=20" -H "Authorization: Bearer gal_…"{ "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:
{ "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#
| Plan | History kept |
|---|---|
| Free | 7 days |
| Pro | 90 days |
| Business | 1 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.