Grist

Delete a document. DELETE /docs/{docId}. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Delete a column of a table. DELETE /docs/{docId}/tables/{tableId}/columns/{colId}.

Remove a webhook. DELETE /docs/{docId}/webhooks/{webhookId}. Permanently delete a webhook. Any pending deliveries in the queue for this webhook will also be removed.

Empty a document's queue of undelivered payloads. DELETE /docs/{docId}/webhooks/queue. Clear all pending webhook deliveries for this document. Use this if the queue has built up due to unreachable endpoints.

Clear queue for a specific webhook. DELETE /docs/{docId}/webhooks/queue/{webhookId}. Clear the queue of pending payloads for a specific webhook. Only document owners can call this endpoint.

Delete an org. DELETE /orgs/{orgId}/{name}. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Delete user's API key. DELETE /profile/apikey. Delete the current user's API key. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Delete a service account. DELETE /service-accounts/{saId}. This deletes a given service account. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Delete a service account's api key. DELETE /service-accounts/{saId}/apikey. Deletes the API key for a service account. The service account will no longer be able to authenticate until a new key is generated. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Delete a user from Grist. DELETE /users/{userId}. This action also deletes the user's personal organisation and all the workspaces and documents it contains. Currently, only the users themselves are allowed to delete their own accounts. This action cannot be undone, please be cautious when using this endpoint IRREVERSIBLE: this deletes the connected Grist account itself, along with its personal organisation and every workspace and document in it. Grist requires the account's own name in the body as a confirmation. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Delete a workspace. DELETE /workspaces/{workspaceId}. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Describe a document. GET /docs/{docId}. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

List users with access to document. GET /docs/{docId}/access. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

List metadata of all attachments in a doc. GET /docs/{docId}/attachments.

Download all attachments. GET /docs/{docId}/attachments/archive. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Get the metadata for an attachment. GET /docs/{docId}/attachments/{attachmentId}.

Download the contents of an attachment. GET /docs/{docId}/attachments/{attachmentId}/download.

Get external store. GET /docs/{docId}/attachments/store. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

List external attachment stores. GET /docs/{docId}/attachments/stores. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Get attachment transfer status. GET /docs/{docId}/attachments/transferStatus. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Compare document versions. GET /docs/{docId}/compare. Compare two versions of the same document by their state hashes. Returns details about what changed between the versions. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Compare two documents. GET /docs/{docId}/compare/{docId2}. Compare this document with another document. Useful for comparing a fork with its trunk document. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Content of table, as a CSV file. GET /docs/{docId}/download/csv.

Content of table, as a DSV file. GET /docs/{docId}/download/dsv. Download table data using a custom delimiter (💩).

Get form view data. GET /docs/{docId}/forms/{viewSectionId}. Get the form configuration for a specific view section. Forms are a special view type that allows external users to submit data. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

List change proposals. GET /docs/{docId}/proposals. List proposals associated with a document. Proposals are suggested changes from forks that can be reviewed and applied to the trunk document. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

List document snapshots. GET /docs/{docId}/snapshots. Returns a list of snapshots (backups) of the document. Snapshots are created automatically as the document is edited. Most recent snapshots are listed first. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Run an SQL query against a document. GET /docs/{docId}/sql. Execute a read-only SQL SELECT query against the document's SQLite database. This is a simplified endpoint for basic queries. For queries with parameters or custom timeouts, use the POST endpoint instead. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Get document action history states. GET /docs/{docId}/states. Returns a list of document states representing the action history. Each state has a sequential number (n) and a hash (h) that uniquely identifies that point in history. Most recent state is first. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

List tables in a document. GET /docs/{docId}/tables.

List columns in a table. GET /docs/{docId}/tables/{tableId}/columns.

Fetch data from a table. GET /docs/{docId}/tables/{tableId}/data. Deprecated in favor of `records` endpoints. We have no immediate plans to remove these endpoints, but consider `records` a better starting point for new projects. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Fetch records from a table. GET /docs/{docId}/tables/{tableId}/records.

Get formula timing status. GET /docs/{docId}/timing. Check if formula timing is enabled for a document and retrieve timing data if available. Only document owners can access timing information. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Get users for 'View As' feature. GET /docs/{docId}/usersForViewAs. Get users that can be used with the "View As" feature for testing access rules. Only document owners can call this endpoint. Users are drawn from: Users the document is shared with Users mentioned in user attribute tables Predefined example users REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Webhooks associated with a document. GET /docs/{docId}/webhooks. Returns all webhooks configured for this document, including their settings and delivery statistics.

List the orgs you have access to. GET /orgs. This enumerates all the team sites or personal areas available.

Describe an org. GET /orgs/{orgId}. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

List users with access to org. GET /orgs/{orgId}/access. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Get organization usage summary. GET /orgs/{orgId}/usage. Get usage statistics for all non-deleted documents in the organization. Only accessible to organization owners. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

List workspaces and documents within an org. GET /orgs/{orgId}/workspaces.

Get user's API key. GET /profile/apikey. Returns the current user's API key if one exists. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Get current user's profile. GET /profile/user. Returns the profile information of the currently authenticated user.

