Skip to main content
Grist logo
  • Category: productivity
  • Auth: API_KEY
  • Composio-managed OAuth available? N/A
  • Tools: 30
  • Triggers: 0
  • Slug: GRIST
  • Version: 20261101_00

Tools

Slug: GRIST_ADD_RECORDSAdd one or more records to a Grist table. First use GRIST_LIST_WORKSPACES to get docId, GRIST_LIST_TABLES to get tableId, and GRIST_LIST_COLUMNS to get column IDs for the fields mapping.

Input Parameters

string
required
The unique document identifier. Obtain from GRIST_LIST_WORKSPACES or document URL.
boolean
If true, values are stored as-is without type conversion (e.g., ‘30’ stays as string, not converted to number).
array
required
List of records to add. Each record contains a ‘fields’ object mapping column IDs to values. Use GRIST_LIST_COLUMNS to get valid column IDs.
string
required
The table identifier (column ID from GRIST_LIST_TABLES, e.g., ‘Table1’, ‘People’).

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GRIST_CREATE_DOCUMENTCreates a new Grist document in a specified workspace. Use this tool when you need to add a new spreadsheet document to a workspace. Requires a valid workspace ID (obtainable via GRIST_LIST_WORKSPACES) and a document name.

Input Parameters

string
required
Name for the new document. This is a required field.
boolean
Whether the new document should be pinned in the workspace.
integer
required
Numeric ID of the workspace in which to create the document.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GRIST_CREATE_SCIM_USERCreate a Grist user for SCIM provisioning. If SCIM is unavailable, this may instead grant owner access to the first supplied email in the first listed organization, or the current organization if none is listed; this does not create a SCIM user.

Input Parameters

object
required
SCIM name object with givenName and familyName
array
required
At least one email object for the user
string
Locale for formatting, e.g., ‘en_US’
array
List containing a single photo object for the user
array
List of SCIM schema URNs. Defaults to the standard SCIM User schema.
string
required
Unique username for the SCIM user
string
Display name of the user
string
Preferred language tag, e.g., ‘en-US’

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GRIST_CREATE_TABLETool to create tables in a document. Use after confirming the document ID. Creates one or more tables with specified columns in the given document.

Input Parameters

string
required
The unique identifier of the Grist document in which to create tables. Obtain this from GRIST_LIST_WORKSPACES or GRIST_CREATE_DOCUMENT.
array
required
List of tables to add to the document.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GRIST_CREATE_WEBHOOKTool to create a new webhook for a specified document. Use when you need to register webhook endpoints for document events in Grist. Run after confirming document ID.

Input Parameters

string
required
Document ID where the webhook will be created. Get document IDs using GRIST_LIST_WORKSPACES.
array
required
Array of webhook configurations to create. Each webhook monitors a specific table for events.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GRIST_DELETE_ATTACHMENTRemove unused attachments from a Grist document to free up storage space. IMPORTANT: This action removes ALL attachments that are not currently referenced by any cell in the document. It does NOT delete a specific attachment by ID. To remove a specific attachment: 1. First remove its reference from the Attachments column cell that contains it 2. Then call this action to clean up the now-unreferenced file Attachments become “unused” when they are no longer referenced by any Attachments-type cell. Grist normally retains unreferenced attachments for a period to allow undo operations. This action removes them immediately (or only expired ones if expired_only=true).

Input Parameters

string
required
The unique identifier of the Grist document. This is a string like ‘kRosSWLjYzm7iaHwV6XnXM’ that you can find in the document URL or from GRIST_LIST_WORKSPACES.
boolean
If true, only remove attachments that have been unreferenced for the server-configured retention period. If false (default), removes all currently unreferenced attachments immediately.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GRIST_DELETE_COLUMNTool to delete a column from a Grist document table. Use after confirming document, table, and column IDs.

Input Parameters

string
required
The column ID to delete. Use the column ID (not label) as returned by List Columns, without any leading ’$’.
string
required
The document ID (alphanumeric string) of the Grist document containing the table. Obtain this from List Workspaces or the document URL.
string
required
The table ID (name) within the document. Use the normalized table name as returned by List Tables.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GRIST_DELETE_RECORDSTool to delete records from a specified Grist table. Use when you need to remove specific rows by their IDs. Use after confirming the row IDs exist.

Input Parameters

