Skip to main content
View as Markdown

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
{
  "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 (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, including parsed mentions and the resolved author:

{
  "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) 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 — 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