Working with records

A record is one row in one of your workspace’s tables — a deal, a contact, a ticket. This guide covers everything you do with records day to day: creating and editing them, the record page and how admins can arrange it, the change and stage histories, discussion threads, attachments, and sharing a single record with a colleague.

If you only remember one thing: the record page is assembled per viewer. Every panel on it — the fields, the history, the comments, even whether the record can be found at all — is filtered to what you are allowed to see. Two people can open the same record and see different fields, different history entries, and in some cases no record at all. The server does this filtering; the page just shows what comes back.

Who can do what

Record work is governed by the normal roles and actions model. The relevant actions:

Action	Grants	Held by default
`records:read`	See records (subject to row and field visibility)	Admin, Member, Reader
`records:create`	Create records	Admin, Member
`records:update`	Edit records — and create/remove shares on records you can edit	Admin, Member
`records:delete`	Delete records	Admin, Member
`comments:read`	Use the discussion feature (see records’ comments)	Admin, Member, Reader
`comments:create`	Post comments; edit and delete your own	Admin, Member
`comments:moderate`	Delete (never edit) someone else’s comment	Admin
`audit:read`	See a record’s change history	Admin, Member, Reader
`attachments:read`	Download attachments	Admin, Member, Reader
`attachments:manage`	Upload and delete attachments	Admin, Member
`customization:read`	Load the admin-configured record layout	Admin, Member, Reader
`customization:manage`	Configure a table’s record layout	Admin

Actions answer “may you do this at all”. Which rows you can see or edit is the separate visibility question — table record visibility, record scopes, ownership and shares — covered in Authorization & Permissions. Every endpoint in this guide resolves the record through your row filter first: a record outside your scope behaves as if it does not exist (a 404, not a “forbidden”).

Creating, editing and deleting records

Create a record from the table’s record list (open a table, then Add Item), by adding a row in a sheet view (see Views), or in bulk via CSV import. The API equivalent is POST /tables/{tableId}/items. Attachment fields can be filled during creation — the file uploads first and is bound to the new record when you save.

Edit on the record page. Editing is deliberately explicit rather than autosaving:

Changed fields are marked, and a counter shows how many unsaved changes you have. Each changed field has its own undo, so you can revert one field without losing the rest.
Save writes only the fields you changed (a PATCH), so you never clobber a column you didn’t touch.
Saving is disabled while your connection is offline.

Conflicts are detected, not silently merged. Each save carries the record’s last-seen timestamp; if someone else (or an import, or an integration) changed the record while you were editing, the save is rejected with a clear message asking you to reload and re-apply your changes. Nothing is overwritten. See Data consistency for the model behind this.

Two other things can intercept a save:

Stage rules. If the table has a pipeline, a stage field only accepts moves the stage machine allows, and fields required for the target stage are flagged the moment you pick it — before you save, not after it fails. See Lifecycles.
Approval rules. If an enabled approval rule matches your change, the save is held: nothing is written, and the page offers to send the change for approval instead. Your edits stay on screen while the request waits. This applies to everyone, including admins. See Approvals.

Delete from the record list’s row actions (with a confirmation). Deletion is permanent from the app’s point of view — there is no per-record recycle bin — but the deletion itself is recorded in the change history and the audit log, including the record’s final values.

The record page

Opening a record shows the end-user record page. Top to bottom:

The record page, panel by panel. Panels a viewer lacks the permission for hide themselves rather than showing an error.

Reference fields link onward: a related record opens on its own record page, and related lists show the child records that point at this record through a reference field.

The record layout (admins)

By default the record page simply lists every field. An admin can arrange it per table — from the table’s schema editor in the builder area, under Record page layout:

Title field — which field’s value titles the page (and names the record in search results and recents).
Highlights — up to 8 fields pinned to the header strip.
Sections — named groups of fields, in order, optionally collapsed by default (up to 30 sections).
Related lists — rename or hide the per-table related-record groups.
Show history — whether the page displays the change history panel at all. (The history endpoint keeps its own permission check regardless; this only decides whether the page asks.)
Arranging for — which audience this layout is for: everyone, or one group. A group’s layout is a separate document, so Sales can open a Deal with pipeline fields at the top while Finance foregrounds billing, and a group without one inherits the workspace’s. You need not be in the group you are composing for. Which group’s layout a person sees is their own choice under Page layout in the app bar — see Workspace administration.

Two safety properties are built in:

A layout can never hide data. Any field the layout doesn’t mention still renders, in an auto-generated Details section. Hiding a field from someone is a permissions decision (field visibility), never a layout one. This holds per group too: targeting a layout at a team changes how their page is arranged, never which records or fields they may read.
A layout can never break the page. Field ids are resolved at render time; a field deleted after the layout was saved is simply skipped.

Reading the layout requires customization:read (all built-in roles have it — a role without it just gets the default page). Saving requires customization:manage (admins). The API is GET /tables/{tableId}/record-layout, PUT /tables/{tableId}/record-layout (a full replace), and DELETE /tables/{tableId}/record-layout to discard the layout and revert to the default page. All three take an optional ownerScope (with ownerGroupId) to address one audience’s layout; a GET without it returns whatever applies to the caller. GET /tables/{tableId}/record-layout/targets lists which audiences already have a layout and which groups can be given one.

Record history

Two separate timelines live at the bottom of the record page, with different permissions on purpose.

Change history (audit data — `audit:read`)

GET /tables/{tableId}/items/{itemId}/history is the audit trail for one record, newest first: who changed it, when, and each change’s before/after values with the changed fields listed. Expanding an entry shows the per-field old → new values.

It is row-scoped and field-masked to you: you can only fetch history for a record you can see, and the before/after values are stripped of fields you may not read. A change that touched only fields you cannot see still appears — as an entry with no listed fields — so the timeline never silently loses events.
The actor can be a user, an API token, or the system.
It is gated on audit:read rather than records:read deliberately: who may see a record’s history stays a separately grantable decision from who may see the record. All built-in roles hold audit:read by default.

The workspace-wide audit log is a different, admin-oriented surface — see Audit.

Stage timeline (product data — `records:read`)

If the table has a pipeline (stage fields — see Lifecycles), GET /tables/{tableId}/items/{itemId}/stage-history shows every stage move, newest first: from → to, who moved it, through which surface (the app, an import), and how long the record sat in the previous stage. Records that have reached an end state (e.g. Won/Lost) also show a cycle time — creation to first end state.

This is deliberately not audit data: how long a deal sat in each stage is something anyone who can see the deal should see, so it needs only records:read. History starts when the stage field was designated — an empty timeline on an old record means “not recorded”, not “never moved”.

Comments

Tables can carry a Discussion thread on every record. It’s off by default — an admin opts a table in with the Discussion on records switch in the table’s settings dialog, where conversation actually belongs (a comment box on a junction table is clutter). The toggle is enforced server-side; switching it off later hides existing comments but does not delete them.

Who can comment. Posting, and editing/deleting your own comments, requires comments:create — held by Members and Admins. Readers hold comments:read only: they see the thread but the composer doesn’t appear. A workspace that wants commenting readers grants comments:create through a custom role.

Who sees a comment. Comments have no visibility rules of their own — they inherit the record’s, entirely. If you can see the record, you can read its whole thread (GET /tables/{tableId}/items/{itemId}/comments, oldest first); if you can’t, the thread doesn’t exist for you. Notably, commenting requires only read access to the record: a person who may see a deal but not change it is exactly who a discussion exists for.

Mentions. Type @ in the composer to pick a workspace member. Mentions are stored as id tokens, so they survive renames, and the mentioned person gets an in-app notification (“Ana mentioned you”) that deep-links to the comment — see Notifications. Mention notifications are in-app only (no email).

Editing and deleting. The rules are strict and deliberate:

Only the author can edit a comment — PATCH /tables/{tableId}/items/{itemId}/comments/{commentId} is author-only, with no moderator override at any permission level, so a comment’s attribution always means what it says. Edits are never silent: an “(edited)” marker appears.
Deleting (DELETE /tables/{tableId}/items/{itemId}/comments/{commentId}) is allowed for the author, or for anyone holding comments:moderate (admins). Deletion tombstones: the thread keeps its shape, but the text is genuinely removed from the database — the placeholder says whether the author or an administrator removed it. Moderator deletions are recorded in the audit log.

Comments are plain text with a small markdown subset, up to 8,000 characters. Threads update live for everyone viewing the record. A departed member’s comments remain, attributed to an unknown user.

Attachments

An attachment field holds one file per record. On the record page:

