# Record History & Comments

Every record carries two activity surfaces: an automatic **change history** (a system-maintained audit trail of who changed what and when) and a **comment thread** (user-authored discussion attached to the record). Both are reachable under the record's URL.

| Method & Path                                                       | Description                              |
| ------------------------------------------------------------------- | ---------------------------------------- |
| `GET /api/tables/:tableId/records/:recordId/history`                | Retrieve the change history for a record |
| `GET /api/tables/:tableId/records/:recordId/comments`               | List comments on a record                |
| `GET /api/tables/:tableId/records/:recordId/comments/:commentId`    | Read a single comment                    |
| `POST /api/tables/:tableId/records/:recordId/comments`              | Create a comment                         |
| `PATCH /api/tables/:tableId/records/:recordId/comments/:commentId`  | Edit a comment                           |
| `DELETE /api/tables/:tableId/records/:recordId/comments/:commentId` | Delete a comment                         |

## Change history

History is tracked automatically for all tables — there is nothing to enable. Every create, update, delete, and restore is recorded with the acting user and a structured field-level diff. Read it with:

```
GET /api/tables/orders/records/123/history
```

```json
{
  "history": [
    {
      "id": 1,
      "action": "update",
      "changes": {
        "status": { "from": "pending", "to": "approved" }
      },
      "user": { "id": 1, "name": "Alice" },
      "timestamp": "2025-01-15T10:30:00Z"
    }
  ],
  "total": 1
}
```

| Field       | Description                                  |
| ----------- | -------------------------------------------- |
| `action`    | `create`, `update`, `delete`, or `restore`   |
| `changes`   | Per-field `{ from, to }` diff for the change |
| `user`      | The acting user (`id`, `name`)               |
| `timestamp` | ISO 8601 time the change occurred            |

The history records changes from **all** sources — REST API writes, admin edits, automations, and batch operations — so the trail is complete. It complements the per-record [authorship fields](records-overview) (`createdBy`/`updatedBy`/`deletedBy`), which capture the latest actor on the record itself.

:::callout
**Retention and field-tracking config is not yet available.** History is currently tracked automatically for every table with no per-table options. Configurable retention policies and selective field tracking will arrive in a future schema version.
:::

## Comments

Comments are user-authored notes attached to a record, supporting `@mentions`. The current user is injected as the author automatically — you only supply the `content`.

```json
POST /api/tables/orders/records/123/comments
{
  "content": "This looks good! @alice can you confirm the numbers?"
}
```

A successful create returns `201 Created` with the stored comment, including parsed mentions and the resolved author:

```json
{
  "id": 2,
  "content": "This looks good! @alice can you confirm the numbers?",
  "mentions": [{ "userId": 1, "username": "alice", "position": 21 }],
  "author": { "id": 2, "name": "Bob" },
  "created_at": "2025-01-15T11:00:00Z"
}
```

`content` is required and limited to 10,000 characters. `@username` tokens are parsed into a `mentions` array (each with the resolved `userId`, `username`, and character `position`), which downstream features (e.g. [notifications](notifications)) consume.

### Reading comments

```
GET /api/tables/orders/records/123/comments       # list all
GET /api/tables/orders/records/123/comments/2      # single comment
```

The list endpoint returns the comment thread for the record. The author object is projected to a safe display shape (`id`, `name`) — email and other PII are never exposed in comment responses.

### Editing and deleting

```
PATCH  /api/tables/orders/records/123/comments/2
DELETE /api/tables/orders/records/123/comments/2
```

Editing replaces `content` (re-parsing mentions); deleting removes the comment. Both honor RBAC and the table's [permissions](table-permissions) — typically a user may edit/delete their own comments, with broader rights granted to elevated roles.

## Cross-cutting rules

| Concern        | Behavior                                                               |
| -------------- | ---------------------------------------------------------------------- |
| Authentication | All endpoints require a session (`401` otherwise)                      |
| Existence      | Unknown table/record/comment returns `404` (anti-enumeration)          |
| Author safety  | Comment author is server-injected; client-supplied authors are ignored |
| PII            | Author projection exposes only `id` and `name`                         |

## Related pages

- [Records Overview](records-overview) — authorship metadata vs change history
- [CRUD & Upsert](records-crud) — the writes that history records
- [Soft Delete & Restore](records-soft-delete) — delete/restore are logged to history
- [Table Permissions](table-permissions) — who may comment, edit, and delete