string
required
The unique document ID (e.g., ‘kbd6BYdxxAzovKnA25Dp9z’). Obtain this from GRIST_LIST_WORKSPACES.
array
required
List of integer row IDs to delete. Must contain at least one ID. Obtain row IDs from GRIST_LIST_RECORDS.
string
required
The table identifier (table name like ‘Table1’, ‘People’). Obtain this from GRIST_LIST_TABLES.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GRIST_DELETE_SCIM_USERDelete a Grist SCIM user by numeric user ID. In some cases, the operation instead removes the user’s access to the first listed organization, or the current organization if none is listed; this is not a SCIM user deletion.

Input Parameters

integer
required
The numeric user ID of the SCIM user to delete. Obtain this ID from the GRIST_GET_USERS action or from the ‘id’ field when creating a user. Note: You cannot delete your own account.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GRIST_DELETE_WEBHOOKPermanently removes a webhook from a Grist document. Use this tool when you need to stop receiving notifications for document changes. First use GRIST_LIST_WEBHOOKS to find the webhook_id you want to delete. This action is destructive and cannot be undone.

Input Parameters

string
required
The unique identifier of the Grist document containing the webhook. Can be obtained from GRIST_LIST_WORKSPACES or document URL.
string
required
The UUID of the webhook to delete. Can be obtained from GRIST_LIST_WEBHOOKS.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GRIST_DOWNLOAD_ALL_ATTACHMENTS_ARCHIVEDownload all attachments from a Grist document as a single archive file (.zip or .tar). Use this to bulk-download attachments. Ensure the document has attachments before calling (check with GRIST_LIST_ATTACHMENTS). Returns an empty archive if no attachments exist.

Input Parameters

string
required
The document ID of the Grist document. Obtain this from GRIST_LIST_WORKSPACES (the ‘id’ field of documents) or from the document URL.
string ("zip" | "tar")
Archive format for the downloaded file. Use ‘zip’ for broader compatibility or ‘tar’ for Unix systems. Defaults to ‘zip’.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GRIST_DOWNLOAD_ATTACHMENTDownload a file attachment from a Grist document. Returns the file content as a downloadable file. Use GRIST_LIST_ATTACHMENTS first to get valid attachment IDs.

Input Parameters

string
required
The unique identifier (alphanumeric string) of the Grist document containing the attachment. Obtain this from GRIST_LIST_WORKSPACES or GRIST_LIST_DOCUMENTS.
integer
required
The numeric ID of the attachment to download. Obtain this from GRIST_LIST_ATTACHMENTS.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GRIST_FETCH_DOCUMENT_METADATATool to fetch metadata for a specified Grist document. Use after obtaining the document ID.

Input Parameters

string
required
Document identifier. Accepts either the full document ID (e.g., ‘rsUfVdgSXSL3UpmhYq3tAe’) or the short urlId alias (e.g., ‘rsUfVdgSXSL3’). Can be obtained from list workspaces or create document actions.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GRIST_FETCH_TABLE_METADATATool to retrieve metadata for a specified table in a Grist document. Use when you need to inspect table schema details before data operations.

Input Parameters

string
required
The unique identifier (UUID) of the document.
string ("colId" | "label")
Header format: ‘colId’ for column IDs or ‘label’ for column labels.
string
required
The table ID or normalized table name within the document.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GRIST_GET_ORG_ACCESSRetrieves the list of users who have access to a Grist organization along with their access roles (owners, editors, viewers). Use this to find user IDs, emails, or check access permissions within an organization. Useful for user management tasks.

Input Parameters

string
Organization identifier: numeric ID, subdomain string, or ‘current’ for the current org

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GRIST_GET_USERSList Grist users via SCIM v2, with filtering and pagination. When SCIM is unavailable, results may instead cover users with access to the current organization; in that case filtering is limited to simple username and display-name expressions.

Input Parameters

integer
Number of users to return in this page.
string
SCIM filter string to narrow down the results, e.g. ‘userName eq “alice”’.
integer
1-based index at which to start pagination.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GRIST_LIST_ATTACHMENTSTool to list all attachments in a Grist document. Use after confirming the document ID to retrieve attachment metadata.

Input Parameters

string
Comma-separated list of fields for sorting attachments. Prefix with ’-’ for descending order. Supported fields: fileName, fileSize, timeUploaded.
string
required
The unique identifier of the Grist document to list attachments from. Can be obtained from GRIST_LIST_WORKSPACES or document URL.
integer
Maximum number of attachments to return; 0 means no limit
string
Alternative to ‘sort’ parameter, passed via HTTP header. Use same format as ‘sort’. Takes precedence over query parameter if both provided.
string
JSON string mapping attachment field names to arrays of allowed values for filtering. Supported fields: fileName, fileSize, timeUploaded.
integer
Alternative to ‘limit’ parameter, passed via HTTP header. Takes precedence over query parameter if both provided.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GRIST_LIST_COLUMNSList columns and their metadata in a specified Grist table. Hidden columns are included when requested.

Input Parameters

string
required
The unique document identifier (alphanumeric string). Obtain from GRIST_LIST_WORKSPACES or GRIST_CREATE_DOCUMENT.
boolean
Set to true to include hidden system columns like ‘manualSort’. Defaults to false.
string
required
The table ID (normalized name) within the document. Obtain from GRIST_LIST_TABLES.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GRIST_LIST_ORGANIZATIONSTool to list all organizations accessible to the authenticated user. Use when you need to select a Grist organization for subsequent operations.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GRIST_LIST_RECORDSTool to retrieve records from a specified table within a Grist document. Use when you need to fetch rows by applying optional filters, sorting, limits, or hidden columns. Example: list records where pet is ‘cat’ sorted by ‘-age’.

Input Parameters

string
Comma-separated columns to sort by; prefix with ’-’ for descending. Supports options via ‘:choiceOrder’, ‘naturalSort’, ‘emptyFirst’.
string
required
Document ID (alphanumeric string) of the Grist document. Obtain this from GRIST_LIST_WORKSPACES or GRIST_CREATE_DOCUMENT.
integer
Maximum number of rows to return; 0 means no limit.
string
URL-encoded JSON mapping column names to allowed values arrays. Example: ’{“pet”:[“cat”,“dog”]}’.
boolean
If true, include hidden columns (e.g., manualSort).
string
required
Table identifier (normalized name) or numeric _grist_Tables row ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GRIST_LIST_TABLESTool to list all tables within a specified document. Use after obtaining the document ID to retrieve its tables.

Input Parameters

string
required
The unique identifier of the Grist document to list tables from. Obtain this from GRIST_LIST_WORKSPACES or GRIST_CREATE_DOCUMENT.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GRIST_LIST_WEBHOOKSList all webhooks configured for a Grist document. Returns webhook configuration details (URL, event types, table binding) and delivery status information. Use this to inspect, audit, or manage webhooks for a document. Requires a valid document ID obtained from GRIST_LIST_WORKSPACES or GRIST_CREATE_DOCUMENT.

Input Parameters

string
required
The document identifier. Can be either the full document ID (e.g., ‘rsUfVdgSXSL3UpmhYq3tAe’) or the short URL ID (e.g., ‘rsUfVdgSXSL3’). Obtain this from GRIST_LIST_WORKSPACES or GRIST_CREATE_DOCUMENT.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GRIST_LIST_WORKSPACESTool to list all workspaces and documents accessible to the authenticated user on the current site. Use when you need to select a workspace or document for subsequent operations.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GRIST_RUN_SQL_QUERYTool to execute a read-only SQL SELECT query on a Grist document. Use after confirming the document ID and preparing a valid SQL SELECT statement.

Input Parameters

string
required
SQL SELECT statement to execute. Must be a single read-only SELECT (no INSERT/UPDATE/DELETE). Do not include trailing semicolon. WITH clauses and parameterized queries (using ’?’ placeholders) are supported.
array
Positional parameters to substitute for ’?’ placeholders in the SQL statement. Provide values in order matching the placeholders.
string
required
Document ID of the Grist document to query. Obtain this via GRIST_LIST_WORKSPACES or from the document URL.
integer
Maximum execution time in milliseconds. Default is 1000ms. Can only be reduced from the default, not increased.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GRIST_UPDATE_COLUMN_METADATAUpdates metadata (label, type, description, formula, etc.) for one or more columns in a Grist table. Use List Columns first to get valid column IDs. Warning: changing ‘label’ may rename the column ID unless ‘untieColIdFromLabel’ is set to true.

Input Parameters