Get all your service accounts. GET /service-accounts. This lists all your service accounts with their details. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Get a service account's details. GET /service-accounts/{saId}. This reports the details of a service account. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Get active session information. GET /session/access/active. Returns information about the active user and organization for the current session. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Get all session users and organizations. GET /session/access/all. Returns all user profiles logged into the current session and all organizations they can access. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

List available templates. GET /templates. Get all available templates. Templates are organized by workspace within a template organization configured on the server. Note: Requires a template organization to be configured on the server. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Get template details. GET /templates/{templateId}. Get information about a specific template. Note: Requires a template organization to be configured on the server. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

List available custom widgets. GET /widgets. Get all widget definitions from the configured widget repository. Custom widgets extend Grist's functionality with specialized views. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Describe a workspace. GET /workspaces/{workspaceId}. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

List users with access to workspace. GET /workspaces/{workspaceId}/access. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Modify document metadata (but not its contents). PATCH /docs/{docId}. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Change who has access to document. PATCH /docs/{docId}/access. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Move document to another workspace.. PATCH /docs/{docId}/move. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Pin a document. PATCH /docs/{docId}/pin. Pin the document so it appears in a prominent location. Pinned documents are displayed at the top of workspace listings for easy access. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Modify tables of a document. PATCH /docs/{docId}/tables. Modify metadata for existing tables. This endpoint is primarily useful for: Renaming tables (via the `tableId` field) Setting on-demand loading (via the `onDemand` field)

Modify columns of a table. PATCH /docs/{docId}/tables/{tableId}/columns.

Modify rows of a table. PATCH /docs/{docId}/tables/{tableId}/data. Deprecated in favor of `records` endpoints. We have no immediate plans to remove these endpoints, but consider `records` a better starting point for new projects. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Modify records of a table. PATCH /docs/{docId}/tables/{tableId}/records.

Unpin a document. PATCH /docs/{docId}/unpin. Remove the pinned status from a document. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Modify a webhook. PATCH /docs/{docId}/webhooks/{webhookId}. Update the configuration of an existing webhook, such as its URL, enabled state, or event types.

Modify an org. PATCH /orgs/{orgId}. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Change who has access to org. PATCH /orgs/{orgId}/access. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Modify a service account. PATCH /service-accounts/{saId}. This updates a service account's label, description or expiration date. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Modify a workspace. PATCH /workspaces/{workspaceId}. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Change who has access to workspace. PATCH /workspaces/{workspaceId}/access. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Create a document. POST /docs. A unified endpoint for creating documents. Can create an empty document, copy an existing document, or import a file. To create an empty unsaved document: provide no parameters To create an empty saved document: provide `workspaceId` To copy an existing document: provide `sourceDocumentId`, `workspaceId`, and `documentName` To import a file: use multipart/form-data with a file upload and optional `workspaceId` REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Apply a list of user actions. POST /docs/{docId}/apply. Apply a sequence of user actions to a document. This is a low-level endpoint for making batch changes using Grist's internal action format. Each action is an array where the first element is the action type. Common action types: `["AddRecord", tableId, rowId, {column: value}]` - Add a row (use null for auto-assigned rowId) `["UpdateRecord", tableId, rowId, {column: value}]` - Update a row `["RemoveRecord", tableId, rowId]` - Delete a row `["BulkAddRecord", tableId, [rowIds], {column: [values]}]` - Add multiple rows `["BulkUpdateRecord", tableId, [rowIds], {column: [values]}]` - Update multiple rows `["BulkRemoveRecord", tableId, [rowIds]]` - Delete multiple rows `["AddColumn", tableId, colId, {type,...}]` - Add a column `["RemoveColumn", tableId, colId]` - Remove a column `["RenameColumn", tableId, oldColId, newColId]` - Rename a column `["AddTable", tableId, [{id, type,...}]]` - Add a table `["RemoveTable", tableId]` - Remove a table REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Reassign document to appropriate worker. POST /docs/{docId}/assign. Administrative endpoint that checks if a document is assigned to the expected worker group and frees it for reassignment if not. Used for load balancing and maintenance operations. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Delete unused attachments from the document. POST /docs/{docId}/attachments/removeUnused. When an uploaded attachment is no longer used in a Grist document, it's retained for a period of time in case it's needed again (e.g. to facilitate an "undo"). This removes all of these retained attachments, reducing the amount of storage used. This is particularly useful if a document has hit its attachment storage limit. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Set external store. POST /docs/{docId}/attachments/store. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Start transferring attachments. POST /docs/{docId}/attachments/transferAll. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Update attachment usage tracking. POST /docs/{docId}/attachments/updateUsed. Recalculate which attachments are in use by scanning the document. This is mostly used for testing and maintenance. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Verify attachment file integrity. POST /docs/{docId}/attachments/verifyFiles. Verify that attachment records match the actual stored files. This is a maintenance endpoint to check for data consistency. Only document owners can call this endpoint. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Copies a document to a workspace.. POST /docs/{docId}/copy. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Disable a document.. POST /docs/{docId}/disable. Disabled documents cannot be accessed or modified. Moving and renaming a disabled doc is also forbidden, as well as accessing or submitting published forms associated to a disabled document. Disabled documents, however, can be moved to and restored from the trash. The operation is non-destructive. Disabled documents can be re-enabled. Only admin accounts can disable a document. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Enable a document.. POST /docs/{docId}/enable. If a document has been previously disabled, this will restore all former access to a document, including access to its associated published forms. Only admin accounts can enable a document. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Flush document to storage. POST /docs/{docId}/flush. Ensure all pending changes to the document are written to persistent storage. Returns true if the document was flushed, false if the document was not open. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Reload a document. POST /docs/{docId}/force-reload. Closes and reopens the document, forcing the python engine to restart. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Fork a document. POST /docs/{docId}/fork. Create a fork of a document. A fork is a personal copy that tracks its relationship to the original document. Forks can be used to experiment with changes before applying them to the original. The fork will have a new docId and urlId that encode the relationship to the trunk (original) document. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Apply a change proposal. POST /docs/{docId}/proposals/{proposalId}/apply. Apply a proposal's changes to the document. This merges the fork's changes into the trunk document. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Create a change proposal. POST /docs/{docId}/propose. Create a proposal from a fork to its trunk document. The proposal contains the comparison of changes between the fork and trunk. This endpoint can only be called on a fork document. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Set recovery mode for a document. POST /docs/{docId}/recover. Controls the recovery mode of a document. Recovery mode helps in recovering from errors or corrupted states. Only document owners can control recovery mode. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Move document to trash. POST /docs/{docId}/remove. Soft-delete the document by moving it to trash. The document can be restored using the unremove endpoint. If the `permanent` query parameter is set to true, the document is permanently deleted instead. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Replace document content. POST /docs/{docId}/replace. Replace the current document content with content from another source. Can restore from a snapshot or copy from another document. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Remove document snapshots. POST /docs/{docId}/snapshots/remove. Remove specific snapshots from a document's backup history. Only document owners can remove snapshots. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Run an SQL query against a document, with options or parameters. POST /docs/{docId}/sql. Execute a read-only SQL SELECT query with support for parameterized queries and custom timeouts. All Grist documents are SQLite databases, and queries are executed directly against SQLite with security restrictions. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Truncate the document's action history. POST /docs/{docId}/states/remove. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Add tables to a document. POST /docs/{docId}/tables.

Add columns to a table. POST /docs/{docId}/tables/{tableId}/columns.

Add rows to a table. POST /docs/{docId}/tables/{tableId}/data. Deprecated in favor of `records` endpoints. We have no immediate plans to remove these endpoints, but consider `records` a better starting point for new projects. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Delete rows of a table. POST /docs/{docId}/tables/{tableId}/data/delete. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Add records to a table. POST /docs/{docId}/tables/{tableId}/records.

Delete records of a table. POST /docs/{docId}/tables/{tableId}/records/delete.

Start formula timing. POST /docs/{docId}/timing/start. Start collecting timing information for formula calculations. Only document owners can start timing. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Stop formula timing. POST /docs/{docId}/timing/stop. Stop collecting timing information and return the collected data. Only document owners can stop timing. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Restore document from trash. POST /docs/{docId}/unremove. Recover a document that was previously soft-deleted. Only works if the document is still in the trash. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Create new webhooks for a document. POST /docs/{docId}/webhooks. Creates one or more webhooks that will POST to specified URLs when data in the document changes. Returns the IDs of the created webhooks.

Create an empty workspace. POST /orgs/{orgId}/workspaces. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Create or regenerate API key. POST /profile/apikey. Create a new API key or regenerate an existing one. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Update user's locale. POST /profile/user/locale. Update the locale preference for the current user. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Update user's name. POST /profile/user/name. Update the display name for the current user. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Create a service account. POST /service-accounts. This creates a new service account with a new API key. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Generate a new service account's api key. POST /service-accounts/{saId}/apikey. This renews an api key of a given service account. Useful especially to change the API key when it has been leaked. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Set active user for organization. POST /session/access/active. Switch which user account is active for a given organization. Useful when a user has multiple accounts logged in. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Disable a user. POST /users/{userId}/disable. A disabled user can not log in and loses access to all pages, including public ones, as well as API access. The operation is non-destructive. Disabled users can be re-enabled. Only admin accounts can disable a user. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Enable a user. POST /users/{userId}/enable. If a user has been disabled, this will restore their access, including API access. Only admin accounts can enable a user. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Create an empty document. POST /workspaces/{workspaceId}/docs.

Move workspace to trash. POST /workspaces/{workspaceId}/remove. Soft-delete the workspace by moving it to trash. The workspace can be restored using the unremove endpoint. If the `permanent` query parameter is set to true, the workspace is permanently deleted instead. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Restore workspace from trash. POST /workspaces/{workspaceId}/unremove. Recover a workspace that was previously soft-deleted. Only works if the workspace is still in the trash. REQUIRES AN API-KEY CONNECTION: Grist's OAuth tokens do not reach this endpoint.

Add or update columns of a table. PUT /docs/{docId}/tables/{tableId}/columns.

Add or update records of a table. PUT /docs/{docId}/tables/{tableId}/records.