Grist | Composio Docs

Overview

SLUG: GRIST

Description

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.

Authentication Details

API Key

subdomain

stringRequired

generic_api_key

stringRequired

Connecting to Grist

Create an auth config

Use the dashboard to create an auth config for the Grist toolkit. This allows you to connect multiple Grist accounts to Composio for agents to use.

Select App

Navigate to Grist.

Configure Auth Config Settings

Select among the supported auth schemes of and configure them here.

Create and Get auth config ID

Click “Create Grist Auth Config”. After creation, copy the displayed ID starting with ac_. This is your auth config ID. This is not a sensitive ID — you can save it in environment variables or a database. This ID will be used to create connections to the toolkit for a given user.

Connect Your Account

Using API Key

1 from composio import Composio
2 
3 # Replace these with your actual values
4 grist_auth_config_id = "ac_YOUR_GRIST_CONFIG_ID" # Auth config ID created above
5 user_id = "0000-0000-0000"  # UUID from database/app
6 
7 composio = Composio()
8 
9 def authenticate_toolkit(user_id: str, auth_config_id: str):
10     # Replace this with a method to retrieve an API key from the user.
11     # Or supply your own.
12     user_api_key = input("[!] Enter API key")
13 
14     connection_request = composio.connected_accounts.initiate(
15         user_id=user_id,
16         auth_config_id=auth_config_id,
17         config={"auth_scheme": "API_KEY", "val": {"generic_api_key": user_api_key}}
18     )
19 
20     # API Key authentication is immediate - no redirect needed
21     print(f"Successfully connected Grist for user {user_id}")
22     print(f"Connection status: {connection_request.status}")
23     
24     return connection_request.id
25 
26 
27 connection_id = authenticate_toolkit(user_id, grist_auth_config_id)
28 
29 # You can verify the connection using:
30 connected_account = composio.connected_accounts.get(connection_id)
31 print(f"Connected account: {connected_account}")

Tools

Executing tools

To prototype you can execute some tools to see the responses and working on the Grist toolkit’s playground

OpenAI (Python)

Anthropic (TypeScript)

Google (Python)

Vercel (TypeScript)

Python

1 from composio import Composio
2 from openai import OpenAI
3 import json
4 
5 openai = OpenAI()
6 composio = Composio()
7 
8 # User ID must be a valid UUID format
9 user_id = "0000-0000-0000"  # Replace with actual user UUID from your database
10 
11 tools = composio.tools.get(user_id=user_id, toolkits=["GRIST"])
12 
13 print("[!] Tools:")
14 print(json.dumps(tools))
15 
16 def invoke_llm(task = "What can you do?"):
17     completion = openai.chat.completions.create(
18         model="gpt-4o",
19         messages=[
20             {
21                 "role": "user",
22                 "content": task,  # Your task here!
23             },
24         ],
25         tools=tools,
26     )
27 
28     # Handle Result from tool call
29     result = composio.provider.handle_tool_calls(user_id=user_id, response=completion)
30     print(f"[!] Completion: {completion}")
31     print(f"[!] Tool call result: {result}")
32 
33 invoke_llm()

Tool List

GRIST_ADD_RECORDS

Tool Name: Add Records

Description

Tool to add records to a specified table in a Grist document. Use after confirming doc and table IDs.

Action Parameters

docId

stringRequired

noparse

boolean

records

arrayRequired

tableId

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

GRIST_CREATE_DOCUMENT

Tool Name: Create Document

Description

Tool to create a document in a workspace. Use when you need to add a new document programmatically after selecting a workspace.

Action Parameters

isPinned

boolean

name

string

workspaceId

integerRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

GRIST_CREATE_SCIM_USER

Tool Name: Create SCIM User

Description

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

Action Parameters

displayName

string

emails

arrayRequired

locale

string

name

objectRequired

photos

array

preferredLanguage

string

schemas

arrayRequired

userName

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

GRIST_CREATE_TABLE

Tool Name: Create Table

Description

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.

Action Parameters

docId

stringRequired

tables

arrayRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

GRIST_CREATE_WEBHOOK

Tool Name: Create Document Webhook

Description

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.

Action Parameters

docId

stringRequired

webhooks

arrayRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

GRIST_DELETE_ATTACHMENT

Tool Name: Delete Attachment

Description

Tool to delete a specified attachment from a Grist document. Use when you need to remove a file by providing its document and attachment IDs.

Action Parameters

attachment_id

integerRequired

doc_id

stringRequired

expiredOnly

boolean

Action Response

data

objectRequired

error

string

successful

booleanRequired

GRIST_DELETE_COLUMN

Tool Name: Delete Column

Description

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

Action Parameters

col_id

stringRequired

doc_id

stringRequired

table_id

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

GRIST_DELETE_RECORDS

Tool Name: Delete Grist Table Records

Description

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.

Action Parameters

doc_id

stringRequired

row_ids

arrayRequired

table_id

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

GRIST_DELETE_SCIM_USER

Tool Name: Delete SCIM User

Description

Tool to delete a specified user via SCIM. Use after confirming the user's SCIM user ID exists.

Action Parameters

user_id

integerRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

GRIST_DELETE_WEBHOOK

Tool Name: Delete Webhook

Description

Tool to delete a webhook from a Grist document. Use when you need to remove a specific webhook after confirming its ID.

Action Parameters

doc_id

stringRequired

webhook_id

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

GRIST_DOWNLOAD_ALL_ATTACHMENTS_ARCHIVE