Upload by picking a file (on phones, image fields also offer the camera). While the record doesn’t exist yet, the file is uploaded to a staging area and bound to the record when you save — so you can create a record with its attachment in one go.
Limits are per field, set by whoever designed the schema: a maximum file size (default 10 MB) and optionally an allowed-type list (e.g. images only, or PDFs). Violations are rejected in the picker with a clear message. Large files upload in chunks automatically; you don’t need to do anything differently.
Images show an inline thumbnail; clicking expands to a larger preview.
Download saves the original file with its original name.
Replace or delete from the field’s controls (uploading a new file replaces the old one).

Downloading requires attachments:read (all roles); uploading and deleting require attachments:manage (Members and Admins) plus the corresponding record access. Download links are short-lived signed URLs minted per request — there is no permanent public URL to an attachment.

Share (on the record page) grants one user or one group access to that one record — the per-record exception lever in the visibility model. The dialog lists existing shares and lets you add or remove them.

What a share is, precisely:

It grants view or edit on exactly one record — never the table, never other records, and it doesn’t grant actions: someone shared an “edit” record still needs records:update in some role to actually save changes (share level and actions are checked independently).
It is additive: it can only widen access, never narrow it. Shares matter on private-visibility tables, where they punch a hole in the row filter; on a workspace-visibility table everyone with record read already sees everything, so a share changes nothing (it’s allowed, just redundant).
No expiry. A share lasts until someone removes it. Removal takes effect immediately — the next request the person makes no longer sees the record, and open apps are told to refresh.

Who can share: creating (POST /tables/{tableId}/items/{itemId}/shares) and revoking (DELETE /tables/{tableId}/items/{itemId}/shares/{shareId}) require update access to that record — the records:update action and the record within your update scope. Anyone who can edit the record can share it or remove any share on it; viewing the share list needs only read access. Group shares reach everyone in the group, tracking its membership as it changes.

Live updates and presence

The app holds one live connection per tab, and record surfaces use it:

Lists, boards and record pages update in place when someone else creates, edits or deletes a record you can see — no refresh needed. Events are permission-filtered server-side: a change to a record outside your visibility is never delivered to your browser.
Discussion threads update live as comments arrive.
Field presence: while a colleague is editing a field on the record you have open, a small named badge appears on that field’s corner — a nudge that helps you avoid the edit-conflict message before it happens. It is purely informational (nothing is locked), it only shows people the record is visible to, and it fades out by itself if the other editor disappears. A workspace admin can switch presence indicators off under Workspace Settings → Appearance → Collaboration.

Expanded relations over the API. GET /tables/{tableId}/items/{itemId}/expanded returns a record with every reference field replaced by the full referenced record, recursively up to 5 levels (circular references are broken automatically). This is API-only — the record page resolves references itself — and is useful for integrations that want one round trip. See API access.
Finding records — the ⌘K palette: Search.
Bulk creation — Importing data.
Alternative surfaces (boards, sheets, saved views) — Views.

FAQ

Q: Two of us opened the same record and see different fields. Bug?

No — field visibility. Private fields are masked per viewer (and admins see everything). Same for history entries and search results: everything on the record surface is filtered to the viewer. See Authorization & Permissions.

Q: There’s no comment box on my records.

In order of likelihood: the table’s Discussion on records switch is off (an admin can enable it in the table’s settings); your role is Reader, which can read but not post (comments:create is needed to write); or the whole section is missing because your role lacks comments:read.

Q: I edited my comment — can anyone tell?

Yes: an “(edited)” marker appears, permanently. The previous text is retrievable by admins through the audit log. There is no silent edit, and nobody — however privileged — can rewrite someone else’s comment.

Q: Saving failed with “changed by someone else”.

Someone (or something — an import, an integration) wrote to the record between your load and your save. Nothing you did was lost from the screen and nothing of theirs was overwritten: reload to see the latest values, then re-apply your edits. The presence badges exist to make this rare.

Q: I shared a record with “edit” but my colleague can’t save changes.

A share widens row visibility, not capability. Your colleague also needs the records:update action from some role — a Reader with an edit share can open the record but still cannot save. Ask an admin to grant the action (a custom role works well for this).

Q: Why does the share dialog let me share records on a table where everyone sees everything?

Shares are harmless there — they only matter once the table’s record visibility is Private. If the table later goes private, existing shares take effect.

Q: Where’s the record’s recycle bin?

There isn’t one per record. Deletion is immediate; the final values are preserved in the change history and audit log, and organization admins can restore whole-workspace backups. If accidental deletion worries you, narrow who holds records:delete (or narrow its record scope) rather than relying on recovery.

Open the app