string
required
Document ID (alphanumeric string) of the Grist document. Obtain from List Workspaces or document URL.
array
required
List of column updates to apply. IMPORTANT: When updating multiple columns in one request, all columns must specify the same set of field keys (e.g., all must have ‘label’ and ‘description’, not mixed).
string
required
Table ID (normalized name) as returned by List Tables action. This is the table’s internal identifier, not its display name.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GRIST_UPDATE_DOCUMENT_METADATATool to update metadata for a specified Grist document. Use when you need to rename or pin/unpin a document after obtaining its ID.

Input Parameters

string
New display name for the document. If not provided, the name remains unchanged.
string
required
The unique identifier of the Grist document to update. Obtain this from GRIST_LIST_WORKSPACES or GRIST_CREATE_DOCUMENT.
boolean
Set to true to pin the document in the workspace for quick access, or false to unpin it. If not provided, the pinned status remains unchanged.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GRIST_UPDATE_RECORDSUpdate existing records in a Grist table by their row IDs. Use this tool to modify field values for one or more records in a specified document and table. First use GRIST_LIST_RECORDS to obtain the record IDs you want to update. Supports batch updates - you can update multiple records in a single call. The API uses PATCH semantics, meaning only specified fields are updated; unspecified fields remain unchanged. IMPORTANT: When updating multiple records in a batch, all records must specify the exact same set of field names (e.g., if updating Name and Age for record 1, you must also update Name and Age for record 2).

Input Parameters

string
required
The unique document identifier. Obtain this from GRIST_LIST_WORKSPACES (in the docs array) or from the document URL.
boolean
When true, string values are stored literally without auto-conversion to column types (e.g., dates, numbers). Useful when you want exact string storage.
array
required
Array of records to update. Each record must include ‘id’ (the row ID from GRIST_LIST_RECORDS) and ‘fields’ (column-value pairs to update). IMPORTANT: When updating multiple records in one call, all records MUST specify the exact same set of field names (Grist API requirement).
string
required
The table name (e.g., ‘People’, ‘Table1’) or numeric table reference. Obtain from GRIST_LIST_TABLES.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GRIST_UPDATE_TABLE_METADATAUpdate metadata for a table in a Grist document, including its table ID for renaming or its on-demand loading setting. The response echoes the requested update.

Input Parameters

string
required
The unique document identifier. Can be found in the document URL or via the List Workspaces action.
object
required
Metadata fields to update. The main supported property is ‘onDemand’ (boolean) which controls whether the table data is loaded on-demand. Must contain at least one property to update.
string
required
The table identifier (normalized name). Use the List Tables action to find valid table IDs for a document.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GRIST_UPDATE_WEBHOOKUpdate an existing webhook on a Grist document, changing provided settings such as its URL, event types, enabled status, or target table. Omitted settings remain unchanged. An update may take effect even when the tool reports an error.

Input Parameters

string
Destination URL to receive webhook POST requests when events occur.
string
Longer description for the webhook
string
Short descriptive name for the webhook
string
required
The document ID (a short URL-safe string, e.g., ‘rsUfVdgSXSL3UpmhYq3tAe’) containing the webhook. Obtain from GRIST_LIST_WORKSPACES or GRIST_CREATE_DOCUMENT.
boolean
Whether the webhook is active. Set to false to disable without deleting.
string
Table ID to monitor for changes (e.g., ‘Table1’, ‘Products’). Get table IDs using GRIST_LIST_TABLES.
array
List of events that trigger the webhook. Valid values: ‘add’ (new records), ‘update’ (modified records).
string
required
UUID identifier of the webhook to update (e.g., ‘0024e0d2-8ecb-4748-b89f-7b15824b9778’). Obtain from GRIST_LIST_WEBHOOKS or GRIST_CREATE_WEBHOOK.
string
Column ID of a boolean column (e.g., ‘Ready’); webhook only triggers when this column’s value is truthy for a record.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GRIST_UPLOAD_ATTACHMENTUpload one or more file attachments to a Grist document. Returns attachment IDs that can be used to link files to records in Attachments-type columns. First use GRIST_LIST_WORKSPACES to get a valid document ID.

Input Parameters

string
required
The unique identifier of the Grist document to attach files to. Obtain this from GRIST_LIST_WORKSPACES which returns document IDs in the ‘docs’ array
array
required
List of files to upload. Each file requires fileName, base64-encoded content, and optionally contentType

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not