Connect AI agents to Grist

Scalekit connector

The Grist connector lets your AI agent act in each user's Grist account. Each user connects their own Grist access token once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 48 tools.

Tools: 48
What they doRead · write · destructive: 20 · 24 · 420 read24 write4 destructive
Users sign in with: Access token

Setup

Install the SDK
- Node.js
- Python
Terminal window
npm install @scalekit-sdk/node dotenv
Terminal window
pip install scalekit-sdk-python python-dotenv
Set your credentials
Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.
.env
```
SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
SCALEKIT_CLIENT_ID=<your-client-id>
SCALEKIT_CLIENT_SECRET=<your-client-secret>
```
Create the Grist connection
In AgentKit > Connections, create a Grist connection. The name you give it is the connection_name your code passes. See Configure connections.

Authorize a user and make your first call

Node.js
Python

1
import { ScalekitClient } from '@scalekit-sdk/node'
2
import 'dotenv/config'
3
import { createInterface } from 'node:readline/promises'
4

5
const scalekit = new ScalekitClient(
6
  process.env.SCALEKIT_ENVIRONMENT_URL,
7
  process.env.SCALEKIT_CLIENT_ID,
8
  process.env.SCALEKIT_CLIENT_SECRET,
9
)
10
const actions = scalekit.actions
11

12
const connector = 'grist'
13
const identifier = 'user_123'
14

15
// Generate an authorization link for the user
16
const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
17
console.log('Authorize Grist:', link)
18
const rl = createInterface({ input: process.stdin, output: process.stdout })
19
await rl.question('Press Enter after authorizing...')
20
rl.close()
21

22
// Make your first call
23
const result = await actions.executeTool({
24
  connector,
25
  identifier,
26
  toolName: 'grist_get_current_user',
27
  toolInput: {},
28
})
29
console.log(result)

npx tsx quickstart.mts

1
import os
2
from scalekit import ScalekitClient
3
from dotenv import load_dotenv
4
load_dotenv()
5

6
scalekit_client = ScalekitClient(
7
    env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),
8
    client_id=os.getenv("SCALEKIT_CLIENT_ID"),
9
    client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
10
)
11
actions = scalekit_client.actions
12

13
connection_name = "grist"
14
identifier = "user_123"
15

16
# Generate an authorization link for the user
17
link_response = actions.get_authorization_link(
18
    connection_name=connection_name,
19
    identifier=identifier,
20
)
21
print("Authorize Grist:", link_response.link)
22
input("Press Enter after authorizing...")
23

24
# Make your first call
25
result = actions.execute_tool(
26
    tool_input={},
27
    tool_name="grist_get_current_user",
28
    connection_name=connection_name,
29
    identifier=identifier,
30
)
31
print(result)

python quickstart.py

Each user opens the link once and enters their Grist credentials there. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool

Try in Playground Request a tool

