# 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
- **Tools:** 32
- **Triggers:** 0
- **Slug:** `GRIST`
- **Version:** 20260211_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.

### 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.

### 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.

### 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.

### 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.

### 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).

### Delete Column

**Slug:** `GRIST_DELETE_COLUMN`

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

### 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.

### 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.

### 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.

### 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.

### 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.

### Download Grist Attachment Content

**Slug:** `GRIST_DOWNLOAD_ATTACHMENT_CONTENT`

Download the binary content of a Grist document attachment as base64-encoded data. Use this when you need to retrieve and process attachment content directly in memory. First use GRIST_LIST_WORKSPACES to get a document ID, then GRIST_LIST_ATTACHMENTS to get the attachment ID.

### Fetch Column Metadata

**Slug:** `GRIST_FETCH_COLUMN_METADATA`

Fetch detailed metadata for a specific column in a Grist table. Returns column type, formula info, description, and display settings. Use to inspect column properties before data operations or to understand column configuration.

### Fetch Document Metadata

**Slug:** `GRIST_FETCH_DOCUMENT_METADATA`

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

### 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.

### 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.

### 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.

### 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.

### 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.

### 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.

### 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'.

### 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.

### 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.

### 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.

### 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.

### 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.

### 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.

### 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).

### 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.

### 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.

### 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.
