> ## Documentation Index
> Fetch the complete documentation index at: https://docs.atako.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Grist

> Connect Grist to your Atako agents — 6 read and 3 write actions.

Let your agents work with your Grist documents: browse workspaces, tables and columns, read, filter and sort records, run read-only SQL queries, add, update and upsert records.

## Connection

* **Authentication**: API key (Grist API key).
* **Required settings**:
  * **Grist domain** — docs.getgrist.com for your personal area, \<team>.getgrist.com for a team site, or your own domain if self-hosted (no https\:// nor path).

> [!NOTE]
>
> In Grist: click your avatar → Account settings → Developer → API Key → Create. Copy the key. It acts with your own access rights, so use an account that only sees the documents the agents need. Set the Grist domain to docs.getgrist.com for your personal area, \<team>.getgrist.com for a team site, or your own domain if you self-host. API usage limits depend on your plan: see Grist pricing.
>
> See [Grist's documentation](https://support.getgrist.com/rest-api/).

## Read actions (6)

| Action | Description |
| - | - |
| `list_columns` | List the columns of a table: \{columns:\[\{id, fields:\{label, type, widgetOptions (JSON string, e.g. Choice options), isFormula, …}}]}. The column id is the key to use in fields / filter / sort. docId: string, required; tableId: string, required, from list\_tables. |
| `list_orgs` | List the Grist sites (team sites or personal area) the key can access: \[\{id, name, domain, …}]. Use an id with list\_workspaces. Also used as the credential probe. No arguments. |
| `list_records` | List the records of a table: \{records:\[\{id, fields:\{\<column id>: value}}]}. docId: string, required; tableId: string, required. Optional: filter (object \{ "\<column id>": \[allowed values] }, e.g. \{"Status":\["open","pending"],"Size":\["S"]}: a record must match one value of EACH listed column; exact match only); sort (string, column ids comma-separated, "-" prefix = descending, e.g. "Status,-Amount"; without it the order is unspecified); limit (integer, max records returned, 0 = no limit). |
| `list_tables` | List the tables of a document: \{tables:\[\{id, fields}]}. The table id (string) is needed by the record actions. docId: string, required, from list\_workspaces. |
| `list_workspaces` | List the workspaces of a site with the documents they contain: \[\{id, name, docs:\[\{id, name, …}]}]. The document id (docs\[].id, string) is needed by every other action. orgId: integer id from list\_orgs, or the string "current" for the site of the configured domain (required). |
| `run_sql` | Run a read-only SQL SELECT query against a document (SQLite; WITH clauses allowed, a single statement without trailing semicolon, nothing that modifies data); answer \{statement, records:\[\{fields:\{…}}]}. Tables and columns are named by their ids (see list\_tables, list\_columns). Arguments: docId (string, required, from list\_workspaces); q (string, required, the SQL query, e.g. "select \* from Contacts where Amount > 100 limit 20"). |

## Write actions (3)

| Action | Description |
| - | - |
| `add_records` | Add records to a table; returns \{records:\[\{id}]}. Arguments: docId (string, required); tableId (string, required); records (array of objects, required, 1 to 200, each \{ "fields": \{ "\<column id>": value } } with only the columns to fill). Cell values by column type: Text / Choice = string; Numeric / Int = number; Bool = true/false; Date = "YYYY-MM-DD" string; DateTime = Unix timestamp in seconds (number); Choice List = \["L", "a", "b"]; Reference = row id (integer); Reference List = \["L", 1, 2]. Formula columns cannot be written. Call list\_columns first for exact column ids and types. |
| `update_records` | Update existing records: only the columns given are changed. Arguments: docId (string, required); tableId (string, required); records (array of objects, required, 1 to 200, each \{ "id": record id (integer, from list\_records), "fields": \{ "\<column id>": new value } }). Cell values by column type: Text / Choice = string; Numeric / Int = number; Bool = true/false; Date = "YYYY-MM-DD" string; DateTime = Unix timestamp in seconds (number); Choice List = \["L", "a", "b"]; Reference = row id (integer); Reference List = \["L", 1, 2]. Formula columns cannot be written. Call list\_columns first for exact column ids and types. |
| `upsert_records` | Add or update records by matching key: for each item, the record whose columns equal `require` is updated with `fields`; if none matches, a new record is created from require + fields. Arguments: docId (string, required); tableId (string, required); records (array of objects, required, 1 to 200, each \{ "require": \{ "\<column id>": value } (non-empty, the match key), "fields": \{ "\<column id>": value } (optional) }); onmany (string, optional: when several records match, "first" (default), "none" or "all"); noadd (boolean, optional: true = never create); noupdate (boolean, optional: true = never update). Cell values by column type: Text / Choice = string; Numeric / Int = number; Bool = true/false; Date = "YYYY-MM-DD" string; DateTime = Unix timestamp in seconds (number); Choice List = \["L", "a", "b"]; Reference = row id (integer); Reference List = \["L", 1, 2]. Formula columns cannot be written. Call list\_columns first for exact column ids and types. |

## Permissions

Every action above must be explicitly granted to an agent before it can be used. See [Permissions](https://docs.atako.ai/integrations/permissions.md) for the grant model and [Security](https://docs.atako.ai/integrations/security.md) for how credentials are protected.

***

*Last reviewed against the provider API: October 2026.*


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.