# Comments and history

> Comment on documents, single fields and branches, mention people, assign tasks with due dates, read who changed what and when, compare versions field by field, and restore a document or some of its fields.

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?"}'
```

| 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.

```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](/docs/branches.md#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](/docs/agents.md#audit-log) of Business projects keeps the same length of time.