Tool Name: Download All Attachments Archive

Description

Tool to download all attachments from a Grist document as a .zip or .tar archive. Use after ensuring attachments exist in the specified document.

Action Parameters

doc_id

stringRequired

format

string

Action Response

data

objectRequired

error

string

successful

booleanRequired

GRIST_DOWNLOAD_ATTACHMENT

Tool Name: Download Attachment

Description

Tool to download the binary data of an attachment. Use when you have the document ID and attachment ID and need the raw file content.

Action Parameters

attachmentId

integerRequired

docId

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

GRIST_DOWNLOAD_ATTACHMENT_CONTENT

Tool Name: Download Grist Attachment Content

Description

Tool to download the raw bytes of an attachment. Use when you need to retrieve the binary data of a specific Grist document attachment after confirming the document and attachment IDs.

Action Parameters

attachmentId

integerRequired

docId

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

GRIST_FETCH_COLUMN_METADATA

Tool Name: Fetch Column Metadata

Description

Tool to fetch metadata for a specific column in a Grist document table. Use when you need to inspect column properties before data operations.

Action Parameters

col_id

stringRequired

doc_id

stringRequired

table_id

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

GRIST_FETCH_DOCUMENT_METADATA

Tool Name: Fetch Document Metadata

Description

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

Action Parameters

doc_id

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

GRIST_FETCH_TABLE_METADATA

Tool Name: Fetch Table Metadata

Description

Tool to retrieve metadata for a specified table in a Grist document. Use when you need to inspect table schema details before data operations.

Action Parameters

doc_id

stringRequired

header

string

table_id

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

GRIST_GET_ORG_ACCESS

Tool Name: Get Org Access

Description

Tool to fetch org access details. Use when you need to retrieve numeric user IDs for actions like SCIM user deletion when SCIM API is disabled.

Action Parameters

org_id

integerDefaults to current

Action Response

data

objectRequired

error

string

successful

booleanRequired

GRIST_GET_USERS

Tool Name: Get Users

Description

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

Action Parameters

count

integer

filter

string

startIndex

integer

Action Response

data

objectRequired

error

string

successful

booleanRequired

GRIST_LIST_ATTACHMENTS

Tool Name: List Attachments

Description

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

Action Parameters

X-Limit

integer

X-Sort

string

docId

stringRequired

filter

string

limit

integer

sort

string

Action Response

data

objectRequired

error

string

successful

booleanRequired

GRIST_LIST_COLUMNS

Tool Name: List Columns

Description

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

Action Parameters

doc_id

stringRequired

hidden

boolean

table_id

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

GRIST_LIST_ORGANIZATIONS

Tool Name: List Organizations

Description

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

Action Parameters

Action Response

data

objectRequired

error

string

successful

booleanRequired

GRIST_LIST_RECORDS

Tool Name: List Records

Description

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

Action Parameters

docId

stringRequired

filter

string

hidden

boolean

limit

integer

sort

string

tableId

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

GRIST_LIST_TABLES

Tool Name: List Tables

Description

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

Action Parameters

docId

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

GRIST_LIST_WEBHOOKS

Tool Name: List Webhooks

Description

Tool to list webhooks configured for a document. Use when you need to retrieve all webhooks for a document after obtaining its ID.

Action Parameters

doc_id

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

GRIST_LIST_WORKSPACES

Tool Name: List Workspaces

Description

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.

Action Parameters

Action Response

data

objectRequired

error

string

successful

booleanRequired

GRIST_RUN_SQL_QUERY

Tool Name: Run SQL Query

Description

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.

Action Parameters

args

array

docId

stringRequired

sql

stringRequired

timeout

integer

Action Response

data

objectRequired

error

string

successful

booleanRequired

GRIST_UPDATE_COLUMN_METADATA

Tool Name: Update Column Metadata

Description

Tool to update metadata for one or more columns in a Grist document table. Use after confirming document and table IDs. Example: change label or type of columns.

Action Parameters

columns

arrayRequired

docId

stringRequired

tableId

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

GRIST_UPDATE_DOCUMENT_METADATA

Tool Name: Update Document Metadata

Description

Tool to update metadata for a specified Grist document. Use when you need to rename or pin/unpin a document after obtaining its ID.

Action Parameters

doc_id

stringRequired

isPinned

boolean

name

string

Action Response

data

objectRequired

error

string

successful

booleanRequired

GRIST_UPDATE_RECORDS

Tool Name: Update Records

Description

Tool to update records in a specified table within a document. Use after fetching record IDs.

Action Parameters

docId

stringRequired

noparse

boolean

records

arrayRequired

tableId

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

GRIST_UPDATE_TABLE_METADATA

Tool Name: Update Table Metadata

Description

Tool to update metadata for a specified table. Use after confirming document and table IDs to modify properties such as onDemand or visibility.

Action Parameters

docId

stringRequired

fields

objectRequired

tableId

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

GRIST_UPDATE_WEBHOOK

Tool Name: Update Webhook

Description

Tool to update an existing webhook for a specified document. Use when you need to modify webhook settings after confirming document and webhook IDs.

Action Parameters

doc_id

stringRequired

enabled

boolean

eventTypes

array

isReadyColumn

string

memo

string

name

string

tableId

string

url

string

webhook_id

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

GRIST_UPLOAD_ATTACHMENT

Tool Name: Upload Attachment

Description

Tool to upload one or more attachments to a Grist document. Use when you need to add files to a document after preparing file data.

Action Parameters

docId

stringRequired

files

arrayRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired