# Grist

Grist is a relational spreadsheet platform that combines the flexibility of a spreadsheet with the robustness of a database, allowing users to create custom applications tailored to their data needs.

- **Category:** productivity
- **Auth:** API_KEY
- **Composio Managed App Available?** N/A
- **Tools:** 31
- **Triggers:** 0
- **Slug:** `GRIST`
- **Version:** 20260312_00

## Tools

### Add Records

**Slug:** `GRIST_ADD_RECORDS`

Add 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `docId` | string | Yes | The unique document identifier. Obtain from GRIST_LIST_WORKSPACES or document URL. |
| `noparse` | boolean | No | If true, values are stored as-is without type conversion (e.g., '30' stays as string, not converted to number). |
| `records` | array | Yes | 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. |
| `tableId` | string | Yes | The table identifier (column ID from GRIST_LIST_TABLES, e.g., 'Table1', 'People'). |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Document

**Slug:** `GRIST_CREATE_DOCUMENT`

Creates 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Name for the new document. This is a required field. |
| `isPinned` | boolean | No | Whether the new document should be pinned in the workspace. |
| `workspaceId` | integer | Yes | Numeric ID of the workspace in which to create the document. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create SCIM User

**Slug:** `GRIST_CREATE_SCIM_USER`

Tool to create a new SCIM user. Use when provisioning new user accounts via SCIM. Run after gathering all required user details.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | object | Yes | SCIM name object with givenName and familyName |
| `emails` | array | Yes | At least one email object for the user |
| `locale` | string | No | Locale for formatting, e.g., 'en_US' |
| `photos` | array | No | List containing a single photo object for the user |
| `schemas` | array | No | List of SCIM schema URNs. Defaults to the standard SCIM User schema. |
| `userName` | string | Yes | Unique username for the SCIM user |
| `displayName` | string | No | Display name of the user |
| `preferredLanguage` | string | No | Preferred language tag, e.g., 'en-US' |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Table

**Slug:** `GRIST_CREATE_TABLE`

Tool 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `docId` | string | Yes | The unique identifier of the Grist document in which to create tables. Obtain this from GRIST_LIST_WORKSPACES or GRIST_CREATE_DOCUMENT. |
| `tables` | array | Yes | List of tables to add to the document. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Document Webhook

**Slug:** `GRIST_CREATE_WEBHOOK`

Tool 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `docId` | string | Yes | Document ID where the webhook will be created. Get document IDs using GRIST_LIST_WORKSPACES. |
| `webhooks` | array | Yes | Array of webhook configurations to create. Each webhook monitors a specific table for events. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Remove Unused Attachments

**Slug:** `GRIST_DELETE_ATTACHMENT`

Remove 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `doc_id` | string | Yes | 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. |
| `expired_only` | boolean | No | 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Column

**Slug:** `GRIST_DELETE_COLUMN`

Tool to delete a column from a Grist document table. Use after confirming document, table, and column IDs.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `col_id` | string | Yes | The column ID to delete. Use the column ID (not label) as returned by List Columns, without any leading '$'. |
| `doc_id` | string | Yes | The document ID (alphanumeric string) of the Grist document containing the table. Obtain this from List Workspaces or the document URL. |
| `table_id` | string | Yes | The table ID (name) within the document. Use the normalized table name as returned by List Tables. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Grist Table Records

**Slug:** `GRIST_DELETE_RECORDS`

Tool 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `doc_id` | string | Yes | The unique document ID (e.g., 'kbd6BYdxxAzovKnA25Dp9z'). Obtain this from GRIST_LIST_WORKSPACES. |
| `row_ids` | array | Yes | List of integer row IDs to delete. Must contain at least one ID. Obtain row IDs from GRIST_LIST_RECORDS. |
| `table_id` | string | Yes | The table identifier (table name like 'Table1', 'People'). Obtain this from GRIST_LIST_TABLES. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete SCIM User

**Slug:** `GRIST_DELETE_SCIM_USER`

Delete a user from the Grist organization by their numeric user ID. Use GRIST_GET_USERS first to find the user's ID. Falls back to org access API if SCIM is not enabled. Note: Cannot delete your own account.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `user_id` | integer | Yes | 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Webhook

**Slug:** `GRIST_DELETE_WEBHOOK`

Permanently 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `doc_id` | string | Yes | The unique identifier of the Grist document containing the webhook. Can be obtained from GRIST_LIST_WORKSPACES or document URL. |
| `webhook_id` | string | Yes | The UUID of the webhook to delete. Can be obtained from GRIST_LIST_WEBHOOKS. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Download All Attachments Archive

**Slug:** `GRIST_DOWNLOAD_ALL_ATTACHMENTS_ARCHIVE`

Download 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `doc_id` | string | Yes | The document ID of the Grist document. Obtain this from GRIST_LIST_WORKSPACES (the 'id' field of documents) or from the document URL. |
| `format` | string ("zip" | "tar") | No | Archive format for the downloaded file. Use 'zip' for broader compatibility or 'tar' for Unix systems. Defaults to 'zip'. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Download Attachment

**Slug:** `GRIST_DOWNLOAD_ATTACHMENT`

Download 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `docId` | string | Yes | The unique identifier (alphanumeric string) of the Grist document containing the attachment. Obtain this from GRIST_LIST_WORKSPACES or GRIST_LIST_DOCUMENTS. |
| `attachmentId` | integer | Yes | The numeric ID of the attachment to download. Obtain this from GRIST_LIST_ATTACHMENTS. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Fetch Document Metadata

**Slug:** `GRIST_FETCH_DOCUMENT_METADATA`