grist_compare_docsCompare a document with another document, for example a fork against its original.Read-only
Compare Documents
Compare a document with another document, for example a fork against its original. Returns the left and right states, their common parent, and a summary of changes. Use fork_doc to create a fork to compare.
Inputs
doc_idstringrequired
ID of the Grist document (a UUID-style string, also shown as the document's id in its URL or from Grist list workspaces results).
doc_id2stringrequired
ID of the second document to compare against.
detailboolean
Set to true to include detailed change information. Leave empty for a summary only.
max_rowsinteger
Maximum number of row changes to include in the detail. Leave empty for the server default.
grist_get_attachment_metadataGet the metadata of one attachment.Read-only
Get Attachment Metadata
Get the metadata of one attachment. Returns fileName, fileSize, and timeUploaded. Use list_attachments to find attachment IDs.
Inputs
attachment_idintegerrequired
Numeric ID of the attachment.
doc_idstringrequired
ID of the Grist document (a UUID-style string, also shown as the document's id in its URL or from Grist list workspaces results).
grist_get_current_userGet the profile of the user the API key belongs to.Read-only
Get Current User
Get the profile of the user the API key belongs to. Returns the user's id, name, and picture. Use list_orgs to see what the user can access.
Inputs
This tool takes no inputs.
grist_get_docRetrieve a document's metadata: name, access level, pinned state, and its workspace.Read-only
Get Document
Retrieve a document's metadata: name, access level, pinned state, and its workspace. Returns id, name, access, isPinned, urlId, and the containing workspace and org. Use list_tables to see the document's contents.
Inputs
doc_idstringrequired
ID of the Grist document (a UUID-style string, also shown as the document's id in its URL or from Grist list workspaces results).
grist_get_doc_statesGet a document's action history as a list of states, most recent first.Read-only
Get Document States
Get a document's action history as a list of states, most recent first. Returns a states array with a sequential number n and a hash h for each state. Use list_doc_snapshots for backups.
Inputs
doc_idstringrequired
ID of the Grist document (a UUID-style string, also shown as the document's id in its URL or from Grist list workspaces results).
grist_get_orgRetrieve one organization (team site or personal area) by ID or subdomain.Read-only
Get Org
Retrieve one organization (team site or personal area) by ID or subdomain. Returns the org's id, name, domain, owner, access level, and created and updated timestamps. Use list_orgs to discover orgs. Use list_workspaces to see what is inside one.
Inputs
org_idstringrequired
Organization (site) to use: its numeric ID, its subdomain such as acme, or the word current to use the site implied by the connected Grist host. Get IDs from the list orgs tool.
grist_get_org_usageGet usage statistics for all non-deleted documents in an organization.Read-only
Get Org Usage
Get usage statistics for all non-deleted documents in an organization. Returns document counts by data limit status and attachment storage totals. Only available to organization owners.
Inputs
org_idstringrequired
Organization (site) to use: its numeric ID, its subdomain such as acme, or the word current to use the site implied by the connected Grist host. Get IDs from the list orgs tool.
grist_get_table_schemaGet a table's schema in the Frictionless Data table-schema format.Read-only
Get Table Schema
Get a table's schema in the Frictionless Data table-schema format. Returns a schema object describing each field's name and type. Use list_columns for Grist-native column metadata instead.
Inputs
doc_idstringrequired
ID of the Grist document (a UUID-style string, also shown as the document's id in its URL or from Grist list workspaces results).
table_idstringrequired
Normalized name of the table, as shown as TABLE ID in Raw Data.
headerstring
Header format: colId for normalized column IDs or label for human-friendly labels. Leave empty for the server default.one of colIdlabel
grist_get_workspaceRetrieve one workspace and the documents inside it.Read-only
Get Workspace
Retrieve one workspace and the documents inside it. Returns the workspace id, name, access level, and a docs array with each document's id, name, pinned state, and access. Use list_workspaces to browse all workspaces in an org.
Inputs
workspace_idintegerrequired
Numeric ID of the workspace. Get it from the list workspaces tool.
grist_list_attachmentsList the metadata of attachments stored in a document.Read-only
List Attachments
List the metadata of attachments stored in a document. Returns a records array; each has an id and fields with fileName, fileSize, and timeUploaded. Use get_attachment_metadata for one attachment.
Inputs
doc_idstringrequired
ID of the Grist document (a UUID-style string, also shown as the document's id in its URL or from Grist list workspaces results).
filterstring
JSON object, as a string, mapping column names to arrays of allowed values. Example: {"pet": ["cat", "dog"]} returns only rows whose pet is cat or dog. Leave empty for no filtering.
limitinteger
Maximum number of rows to return. 0 means no limit. Leave empty for no limit.
sortstring
Comma-separated column names giving the sort order. Prefix a column with - for descending order, for example pet,-age. Leave empty for the default order.
grist_list_columnsList the columns of a table.Read-only
List Columns
List the columns of a table. Returns a columns array; each column has an id and a fields object with type, label, formula, isFormula, widgetOptions, and related settings. Use this before add_records or update_records to learn valid column IDs and types.
Inputs
doc_idstringrequired
ID of the Grist document (a UUID-style string, also shown as the document's id in its URL or from Grist list workspaces results).
table_idstringrequired
Table identifier: the normalized table name shown as TABLE ID in the document's Raw Data page (for example Table1), or its numeric row ID in _grist_Tables.
hiddenboolean
Set to true to include hidden columns such as manualSort. Leave empty to exclude them.
grist_list_doc_accessList the users who have access to a document.Read-only
List Document Access
List the users who have access to a document. Returns maxInheritedRole and a users array with id, name, email, and access level. Use update_doc_access to change who has access.
Inputs
doc_idstringrequired
ID of the Grist document (a UUID-style string, also shown as the document's id in its URL or from Grist list workspaces results).
grist_list_doc_snapshotsList automatic snapshots (backups) of a document, most recent first.Read-only
List Document Snapshots
List automatic snapshots (backups) of a document, most recent first. Returns a snapshots array with snapshotId, lastModified, and docId. Use get_doc_states for fine-grained action history.
Inputs
doc_idstringrequired
ID of the Grist document (a UUID-style string, also shown as the document's id in its URL or from Grist list workspaces results).
rawboolean
Set to true to include snapshots that are not in the snapshot inventory. Leave empty for the normal list.
grist_list_org_accessList the users who have access to an organization.Read-only
List Org Access
List the users who have access to an organization. Returns a users array with id, name, email, and access level. Use list_doc_access or list_workspace_access for narrower scopes.
Inputs
org_idstringrequired
Organization (site) to use: its numeric ID, its subdomain such as acme, or the word current to use the site implied by the connected Grist host. Get IDs from the list orgs tool.
grist_list_orgsList the organizations (team sites and personal areas) the connected user can access.Read-only
List Orgs
List the organizations (team sites and personal areas) the connected user can access. Returns an array of orgs with id, name, domain, owner, access level, and created and updated timestamps. Use this first to find an org ID, then list_workspaces to browse its documents. Use get_org for one org.
Inputs
This tool takes no inputs.
grist_list_recordsFetch records (rows) from a table, optionally filtered, sorted, and limited.Read-only
List Records
Fetch records (rows) from a table, optionally filtered, sorted, and limited. Returns a records array; each record has an id and a fields object mapping column names to cell values. Use run_sql_query for joins or aggregates. Use list_columns to see the column names first.
Inputs
doc_idstringrequired
ID of the Grist document (a UUID-style string, also shown as the document's id in its URL or from Grist list workspaces results).
table_idstringrequired
Table identifier: the normalized table name shown as TABLE ID in the document's Raw Data page (for example Table1), or its numeric row ID in _grist_Tables.
cell_formatstring
Cell value format: normal (default) or typed, which returns self-describing typed values such as dates as ["d", timestamp]. Leave empty for normal.one of normaltyped
filterstring
JSON object, as a string, mapping column names to arrays of allowed values. Example: {"pet": ["cat", "dog"]} returns only rows whose pet is cat or dog. Leave empty for no filtering.
hiddenboolean
Set to true to include hidden columns such as manualSort. Leave empty to exclude them.
limitinteger
Maximum number of rows to return. 0 means no limit. Leave empty for no limit.
sortstring
Comma-separated column names giving the sort order. Prefix a column with - for descending order, for example pet,-age. Leave empty for the default order.
grist_list_tablesList the tables in a document.Read-only
List Tables
List the tables in a document. Returns a tables array with each table's id and fields; with expand set to column, each table also includes its column metadata. Use list_columns for a single table's columns. Use list_records to read rows.
Inputs
doc_idstringrequired
ID of the Grist document (a UUID-style string, also shown as the document's id in its URL or from Grist list workspaces results).
expandstring
Set to column to include column metadata for each table. Leave empty to omit it.one of column
grist_list_workspace_accessList the users who have access to a workspace.Read-only
List Workspace Access
List the users who have access to a workspace. Returns maxInheritedRole and a users array with id, name, email, and access level. Use update_workspace_access to change who has access.
Inputs
workspace_idintegerrequired
Numeric ID of the workspace. Get it from the list workspaces tool.
grist_list_workspacesList the workspaces in an organization, including the documents inside each workspace.Read-only
List Workspaces
List the workspaces in an organization, including the documents inside each workspace. Returns an array of workspaces, each with id, name, access level, and a docs array of document id, name, pinned state, and access. Use this to find document IDs for the table and record tools. Use get_workspace for a single workspace. Requires an org ID from list_orgs, or the value current.
Inputs
org_idstringrequired
Organization (site) to use: its numeric ID, its subdomain such as acme, or the word current to use the site implied by the connected Grist host. Get IDs from the list orgs tool.
grist_run_sql_queryRun a read-only SQL SELECT query against a document's SQLite database.Read-only
Run SQL Query
Run a read-only SQL SELECT query against a document's SQLite database. Returns the statement and a records array; each record has a fields object of column values. Use list_records for simple reads. Use this for joins, aggregates, and WITH clauses. Table names are the table IDs from list_tables.
Inputs
doc_idstringrequired
ID of the Grist document (a UUID-style string, also shown as the document's id in its URL or from Grist list workspaces results).
sqlstringrequired
A single SELECT statement with no trailing semicolon. WITH clauses are allowed; statements that modify data are not. Use ? placeholders together with args for values. Example: SELECT Name, Age FROM People WHERE Age > ?.
argsarray
Values for the ? placeholders in sql, in order. Each is a number or string. Example: [30]. Leave empty if the query has no placeholders.
timeoutnumber
Query timeout in milliseconds. Defaults to the server setting (1000) and can only be lowered, not raised. Leave empty for the default.
grist_add_columnsAdd one or more columns to an existing table.Write
Add Columns
Add one or more columns to an existing table. Returns a columns array with the id of each column created. Use update_columns to change existing columns. Use create_tables to make a whole new table.
Inputs
columnsarrayrequired
Columns to add. Each item is an object with an id (the column name) and an optional fields object such as type (Any, Text, Numeric, Int, Bool, Date, DateTime:<timezone>, Choice, ChoiceList, Ref:<tableId>, RefList:<tableId>, Attachments), label, formula, isFormula, and widgetOptions (a JSON string). Example: [{"id": "Email", "fields": {"type": "Text", "label": "Email"}}].
doc_idstringrequired
ID of the Grist document (a UUID-style string, also shown as the document's id in its URL or from Grist list workspaces results).
table_idstringrequired
Table identifier: the normalized table name shown as TABLE ID in the document's Raw Data page (for example Table1), or its numeric row ID in _grist_Tables.
grist_add_recordsAdd one or more records (rows) to a table.Write
Add Records
Add one or more records (rows) to a table. Returns a records array with the id of each new record, in the order given. Use update_records to change existing rows. Use upsert_records to add or update by matching values.
Inputs
doc_idstringrequired
ID of the Grist document (a UUID-style string, also shown as the document's id in its URL or from Grist list workspaces results).
recordsarrayrequired
Records to add. Each item is an object with a fields object mapping column names to values. Example: [{"fields": {"Name": "Ada", "Age": 36}}].
table_idstringrequired
Table identifier: the normalized table name shown as TABLE ID in the document's Raw Data page (for example Table1), or its numeric row ID in _grist_Tables.
noparseboolean
Set to true to store string values exactly as given instead of parsing them according to the column type (for example dates will not be converted). Leave empty to use Grist's default parsing.
grist_apply_user_actionsApply a batch of low-level Grist user actions to a document in one transaction.Write
Apply User Actions
Apply a batch of low-level Grist user actions to a document in one transaction. Returns actionNum (the action number assigned) and retValues (return values such as new row IDs). Use this only for operations the other tools cannot express, such as BulkAddRecord, AddTable, or RenameColumn. Prefer add_records, update_records, and delete_records for row changes.
Inputs
actionsarrayrequired
List of user actions. Each action is an array whose first item is the action name, for example ["AddRecord", "Table1", null, {"Name": "Ada"}], ["UpdateRecord", "Table1", 3, {"Name": "Ada L"}], or ["RemoveRecord", "Table1", 3].
doc_idstringrequired
ID of the Grist document (a UUID-style string, also shown as the document's id in its URL or from Grist list workspaces results).
noparseboolean
Set to true to store string values exactly as given instead of parsing them according to the column type. Leave empty for default parsing.
grist_copy_docCopy a document into a workspace.Write
Copy Document
Copy a document into a workspace. Returns the string ID of the new document. Set as_template to copy only the structure without data or history. Use fork_doc for a personal fork that tracks the original.
Inputs
doc_idstringrequired
ID of the Grist document (a UUID-style string, also shown as the document's id in its URL or from Grist list workspaces results).
document_namestringrequired
Name for the copied document.
workspace_idintegerrequired
Numeric ID of the workspace to place the copy in.
as_templateboolean
Set to true to remove all data and history and keep only the structure. Leave empty for a full copy.
grist_create_docCreate an empty document in a workspace.Write
Create Document
Create an empty document in a workspace. Returns the string ID of the new document. Use copy_doc to duplicate an existing document instead. Use create_tables afterwards to add tables.
Inputs
workspace_idintegerrequired
Numeric ID of the workspace. Get it from the list workspaces tool.
is_pinnedboolean
Set to true to pin the document so it appears prominently in the workspace. Leave empty to leave it unpinned.
namestring
Name for the new document.
grist_create_tablesAdd one or more tables, with their columns, to a document.Write
Create Tables
Add one or more tables, with their columns, to a document. Returns a tables array with the id of each table created. Use add_columns to add columns to an existing table. Use add_records to fill a table with rows.
Inputs
doc_idstringrequired
ID of the Grist document (a UUID-style string, also shown as the document's id in its URL or from Grist list workspaces results).
tablesarrayrequired
Tables to create. Each item is an object with an optional id (the table name) and a columns array; each column has an id and an optional fields object (for example type, label, formula). Example: [{"id": "People", "columns": [{"id": "Name", "fields": {"type": "Text"}}, {"id": "Age", "fields": {"type": "Int"}}]}].
grist_create_workspaceCreate an empty workspace in an organization.Write
Create Workspace
Create an empty workspace in an organization. Returns the numeric ID of the new workspace. Use create_doc afterwards to add documents to it.
Inputs
namestringrequired
Name for the new workspace.
org_idstringrequired
Organization (site) to use: its numeric ID, its subdomain such as acme, or the word current to use the site implied by the connected Grist host. Get IDs from the list orgs tool.
grist_fork_docCreate a personal fork of a document that tracks its relationship to the original.Write
Fork Document
Create a personal fork of a document that tracks its relationship to the original. Returns forkId, docId, and urlId of the new fork. Use compare_docs to see the fork's changes against the original. Use copy_doc for an independent copy.
Inputs
doc_idstringrequired
ID of the Grist document (a UUID-style string, also shown as the document's id in its URL or from Grist list workspaces results).
grist_move_docMove a document to another workspace.Write
Move Document
Move a document to another workspace. Returns an empty success response. Use list_workspaces to find the target workspace ID.
- Idempotent
Inputs
doc_idstringrequired
ID of the Grist document (a UUID-style string, also shown as the document's id in its URL or from Grist list workspaces results).
workspace_idintegerrequired
Numeric ID of the workspace to move the document into.
grist_pin_docPin a document so it appears at the top of its workspace listing.Write
Pin Document
Pin a document so it appears at the top of its workspace listing. Returns an empty success response. Use unpin_doc to undo.
- Idempotent
Inputs
doc_idstringrequired
ID of the Grist document (a UUID-style string, also shown as the document's id in its URL or from Grist list workspaces results).
grist_restore_docRestore a document that was moved to the trash.Write
Restore Document
Restore a document that was moved to the trash. Returns an empty success response. Only works while the document is still in the trash.
- Idempotent
Inputs
doc_idstringrequired
ID of the Grist document (a UUID-style string, also shown as the document's id in its URL or from Grist list workspaces results).
grist_restore_workspaceRestore a workspace that was moved to the trash.Write
Restore Workspace
Restore a workspace that was moved to the trash. Returns an empty success response. Only works while the workspace is still in the trash.
- Idempotent
Inputs
workspace_idintegerrequired
Numeric ID of the workspace. Get it from the list workspaces tool.
grist_trash_docMove a document to the trash so it can be restored later.Write
Move Document to Trash
Move a document to the trash so it can be restored later. Returns an empty success response. Use restore_doc to undo. Use delete_doc for permanent deletion.
- Idempotent
Inputs
doc_idstringrequired
ID of the Grist document (a UUID-style string, also shown as the document's id in its URL or from Grist list workspaces results).
grist_trash_workspaceMove a workspace to the trash so it can be restored later.Write
Move Workspace to Trash
Move a workspace to the trash so it can be restored later. Returns an empty success response. Use restore_workspace to undo. Use delete_workspace for permanent deletion.
- Idempotent
Inputs
workspace_idintegerrequired
Numeric ID of the workspace. Get it from the list workspaces tool.
grist_unpin_docUnpin a previously pinned document.Write
Unpin Document
Unpin a previously pinned document. Returns an empty success response. Use pin_doc to pin it again.
- Idempotent
Inputs
doc_idstringrequired
ID of the Grist document (a UUID-style string, also shown as the document's id in its URL or from Grist list workspaces results).
grist_update_columnsModify existing columns of a table, such as their type, label, or formula.Write
Update Columns
Modify existing columns of a table, such as their type, label, or formula. Returns an empty success response. Use upsert_columns to add or update in one call. Use add_columns to add only.
- Idempotent
Inputs
columnsarrayrequired
Columns to change. Each item is an object with id (the column's current id) and fields, an object with the properties to set such as type, label, formula, isFormula, or widgetOptions. Example: [{"id": "Email", "fields": {"label": "Work Email"}}].
doc_idstringrequired
ID of the Grist document (a UUID-style string, also shown as the document's id in its URL or from Grist list workspaces results).
table_idstringrequired
Table identifier: the normalized table name shown as TABLE ID in the document's Raw Data page (for example Table1), or its numeric row ID in _grist_Tables.
grist_update_docRename a document or change its pinned state, without changing its contents.Write
Update Document
Rename a document or change its pinned state, without changing its contents. Returns an empty success response. Use pin_doc or unpin_doc when only the pinned state changes.
- Idempotent
Inputs
doc_idstringrequired
ID of the Grist document (a UUID-style string, also shown as the document's id in its URL or from Grist list workspaces results).
is_pinnedboolean
Set to true to pin the document or false to unpin it. Leave empty to keep the current state.
namestring
New name for the document. Leave empty to keep the current name.
grist_update_doc_accessChange who has access to a document and at what level.Write
Update Document Access
Change who has access to a document and at what level. Returns an empty success response. Use list_doc_access to see current access first.
- Idempotent
Inputs
deltaobjectrequired
Changes to make to a document's access, as an object with optional keys maxInheritedRole (one of owners, editors, viewers) and users (an object mapping a user email address to a role: owners, editors, viewers, or members; use null to remove that user's access). Example: {"users": {"ann@example.com": "editors", "bob@example.com": null}}.
doc_idstringrequired
ID of the Grist document (a UUID-style string, also shown as the document's id in its URL or from Grist list workspaces results).
grist_update_recordsUpdate existing records (rows) of a table by record id.Write
Update Records
Update existing records (rows) of a table by record id. Returns an empty success response. Use list_records to find record ids. Use upsert_records to match rows by column values instead of id.
- Idempotent
Inputs
doc_idstringrequired
ID of the Grist document (a UUID-style string, also shown as the document's id in its URL or from Grist list workspaces results).
recordsarrayrequired
Records to change. Each item is an object with id (the numeric record id) and fields (an object mapping column names to new values). Only the listed columns change. Example: [{"id": 1, "fields": {"Age": 37}}].
table_idstringrequired
Table identifier: the normalized table name shown as TABLE ID in the document's Raw Data page (for example Table1), or its numeric row ID in _grist_Tables.
noparseboolean
Set to true to store string values exactly as given instead of parsing them according to the column type (for example dates will not be converted). Leave empty to use Grist's default parsing.
grist_update_tablesRename tables or change their on-demand loading setting.Write
Update Tables
Rename tables or change their on-demand loading setting. Returns an empty success response. Use update_columns to change columns instead.
- Idempotent
Inputs
doc_idstringrequired
ID of the Grist document (a UUID-style string, also shown as the document's id in its URL or from Grist list workspaces results).
tablesarrayrequired
Tables to change. Each item is an object with id (the table's current id) and fields, an object with tableId (a new name to rename the table) and or onDemand (boolean). Example: [{"id": "Table1", "fields": {"tableId": "Customers"}}].
grist_update_workspaceRename a workspace.Write
Update Workspace
Rename a workspace. Returns an empty success response. Use get_workspace to confirm the change.
- Idempotent
Inputs
namestringrequired
New name for the workspace.
workspace_idintegerrequired
Numeric ID of the workspace. Get it from the list workspaces tool.
grist_update_workspace_accessChange who has access to a workspace and at what level.Write
Update Workspace Access
Change who has access to a workspace and at what level. Returns an empty success response. Use list_workspace_access to see current access first.
- Idempotent
Inputs
deltaobjectrequired
Changes to make to a workspace's access, as an object with optional keys maxInheritedRole (one of owners, editors, viewers) and users (an object mapping a user email address to a role: owners, editors, viewers, or members; use null to remove that user's access). Example: {"users": {"ann@example.com": "editors", "bob@example.com": null}}.
workspace_idintegerrequired
Numeric ID of the workspace. Get it from the list workspaces tool.
grist_upsert_columnsAdd columns that do not exist and update those that do, matching on column id.Write
Add or Update Columns
Add columns that do not exist and update those that do, matching on column id. Returns an empty success response. Columns not listed are left unchanged. Use add_columns or update_columns when you only need one of the two behaviors.
- Idempotent
Inputs
columnsarrayrequired
Columns to add or update. Each item is an object with id (the column id) and fields (properties such as type, label, formula). A column whose id already exists is updated, otherwise it is created. Example: [{"id": "Score", "fields": {"type": "Numeric"}}].
doc_idstringrequired
ID of the Grist document (a UUID-style string, also shown as the document's id in its URL or from Grist list workspaces results).
table_idstringrequired
Table identifier: the normalized table name shown as TABLE ID in the document's Raw Data page (for example Table1), or its numeric row ID in _grist_Tables.
noaddboolean
Set to true to prevent adding new columns, so only existing columns are updated. Leave empty to allow adding.
noupdateboolean
Set to true to prevent updating existing columns, so only new columns are added. Leave empty to allow updating.
grist_upsert_recordsAdd or update records by matching on column values, instead of by record id.Write
Add or Update Records
Add or update records by matching on column values, instead of by record id. Returns an empty success response. For each item, a row matching require is updated with fields; if none matches, a new row is created. Use add_records or update_records when you know you only need one of the two.
- Idempotent
Inputs
doc_idstringrequired
ID of the Grist document (a UUID-style string, also shown as the document's id in its URL or from Grist list workspaces results).
recordsarrayrequired
Records to add or update. Each item is an object with require (an object of column values used to find an existing row, or used to create a new one) and an optional fields object (values to set). Example: [{"require": {"Email": "ada@example.com"}, "fields": {"Age": 37}}].
table_idstringrequired
Table identifier: the normalized table name shown as TABLE ID in the document's Raw Data page (for example Table1), or its numeric row ID in _grist_Tables.
allow_empty_requireboolean
Set to true to allow an empty require object, which matches and updates every row in the table. Leave empty to reject empty require.
noaddboolean
Set to true to prevent adding new rows, so only matching rows are updated. Leave empty to allow adding.
noparseboolean
Set to true to store string values exactly as given instead of parsing them according to the column type (for example dates will not be converted). Leave empty to use Grist's default parsing.
noupdateboolean
Set to true to prevent updating rows, so only new rows are added. Leave empty to allow updating.
onmanystring
What to do when several rows match require: first updates only the first match, none updates nothing, all updates every match. Leave empty for first.one of firstnoneall
grist_delete_columnDelete a column from a table.Destructive
Delete Column
Delete a column from a table. This permanently removes the column and its data. Returns an empty success response. Use list_columns first to confirm the column id.
- Idempotent
Inputs
col_idstringrequired
Column identifier, without the leading $, as shown in the column configuration panel.
doc_idstringrequired
ID of the Grist document (a UUID-style string, also shown as the document's id in its URL or from Grist list workspaces results).
table_idstringrequired
Table identifier: the normalized table name shown as TABLE ID in the document's Raw Data page (for example Table1), or its numeric row ID in _grist_Tables.
grist_delete_docDelete a document permanently.Destructive
Delete Document
Delete a document permanently. Returns an empty success response. Use trash_doc instead for a recoverable removal.
- Idempotent
Inputs
doc_idstringrequired
ID of the Grist document (a UUID-style string, also shown as the document's id in its URL or from Grist list workspaces results).
grist_delete_recordsDelete records (rows) from a table by record id.Destructive
Delete Records
Delete records (rows) from a table by record id. This permanently removes the rows. Returns an empty success response. Use list_records first to find the record ids to delete.
Inputs
doc_idstringrequired
ID of the Grist document (a UUID-style string, also shown as the document's id in its URL or from Grist list workspaces results).
row_idsarrayrequired
Numeric IDs of the records to delete. Example: [1, 2, 3].
table_idstringrequired
Table identifier: the normalized table name shown as TABLE ID in the document's Raw Data page (for example Table1), or its numeric row ID in _grist_Tables.
grist_delete_workspaceDelete a workspace and all documents in it.Destructive
Delete Workspace
Delete a workspace and all documents in it. Returns an empty success response. Use trash_workspace instead for a recoverable removal.
- Idempotent
Inputs
workspace_idintegerrequired
Numeric ID of the workspace. Get it from the list workspaces tool.

Setup

Install the SDK

Set your credentials

Create the Grist connection

Authorize a user and make your first call

Tools

Call it

Returns

Compare Documents

Inputs

Get Attachment Metadata

Inputs

Get Current User

Inputs

Get Document

Inputs

Get Document States

Inputs

Get Org

Inputs

Get Org Usage

Inputs

Get Table Schema

Inputs

Get Workspace

Inputs

List Attachments

Inputs

List Columns

Inputs

List Document Access

Inputs

List Document Snapshots

Inputs

List Org Access

Inputs

List Orgs

Inputs

List Records

Inputs

List Tables

Inputs

List Workspace Access

Inputs

List Workspaces

Inputs

Run SQL Query

Inputs

Add Columns

Inputs

Add Records

Inputs

Apply User Actions

Inputs

Copy Document

Inputs

Create Document

Inputs

Create Tables

Inputs

Create Workspace

Inputs

Fork Document

Inputs

Move Document

Inputs

Pin Document

Inputs

Restore Document

Inputs

Restore Workspace

Inputs

Move Document to Trash

Inputs

Move Workspace to Trash

Inputs

Unpin Document

Inputs

Update Columns

Inputs