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.

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

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

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 (createdBy/updatedBy/deletedBy), which capture the latest actor on the record itself.

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.

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 wrapped in a comment envelope:

{
  "comment": {
    "id": 2,
    "content": "This looks good! @alice can you confirm the numbers?",
    "userId": 2,
    "recordId": 123,
    "tableId": "orders",
    "createdAt": "2025-01-15T11:00:00Z",
    "updatedAt": "2025-01-15T11:00:00Z",
    "user": { "id": 2, "name": "Bob" }
  }
}

content is required and limited to 10,000 characters. Mentions are not parsed out of the body text — supply the mentioned user IDs yourself in an optional mentions array on the request. They reach automations as $trigger.mentions, so a comment trigger can act on them.

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 user 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 — typically a user may edit/delete their own comments, with broader rights granted to elevated roles.

Cross-cutting rules

Related pages

• Records Overview — authorship metadata vs change history
• CRUD & Upsert — the writes that history records
• Soft Delete & Restore — delete/restore are logged to history
• Table Permissions — who may comment, edit, and delete