Tool to fetch metadata for a specified Grist document. Use after obtaining the document ID.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `doc_id` | string | Yes | 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Fetch Table Metadata

**Slug:** `GRIST_FETCH_TABLE_METADATA`

Tool 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `doc_id` | string | Yes | The unique identifier (UUID) of the document. |
| `header` | string ("colId" | "label") | No | Header format: 'colId' for column IDs or 'label' for column labels. |
| `table_id` | string | Yes | The table ID or normalized table name within the document. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Org Access

**Slug:** `GRIST_GET_ORG_ACCESS`

Retrieves 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `org_id` | string | No | Organization identifier: numeric ID, subdomain string, or 'current' for the current org |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Users

**Slug:** `GRIST_GET_USERS`

Tool to retrieve a list of users via SCIM v2. Use when you need to page through and filter enterprise users in Grist.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `count` | integer | No | Number of users to return in this page. |
| `filter` | string | No | SCIM filter string to narrow down the results, e.g. 'userName eq "alice"'. |
| `startIndex` | integer | No | 1-based index at which to start pagination. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Attachments

**Slug:** `GRIST_LIST_ATTACHMENTS`

Tool to list all attachments in a Grist document. Use after confirming the document ID to retrieve attachment metadata.

#### Input Parameters

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

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Columns

**Slug:** `GRIST_LIST_COLUMNS`

Tool to list all columns in a specified Grist table. Use after selecting the document and table to inspect column metadata.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `doc_id` | string | Yes | The unique document identifier (alphanumeric string). Obtain from GRIST_LIST_WORKSPACES or GRIST_CREATE_DOCUMENT. |
| `hidden` | boolean | No | Set to true to include hidden system columns like 'manualSort'. Defaults to false. |
| `table_id` | string | Yes | The table ID (normalized name) within the document. Obtain from GRIST_LIST_TABLES. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Organizations

**Slug:** `GRIST_LIST_ORGANIZATIONS`

Tool to list all organizations accessible to the authenticated user. Use when you need to select a Grist organization for subsequent operations.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Records

**Slug:** `GRIST_LIST_RECORDS`

Tool 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

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

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Tables

**Slug:** `GRIST_LIST_TABLES`

Tool to list all tables within a specified document. Use after obtaining the document ID to retrieve its tables.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `docId` | string | Yes | The unique identifier of the Grist document to list tables from. Obtain this from GRIST_LIST_WORKSPACES or GRIST_CREATE_DOCUMENT. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Webhooks

**Slug:** `GRIST_LIST_WEBHOOKS`

List 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `doc_id` | string | Yes | 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Workspaces

**Slug:** `GRIST_LIST_WORKSPACES`

Tool 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Run SQL Query

**Slug:** `GRIST_RUN_SQL_QUERY`

Tool 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `sql` | string | Yes | 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. |
| `args` | array | No | Positional parameters to substitute for '?' placeholders in the SQL statement. Provide values in order matching the placeholders. |
| `docId` | string | Yes | Document ID of the Grist document to query. Obtain this via GRIST_LIST_WORKSPACES or from the document URL. |
| `timeout` | integer | No | Maximum execution time in milliseconds. Default is 1000ms. Can only be reduced from the default, not increased. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Column Metadata

**Slug:** `GRIST_UPDATE_COLUMN_METADATA`

Updates 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `docId` | string | Yes | Document ID (alphanumeric string) of the Grist document. Obtain from List Workspaces or document URL. |
| `columns` | array | Yes | 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). |
| `tableId` | string | Yes | Table ID (normalized name) as returned by List Tables action. This is the table's internal identifier, not its display name. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Document Metadata

**Slug:** `GRIST_UPDATE_DOCUMENT_METADATA`

Tool 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | New display name for the document. If not provided, the name remains unchanged. |
| `doc_id` | string | Yes | The unique identifier of the Grist document to update. Obtain this from GRIST_LIST_WORKSPACES or GRIST_CREATE_DOCUMENT. |
| `isPinned` | boolean | No | 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Records

**Slug:** `GRIST_UPDATE_RECORDS`

Update 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `docId` | string | Yes | The unique document identifier. Obtain this from GRIST_LIST_WORKSPACES (in the docs array) or from the document URL. |
| `noparse` | boolean | No | When true, string values are stored literally without auto-conversion to column types (e.g., dates, numbers). Useful when you want exact string storage. |
| `records` | array | Yes | 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). |
| `tableId` | string | Yes | The table name (e.g., 'People', 'Table1') or numeric table reference. Obtain from GRIST_LIST_TABLES. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Table Metadata

**Slug:** `GRIST_UPDATE_TABLE_METADATA`

Update metadata properties for a table in a Grist document. Currently the main updatable property is 'onDemand' which controls lazy loading of table data. Use List Tables to find valid table IDs first.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `docId` | string | Yes | The unique document identifier. Can be found in the document URL or via the List Workspaces action. |
| `fields` | object | Yes | 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. |
| `tableId` | string | Yes | The table identifier (normalized name). Use the List Tables action to find valid table IDs for a document. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Webhook

**Slug:** `GRIST_UPDATE_WEBHOOK`

Update an existing webhook configuration for a Grist document. Use to modify webhook settings such as URL, event types, enabled status, or target table. Requires valid document ID (from GRIST_LIST_WORKSPACES) and webhook ID (from GRIST_LIST_WEBHOOKS). Only provided fields will be updated; omitted fields remain unchanged.

#### Input Parameters

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

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Upload Attachment

**Slug:** `GRIST_UPLOAD_ATTACHMENT`

Upload 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `docId` | string | Yes | 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 |
| `files` | array | Yes | List of files to upload. Each file requires fileName, base64-encoded content, and optionally contentType |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |