Mattering Automations Grist integration
Connect Grist to Mattering Automations: sites, workspaces and documents, the tables, columns and records inside them, access at all three levels, snapshot listing and a read-only SQL node as workflow steps, authenticated with one API key and the Grist site host it belongs to.
The Mattering Automations Grist integration puts Grist's REST API on your automation canvas: list sites and workspaces, create documents, add and update tables and columns, read and write rows, manage who can see what at site, workspace and document level, list the automatic snapshots a document has, and run read-only SQL against the document itself.
The credential is a Grist API key created on the Developer page of your account settings, sent as an Authorization Bearer header, plus one non-secret field that most integrations do not need: the Grist site host. Grist runs a personal site at docs.getgrist.com, a subdomain per team site, and any number of self-hosted grist-core or Grist Enterprise installs, and an API key belongs to exactly one of them. So the host lives on the credential and one connection addresses one Grist site. Setup takes a few minutes, and this guide walks each step and ends with the full node reference.
Two things are worth knowing before you build, because both are easier to read here than to discover later. Records go through Grist's row-oriented /records API rather than the parallel column-oriented /data one, so a row arrives as one self-contained object with an id and a fields map, which is the shape a loop, a template reference or a database row wants. And Grist does not paginate: record reads take a limit with no cursor and no offset, so a large table is walked with Grist: Run SQL Query using LIMIT and OFFSET rather than by following a cursor field that does not exist.
Before you start
- A Grist account you can create an API key in, on a personal site, a team site, or a self-hosted install. Grist is open source, grist-core is published under the Apache 2.0 licence, and the same nodes work against your own domain.
- The site host that key belongs to, over https. A key minted on one Grist deployment does not work against another, so a personal-site key will not reach a team site's documents and the other way round.
- Awareness of what the key can reach. Grist states that an API key is owned by a single user and has the same permissions as that user, and there are no scopes on an API key, so the credential can do anything its owner can do. Consider creating it under an account whose access matches what you intend to automate.
- A sense of your plan's quotas, because none of the nodes are plan-gated but several of Grist's limits are. The free tier caps a document at 5,000 rows, free team sites are capped at 10 members and go read-only until they are back under the limit, and snapshot retention is 30 days on Free against 3 years on Pro and 5 years on Business, which is what the recovery advice in this guide is worth on your plan. Grist meters API calls on the free tier at 3,000 calls per month, shared across every document on the site, and free plans may additionally be rate limited to 5 requests per second per document. Pro and Business raise the allowance to 40,000 and 60,000 calls per document per day. Grist counts MCP tool calls against the same allowance as REST calls.
- A Mattering workspace with access to the Automations app.
- Not required and not stored here: a document id, a workspace id or an organisation id. Those are picked per node from the listers, and the org-scoped nodes accept Grist's own literal value current, which means the site the credential's host addresses.
Create a Grist API key
Grist authenticates every request with an API key sent as an Authorization Bearer header. There are no scopes to compose: the key carries its owner's permissions, whatever those are. The one extra decision is which Grist site this credential is for, because the host travels with the key.
Connect Grist to Mattering
Verify it works
Open any automation canvas and check the palette for a Grist section. Drop Grist: List Sites onto the canvas and run a test step. It takes no configuration at all, and it returns every organisation the key can reach, each team site plus the personal area, as a bare array, so paths read data[].id and data[].name. If the sites listed are not the ones you expected, the key belongs to a different Grist account or a different deployment than you meant.
Now walk one level down. Drop Grist: List Workspaces onto the canvas and leave the site as current, which is Grist's own way of saying the site this connection's host addresses. One call returns every workspace WITH the documents inside it, so you get workspace ids at data[].id and document ids at data[].docs[].id in a single read. This is the tree the rest of the integration hangs off.
Finish with a read against real data. Drop Grist: List Tables onto the canvas, choose a document from the Document picker, and set Expand to column so the response carries each table's full column metadata as well. Then run Grist: List Records against one of those tables. Everything in this path is read-only, so it cannot reach any of the five destructive nodes and is safe to re-run whenever you rotate the key.
Node reference
35 nodes, generated from the connector itself so this reference always matches what ships.
Read and query nodes 14
Grist: Get Document
grist_get_doc
Describe a document's metadata: name, pinned state, this key's access level, and the workspace and site it lives in. Contents are read with Grist: List Records or Grist: Run SQL Query.
Grist: Get Site
grist_get_site
Describe one organisation (team site or personal area): its name, subdomain, owner, this key's access level, and timestamps.
Grist: Get Site Usage
grist_get_site_usage
Usage summary across every non-deleted document in the site: how many documents are approaching, in a grace period for, or past their data limit, plus total attachment bytes. Grist documents this as accessible to site OWNERS only, so a key with editor access gets a 403 here while every other read still works. Useful as a scheduled quota alarm.
Grist: Get Workspace
grist_get_workspace
Describe one workspace: its name, this key's access level, the documents it contains, and the organisation it belongs to.
Grist: List Columns
grist_list_columns
List a table's columns with their ids, labels, types, formulas and widget options. Grist schemas are defined by the user, so this is how an automation discovers what it is allowed to write before it writes it.
Grist: List Document Access
grist_list_doc_access
List everyone with access to a document, showing their direct role, the role inherited from the workspace, and maxInheritedRole.
Grist: List Records
grist_list_records
Read rows from a table, one self-contained object per record: {"id": 1, "fields": {...}}. Supports exact value filtering, multi-column sorting and a row limit. There is no cursor and no offset - Grist does not paginate this endpoint - so for large tables either raise the limit or use Grist: Run SQL Query with LIMIT and OFFSET. Records with formula errors carry an extra 'errors' object naming the failing columns. Grist rejects requests with HTTP 429 once ten authorized requests are in flight for one document (all plans). Free plans are metered at 3,000 API calls per month shared across every document on the site, and may additionally be rate limited to 5 requests per second per document; Pro and Business raise the allowance to 40,000 and 60,000 calls per document per day. Grist counts MCP tool calls against the same allowance as REST calls.
Grist: List Site Access
grist_list_site_access
List everyone with access to the site, with their id, name, email and role (owners / editors / viewers).
Grist: List Sites
grist_list_orgs
List every organisation the API key can reach: each team site plus the personal area. This is where the site ids and subdomains used by the org-scoped nodes come from, and it is the call Grist's own documentation uses to check an API key works. The response is a bare array, so downstream references read data[].id and data[].name.
Grist: List Snapshots
grist_list_snapshots
List the automatic backups Grist has kept of a document, most recent first, each with a snapshotId, a lastModified timestamp and a docId that opens that version. This is the recovery surface behind every destructive node in this connector: it tells an automation which restore points exist. Restoring one is a whole-document rollback and is done in the Grist UI, not through this API.
Grist: List Tables
grist_list_tables
List the tables in a document. Table ids are what every record and column node needs. Set expand to 'column' to get each table's full column metadata in the same call, which is the cheapest way to learn a user-defined schema before writing to it. Documents are limited to 500 tables.
Grist: List Workspace Access
grist_list_workspace_access
List everyone with access to a workspace, showing both their direct role and the role they inherit from the site, plus maxInheritedRole - the ceiling on what site membership alone grants here.
Grist: List Workspaces
grist_list_workspaces
List every workspace in a site WITH the documents inside each one, in a single call. This is the tree the rest of the connector hangs off: workspace ids come from data[].id and document ids from data[].docs[].id. The response is a bare array. Pass 'current' as the site to mean the site this connection's host addresses.
Grist: Run SQL Query
grist_run_sql
Run a read-only SQL SELECT against a document. Every Grist document is a SQLite database, and this runs the query against it directly with defensive measures: a single SELECT statement, no trailing semicolon, WITH clauses allowed, and anything that would modify the database rejected. This is the escape hatch for everything Grist: List Records cannot express - joins across tables, aggregates, ranges, LIKE matching, and LIMIT/OFFSET paging. Use args for parameters rather than string concatenation. The POST form is shipped rather than the GET form because only POST accepts parameters and a timeout.
Action nodes 21
Grist: Add Columns
grist_add_columns
Add columns to a table, including formula columns and references to other tables. Additive: existing columns are untouched.
Grist: Add Or Update Columns
grist_replace_columns
Upsert columns: each entry updates the column with that id, or creates it if it does not exist. Marked destructive for one reason - replaceall. With replaceall true, every column NOT listed in the body is REMOVED from the table, along with its data, so the node's blast radius is whatever the table happens to contain at that moment. It defaults to false, which makes the node a plain upsert. There is no per-row undo. The only recovery is a whole-document rollback to an automatic snapshot, done in the Grist UI, which also discards every other change made since that snapshot (snapshots are retained 30 days on Free, 3 years on Pro, 5 years on Business).
Grist: Add Or Update Records
grist_upsert_records
Upsert rows: each entry names a 'require' object that identifies an existing row by column values, and a 'fields' object of values to write. A match is updated, no match creates a row combining both objects. This is the idempotent write - the right node for a workflow that may retry. Columns not mentioned are left alone, so unlike some vendors' PUT this does not blank omitted fields. One hazard: allow_empty_require lets an empty 'require' match and update EVERY row in the table, which is off by default.
Grist: Add Records
grist_add_records
Add rows to a table. The response returns the new row ids so a later step can update or delete exactly what this step created. Not idempotent: running it twice adds the rows twice, so a retried workflow should either dedupe upstream or use Grist: Add Or Update Records instead. Request bodies are capped at 1MB, so large batches must be split.
Grist: Add Tables
grist_add_tables
Add one or more tables to a document, each with its columns. Additive: existing tables are untouched. Note this connector ships no delete-table node, so cleanup of a table created here is done in the Grist UI.
Grist: Create Document
grist_create_doc
Create an empty document in a workspace. The response body is the new document id as a bare string, so downstream steps reference data directly. Add structure afterwards with Grist: Add Tables, then rows with Grist: Add Records.
Grist: Create Workspace
grist_create_workspace
Create an empty workspace in a site. The response body is the new workspace id as a bare integer, so downstream steps reference data directly rather than a field of it.
Grist: Delete Column
grist_delete_column
Delete one column from a table, and with it every value that column held. There is no per-column undo and no column trash. There is no per-row undo. The only recovery is a whole-document rollback to an automatic snapshot, done in the Grist UI, which also discards every other change made since that snapshot (snapshots are retained 30 days on Free, 3 years on Pro, 5 years on Business). Formulas in other columns that referenced this one will start erroring.
Grist: Delete Records
grist_delete_records
Delete rows from a table by row id. There is no row-level trash and no undo endpoint. There is no per-row undo. The only recovery is a whole-document rollback to an automatic snapshot, done in the Grist UI, which also discards every other change made since that snapshot (snapshots are retained 30 days on Free, 3 years on Pro, 5 years on Business). The request body is a bare JSON array of row ids, which is unusual for this API - every other write wraps its payload in an object.
Grist: Modify Document Access
grist_modify_doc_access
Share a document with people by email, change their role, or remove them, and optionally lower the ceiling on what workspace membership inherits here. This is the node that turns a generated document into a shared one.
Grist: Modify Site Access
grist_modify_site_access
Grant, change or remove site-level access by email address. Reversible by sending the previous roles back, but note the one irreversible-in-practice case: setting the API key owner's own entry to null removes this connection's access, after which only another owner can restore it.
Grist: Modify Workspace Access
grist_modify_workspace_access
Grant, change or remove workspace access by email, and optionally lower the ceiling on what site membership inherits into this workspace. Reversible by sending the previous values back.
Grist: Move Document
grist_move_doc
Move a document into another workspace. Reversible by moving it back. Returns an empty body on success.
Grist: Remove Document
grist_remove_doc
Move a document to trash. Trashed items can be restored for 30 days, after which the trash purges automatically and the backups go with it. Restore it with Grist: Restore Document From Trash, which brings the snapshot history back with it. Setting permanent to true skips trash and deletes the document and every backup of it forever. This node is the connector's only document delete: Grist's separate hard-delete endpoint does exactly what permanent=true does here.
Grist: Remove Workspace
grist_remove_workspace
Move a workspace, and everything in it, to trash. Trashed items can be restored for 30 days, after which the trash purges automatically and the backups go with it. Setting permanent to true skips trash and deletes the workspace and its documents forever, snapshot history included. This node is the connector's only workspace delete: Grist's separate hard-delete endpoint does exactly what permanent=true does here.
Grist: Rename Workspace
grist_modify_workspace
Rename a workspace. Name is the only property Grist documents as modifiable here; documents are moved with Grist: Move Document rather than by editing the workspace.
Grist: Restore Document From Trash
grist_unremove_doc
Restore a document that was moved to trash, together with its snapshot history. Only works while the document is still in trash - after 30 days it is purged and this returns an error.
Grist: Update Columns
grist_modify_columns
Update existing columns: change a label, type, formula or widget options, or rename a column by setting colId. Partial - properties you do not send are left alone. Changing a column's type can convert its stored values, so the previous values are only recoverable by a whole-document snapshot rollback.
Grist: Update Document
grist_modify_doc
Update a document's metadata - its name and whether it is pinned. This never touches the document's contents; rows and columns are changed with the record and column nodes.
Grist: Update Records
grist_modify_records
Update existing rows by id. Partial: only the columns you send change, and columns you omit keep their values, so this cannot silently blank a field. Idempotent - sending the same update twice leaves the same result.
Grist: Update Tables
grist_modify_tables
Update table metadata: rename a table by setting a new tableId, or switch on-demand loading on and off. Renaming changes the id every other node addresses the table by, so re-point any saved configuration afterwards.
Using the integration
On the automation canvas
Grist nodes chain with every other node. A form submission or a webhook can land a row with Grist: Add Records, a nightly schedule can reconcile a whole table with Grist: Add Or Update Records, and Grist: Run SQL Query can produce the aggregate a report step needs. The id fields are pickers rather than free text wherever a lister exists: sites come from Grist: List Sites, workspaces and documents from Grist: List Workspaces, tables from Grist: List Tables and columns from Grist: List Columns, so you choose names and the ids are filled in for you.
From AI assistants over MCP
Every node speaks MCP, the open protocol for connecting AI assistants to tools, so Claude, ChatGPT, and Matter, the assistant built into the platform, can drive the same surface. The pattern that works for an agent is discovery then write: Grist: List Columns to learn the real column ids and types, Grist: List Records or Grist: Run SQL Query to read, and Grist: Add Or Update Records to write back. The read nodes plus the upsert are the comfortable surface to hand an agent. Keep the five destructive nodes behind a condition or an approval task, and keep the access nodes out of reach too, because Grist: Modify Site Access can remove this connection's own access. Running the nodes here rather than as a local tool also means they work on a schedule with nobody present, chain with every other connector in one workflow, and hold the key in the workspace credential store rather than in one person's client config. Grist also hosts an official MCP server of its own at docs.getgrist.com/api/mcp, documented as available to all users at no extra cost across all plans, and a self-hosted Grist can enable the same on its own host. That one is the right choice for an assistant working with a document interactively; this integration is the unattended side. Note that Grist counts MCP tool calls against the same API allowance as REST calls either way.
One credential, one Grist site
The host is part of the credential because a Grist API key is minted on one deployment and is meaningless on another, exactly as a sandbox token is not a live token. That gives a clean rule: one connection addresses one Grist site, and a user with two team sites creates two connections and selects the right one on the node. Inside a site, nothing else needs an address. Document ids are globally unique, and the org-scoped nodes accept Grist's documented literal current, which means the site the host already fixed. If the Test Connection message names sites you do not recognise, the host and the key disagree about which deployment you are on.
Writing rows without surprises
Three write nodes, and picking the right one prevents most trouble. Grist: Add Records appends and returns the new row ids, so a later step can update exactly what it created, but it is not idempotent: run it twice and the rows exist twice. Grist: Update Records is partial by id, so columns you omit keep their values and it cannot silently blank a field. Grist: Add Or Update Records is the idempotent one and the right default for anything that might retry: each entry names a require object identifying a row by column values and a fields object of values to write, a match updates and no match creates. One hazard is on that node deliberately: allow_empty_require lets an empty require match and update every row in the table, and it is off by default. Request bodies are capped at 1MB, so large batches are split rather than sent whole.
Reading, filtering and the SQL escape hatch
Grist: List Records supports exact value filtering, multi-column sorting and a row limit. Read the filter for what it is: exact membership matching only, with no operators, no ranges and no text search. Anything more expressive belongs in Grist: Run SQL Query, which runs a single read-only SELECT straight against the document, since every Grist document is a SQLite database underneath. WITH clauses are allowed, a trailing semicolon is not, parameters go in args rather than into the string, and anything that would modify the database is rejected. It is also how you page, because Grist does not: there is no cursor and no offset on any read, so LIMIT and OFFSET in SQL is the mechanism. One more field worth understanding before you map a response: cellFormat set to typed changes the shape of every cell, turning dates into a tagged pair and references into a tagged triple, so a downstream mapping written against one setting breaks against the other.
Discovering a schema you did not design
Grist schemas are defined by the user, which makes discovery a real step rather than a nicety. Grist: List Tables with expand set to column is the cheapest way to learn a whole document's structure, and Grist: List Columns gives one table's ids, labels, types, formulas and widget options. Two details that catch people. A column's type string carries its postfix, so a reference is Ref:Orders and a datetime is DateTime with a timezone, and a bare Ref is not a valid type. And renaming is an id change: Grist: Update Tables with a new tableId, or Grist: Update Columns with a new colId, changes the identifier every other node addresses the thing by, and saved node configuration does not follow. Re-point your nodes after a rename.
Sharing, access and the one irreversible sharp edge
Grist: Modify Site Access, Grist: Modify Workspace Access and Grist: Modify Document Access grant, change or remove access by email address, and the workspace and document ones can also lower maxInheritedRole, the ceiling on what membership at the level above grants here. Removing someone means sending a JSON null for their entry rather than an empty string. These are reversible by sending the previous roles back, with one exception that is not: setting the API key owner's own entry to null removes this connection's access, after which only another owner can restore it. The matching read nodes (Grist: List Site Access, Grist: List Workspace Access, Grist: List Document Access) are safe to run on a schedule as an access review.
The five destructive nodes, and what recovery really costs
Grist: Remove Document and Grist: Remove Workspace move things to trash, which Grist keeps for 30 days and then purges automatically, taking the backups with it, so the automatic purge is itself a point of no return. Grist: Restore Document From Trash brings a document back with its snapshot history while it is still in trash. Setting permanent to true on either removal skips trash entirely and deletes the backups with it. Grist: Delete Records and Grist: Delete Column are the ones to read carefully: there is no row trash, no column trash and no undo endpoint, so there is no per-item recovery at all. The data does survive in an automatic document snapshot, and Grist: List Snapshots reports which restore points exist, but restoring one is a whole-document rollback done in the Grist UI that discards every other change made since. Retention is 30 days on Free, 3 years on Pro and 5 years on Business. Grist: Add Or Update Columns is flagged for one setting: with replaceall true, every column not listed in the body is removed along with its data. It defaults to false, which makes the node a plain upsert. Gate all five behind a condition or an approval step, and run Grist: List Snapshots before a bulk rewrite so the run at least records what existed.
Troubleshooting
Test Connection fails with a 401 or 403
Test Connection fails with a 404, or nodes report no Grist API at that host
Test Connection passes, but every node returns an empty list
A busy workflow starts getting 429 responses
Grist: Get Site Usage returns 403 while every other read works
A record filter returns nothing even though matching rows exist
Nodes that worked yesterday now fail on an unknown table or column
A large batch write fails or is rejected
A deleted row needs to come back
Restore Document From Trash returns an error
Related
The Grist MCP
What connecting Grist unlocks for AI agents and automations, with common uses and FAQs.
More guides
All Automations documentation
Every integration guide, plus how connectors, credentials, and workflows fit together.
Grist is a trademark of its respective owner. Mattering uses platform names to identify the services these integrations connect to; no endorsement or affiliation is implied.