Skip to content

Grist API Reference#

REST API for manipulating documents, workspaces, and team sites.

  • API Usage is an introduction to using the API.
  • API Console allows you to make API calls from the browser.
API docs by Redocly

Grist API (1.0.1)

An API for manipulating Grist sites, workspaces, and documents.

Authentication

ApiKey

Access to the Grist API is controlled by an Authorization header, which should contain the word 'Bearer', followed by a space, followed by your API key.

Security Scheme Type: HTTP
HTTP Authorization Scheme: bearer
Bearer format: Authorization: Bearer XXXXXXXXXXX

orgs

Team sites and personal spaces are called 'orgs' in the API.

List the orgs you have access to

This enumerates all the team sites or personal areas available.

Authorizations:
ApiKey

Responses

Response samples

Content type
application/json
[
  • {
    • "id": 42,
    • "name": "Grist Labs",
    • "domain": "gristlabs",
    • "owner": {
      • "id": 101,
      • "name": "Helga Hufflepuff",
      • "picture": null
      },
    • "access": "owners",
    • "createdAt": "2019-09-13T15:42:35.000Z",
    • "updatedAt": "2019-09-13T15:42:35.000Z"
    }
]

Describe an org

Authorizations:
ApiKey
path Parameters
required
integer or string

This can be an integer id, or a string subdomain (e.g. gristlabs), or current if the org is implied by the domain in the url

Responses

Response samples

Content type
application/json
{
  • "id": 42,
  • "name": "Grist Labs",
  • "domain": "gristlabs",
  • "owner": {
    • "id": 101,
    • "name": "Helga Hufflepuff",
    • "picture": null
    },
  • "access": "owners",
  • "createdAt": "2019-09-13T15:42:35.000Z",
  • "updatedAt": "2019-09-13T15:42:35.000Z"
}

Modify an org

Authorizations:
ApiKey
path Parameters
required
integer or string

This can be an integer id, or a string subdomain (e.g. gristlabs), or current if the org is implied by the domain in the url

Request Body schema: application/json

the changes to make

name
string

Responses

Request samples

Content type
application/json
{
  • "name": "ACME Unlimited"
}

Delete an org

Authorizations:
ApiKey
path Parameters
required
integer or string

This can be an integer id, or a string subdomain (e.g. gristlabs), or current if the org is implied by the domain in the url

name
required
string

The organization name

Responses

List users with access to org

Authorizations:
ApiKey
path Parameters
required
integer or string

This can be an integer id, or a string subdomain (e.g. gristlabs), or current if the org is implied by the domain in the url

Responses

Response samples

Content type
application/json
{
  • "users": [
    • {
      • "id": 1,
      • "name": "Andrea",
      • "email": "andrea@getgrist.com",
      • "access": "owners"
      }
    ]
}

Change who has access to org

Authorizations:
ApiKey
path Parameters
required
integer or string

This can be an integer id, or a string subdomain (e.g. gristlabs), or current if the org is implied by the domain in the url

Request Body schema: application/json

the changes to make

required
object (OrgAccessWrite)

Responses

Request samples

Content type
application/json
{
  • "delta": {
    • "users": {
      • "foo@getgrist.com": "owners",
      • "bar@getgrist.com": null
      }
    }
}

Get organization usage summary

Get usage statistics for all non-deleted documents in the organization. Only accessible to organization owners.

Authorizations:
ApiKey
path Parameters
required
integer or string

This can be an integer id, or a string subdomain (e.g. gristlabs), or current if the org is implied by the domain in the url

Responses

Response samples

Content type
application/json
{
  • "countsByDataLimitStatus": {
    • "approachingLimit": 0,
    • "gracePeriod": 0,
    • "deleteOnly": 0
    },
  • "attachments": {
    • "totalBytes": 0,
    • "limitExceeded": true
    }
}

workspaces

Sites can be organized into groups of documents called workspaces.

List workspaces and documents within an org

Authorizations:
ApiKey
path Parameters
required
integer or string

This can be an integer id, or a string subdomain (e.g. gristlabs), or current if the org is implied by the domain in the url

Responses

Response samples

Content type
application/json
[
  • {
    • "id": 97,
    • "name": "Secret Plans",
    • "access": "owners",
    • "docs": [
      • {
        • "id": 145,
        • "name": "Project Lollipop",
        • "access": "owners",
        • "isPinned": true,
        • "urlId": null
        }
      ],
    • "orgDomain": "gristlabs"
    }
]

Create an empty workspace

Authorizations:
ApiKey
path Parameters
required
integer or string

This can be an integer id, or a string subdomain (e.g. gristlabs), or current if the org is implied by the domain in the url

Request Body schema: application/json

settings for the workspace

name
string

Responses

Request samples

Content type
application/json
{
  • "name": "Retreat Docs"
}

Response samples

Content type
application/json
155

Describe a workspace

Authorizations:
ApiKey
path Parameters
workspaceId
required
integer

An integer id

Responses

Response samples

Content type
application/json
{
  • "id": 97,
  • "name": "Secret Plans",
  • "access": "owners",
  • "docs": [
    • {
      • "id": 145,
      • "name": "Project Lollipop",
      • "access": "owners",
      • "isPinned": true,
      • "urlId": null
      }
    ],
  • "org": {
    • "id": 42,
    • "name": "Grist Labs",
    • "domain": "gristlabs",
    • "owner": {
      • "id": 101,
      • "name": "Helga Hufflepuff",
      • "picture": null
      },
    • "access": "owners",
    • "createdAt": "2019-09-13T15:42:35.000Z",
    • "updatedAt": "2019-09-13T15:42:35.000Z"
    }
}

Modify a workspace

Authorizations:
ApiKey
path Parameters
workspaceId
required
integer

An integer id

Request Body schema: application/json

the changes to make

name
string

Responses

Request samples

Content type
application/json
{
  • "name": "Retreat Docs"
}

Delete a workspace

Authorizations:
ApiKey
path Parameters
workspaceId
required
integer

An integer id

Responses

Move workspace to trash

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.

Authorizations:
ApiKey
path Parameters
workspaceId
required
integer

An integer id

query Parameters
permanent
boolean

If true, permanently delete instead of moving to trash

Responses

Restore workspace from trash

Recover a workspace that was previously soft-deleted. Only works if the workspace is still in the trash.

Authorizations:
ApiKey
path Parameters
workspaceId
required
integer

An integer id

Responses

List users with access to workspace

Authorizations:
ApiKey
path Parameters
workspaceId
required
integer

An integer id

Responses

Response samples

Content type
application/json
{
  • "maxInheritedRole": "owners",
  • "users": [
    • {
      • "id": 1,
      • "name": "Andrea",
      • "email": "andrea@getgrist.com",
      • "access": "owners",
      • "parentAccess": "owners"
      }
    ]
}

Change who has access to workspace

Authorizations:
ApiKey
path Parameters
workspaceId
required
integer

An integer id

Request Body schema: application/json

the changes to make

required
object (WorkspaceAccessWrite)

Responses

Request samples

Content type
application/json
{
  • "delta": {
    • "maxInheritedRole": "owners",
    • "users": {
      • "foo@getgrist.com": "owners",
      • "bar@getgrist.com": null
      }
    }
}

docs

Workspaces contain collections of Grist documents.

Create an empty document

Authorizations:
ApiKey
path Parameters
workspaceId
required
integer

An integer id

Request Body schema: application/json

settings for the document

name
string
isPinned
boolean

Responses

Request samples

Content type
application/json
{
  • "name": "Competitive Analysis",
  • "isPinned": false
}

Response samples

Content type
application/json
"9PJhBDZPyCNoayZxaCwFfS"

Import an existing document

Authorizations:
ApiKey
path Parameters
workspaceId
required
integer

An integer id

Request Body schema: multipart/form-data

settings for the document

upload
string <binary>

Contents of a .grist file, as a standard multipart/form-data file entry

documentName
string

Responses

Response samples

Content type
application/json
{
  • "id": "9PJhBDZPyCNoayZxaCwFfS"
}

Create a document

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
Authorizations:
ApiKey
Request Body schema:

settings for the document

workspaceId
integer

The workspace to save the document in. If omitted, creates an unsaved document.

documentName
string

Name for the new document (required when copying)

sourceDocumentId
string

ID of document to copy from. Requires workspaceId and documentName.

asTemplate
boolean

When copying, if true, copy structure only without data

timezone
string

Timezone for the document

Responses

Request samples

Content type
{
  • "workspaceId": 97,
  • "documentName": "My Document",
  • "sourceDocumentId": "mNnQ2PXndhXm",
  • "asTemplate": false,
  • "timezone": "America/New_York"
}

Response samples

Content type
application/json
"9PJhBDZPyCNoayZxaCwFfS"

Describe a document

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

Responses

Response samples

Content type
application/json
{
  • "id": 145,
  • "name": "Project Lollipop",
  • "access": "owners",
  • "isPinned": true,
  • "urlId": null,
  • "workspace": {
    • "id": 97,
    • "name": "Secret Plans",
    • "access": "owners",
    • "org": {
      • "id": 42,
      • "name": "Grist Labs",
      • "domain": "gristlabs",
      • "owner": {
        • "id": 101,
        • "name": "Helga Hufflepuff",
        • "picture": null
        },
      • "access": "owners",
      • "createdAt": "2019-09-13T15:42:35.000Z",
      • "updatedAt": "2019-09-13T15:42:35.000Z"
      }
    }
}

Modify document metadata (but not its contents)

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

Request Body schema: application/json

the changes to make

name
string
isPinned
boolean

Responses

Request samples

Content type
application/json
{
  • "name": "Competitive Analysis",
  • "isPinned": false
}

Delete a document

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

Responses

Move document to trash

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.

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

query Parameters
permanent
boolean

If true, permanently delete instead of moving to trash

Responses

Restore document from trash

Recover a document that was previously soft-deleted. Only works if the document is still in the trash.

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

Responses

Move document to another workspace.

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

Request Body schema: application/json

the target workspace

workspace
required
integer

Responses

Request samples

Content type
application/json
{
  • "workspace": 597
}

Pin a document

Pin the document so it appears in a prominent location. Pinned documents are displayed at the top of workspace listings for easy access.

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

Responses

Unpin a document

Remove the pinned status from a document.

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

Responses

Disable a document.

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.

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

Responses

Enable a document.

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.

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

Responses

Copies a document to a workspace.

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

Request Body schema: application/json

the target workspace

workspaceId
required
integer
documentName
required
string
asTemplate
boolean

Remove all data and history but keep the structure to use the document as a template

Responses

Request samples

Content type
application/json
{
  • "workspaceId": 597,
  • "documentName": "Example Doc",
  • "asTemplate": true
}

Response samples

Content type
application/json
"145"

Fork a document

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.

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

Responses

Response samples

Content type
application/json
{
  • "forkId": "abc123",
  • "docId": "XXXXX~abc123",
  • "urlId": "UUUUU~abc123"
}

List users with access to document

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

Responses

Response samples

Content type
application/json
{
  • "maxInheritedRole": "owners",
  • "users": [
    • {
      • "id": 1,
      • "name": "Andrea",
      • "email": "andrea@getgrist.com",
      • "access": "owners",
      • "parentAccess": "owners"
      }
    ]
}

Change who has access to document

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

Request Body schema: application/json

the changes to make

required
object (DocAccessWrite)

Responses

Request samples

Content type
application/json
{
  • "delta": {
    • "maxInheritedRole": "owners",
    • "users": {
      • "foo@getgrist.com": "owners",
      • "bar@getgrist.com": null
      }
    }
}

Get users for 'View As' feature

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
Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

Responses

Response samples

Content type
application/json
{
  • "users": [
    • {
      • "id": 101,
      • "name": "Helga Hufflepuff",
      • "picture": null
      }
    ],
  • "attributeTableUsers": [
    • {
      • "id": 101,
      • "name": "Helga Hufflepuff",
      • "picture": null
      }
    ],
  • "exampleUsers": [
    • {
      • "id": 101,
      • "name": "Helga Hufflepuff",
      • "picture": null
      }
    ]
}

Content of document, as an Sqlite file

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

query Parameters
nohistory
boolean

Remove document history (can significantly reduce file size)

template
boolean

Remove all data and history but keep the structure to use the document as a template

Responses

Content of document, as an Excel file

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

query Parameters
header
string
Enum: "colId" "label"

Format for headers. Labels tend to be more human-friendly while colIds are more normalized.

tableId
string

Name of a table (normalized).

Responses

Content of table, as a CSV file

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

query Parameters
tableId
required
string

Name of a table (normalized).

header
string
Enum: "colId" "label"

Format for headers. Labels tend to be more human-friendly while colIds are more normalized.

Responses

Content of table, as a TSV file

Download table data as tab-separated values.

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

query Parameters
tableId
required
string

Name of a table (normalized).

header
string
Enum: "colId" "label"

Format for headers. Labels tend to be more human-friendly while colIds are more normalized.

Responses

Content of table, as a DSV file

Download table data using a custom delimiter (💩).

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

query Parameters
tableId
required
string

Name of a table (normalized).

header
string
Enum: "colId" "label"

Format for headers. Labels tend to be more human-friendly while colIds are more normalized.

Responses

The schema of a table

The schema follows frictionlessdata's table-schema standard.

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

query Parameters
tableId
required
string

Name of a table (normalized).

header
string
Enum: "colId" "label"

Format for headers. Labels tend to be more human-friendly while colIds are more normalized.

Responses

Response samples

Content type
text/json
{
  • "name": "string",
  • "title": "string",
  • "path": "https://getgrist.com/o/docs/api/docs/ID/download/csv?tableId=Table1&....",
  • "format": "csv",
  • "mediatype": "text/csv",
  • "encoding": "utf-8",
  • "dialect": "{\n \"dialect\": {\n \"delimiter\": \";\"\n }\n}\n",
  • "schema": "{\n \"schema\": {\n \"fields\": [\n {\n \"name\": \"first_name\",\n \"type\": \"string\"\n \"constraints\": {\n \"required\": true\n }\n },\n {\n \"name\": \"age\",\n \"type\": \"integer\"\n },\n ],\n \"primaryKey\": [\n \"name\"\n ]\n }\n}\n"
}

List document 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.

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

query Parameters
raw
boolean

If true, returns all snapshots including those not in the snapshot inventory

Responses

Response samples

Content type
application/json
{
  • "snapshots": [
    • {
      • "snapshotId": "string",
      • "lastModified": "2019-08-24T14:15:22Z",
      • "docId": "string"
      }
    ]
}

Remove document snapshots

Remove specific snapshots from a document's backup history. Only document owners can remove snapshots.

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

Request Body schema: application/json
snapshotIds
Array of strings

List of snapshot IDs to remove

Responses

Request samples

Content type
application/json
{
  • "snapshotIds": [
    • "abc123",
    • "def456"
    ]
}

Response samples

Content type
application/json
{
  • "snapshotIds": [
    • "string"
    ]
}

Get document action history 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.

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

Responses

Response samples

Content type
application/json
{
  • "states": [
    • {
      • "n": 0,
      • "h": "string"
      }
    ]
}

Compare document versions

Compare two versions of the same document by their state hashes. Returns details about what changed between the versions.

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

query Parameters
left
string

Hash of the left version to compare (defaults to HEAD)

right
string

Hash of the right version to compare (defaults to HEAD)

maxRows
integer

Maximum number of row changes to include in details

Responses

Response samples

Content type
application/json
{
  • "left": {
    • "n": 0,
    • "h": "string"
    },
  • "right": {
    • "n": 0,
    • "h": "string"
    },
  • "parent": {
    • "n": 0,
    • "h": "string"
    },
  • "summary": "same",
  • "details": {
    • "leftChanges": { },
    • "rightChanges": { }
    }
}

Compare two documents

Compare this document with another document. Useful for comparing a fork with its trunk document.

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

docId2
required
string

ID of the document to compare with

query Parameters
detail
boolean

If true, include detailed change information

maxRows
integer

Maximum number of row changes to include

Responses

Response samples

Content type
application/json
{
  • "left": {
    • "n": 0,
    • "h": "string"
    },
  • "right": {
    • "n": 0,
    • "h": "string"
    },
  • "parent": {
    • "n": 0,
    • "h": "string"
    },
  • "summary": "same",
  • "details": {
    • "leftChanges": { },
    • "rightChanges": { }
    }
}

Truncate the document's action history

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

Request Body schema: application/json
keep
required
integer

The number of the latest history actions to keep

Request samples

Content type
application/json
{
  • "keep": 3
}

List change proposals

List proposals associated with a document. Proposals are suggested changes from forks that can be reviewed and applied to the trunk document.

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

query Parameters
outgoing
boolean

If true, list proposals where this document is the source. Otherwise list proposals where this document is the destination.

Responses

Response samples

Content type
application/json
{
  • "proposals": [
    • {
      • "id": 0,
      • "srcDocId": "string",
      • "destDocId": "string",
      • "retracted": true,
      • "comparison": {
        • "left": {
          • "n": 0,
          • "h": "string"
          },
        • "right": {
          • "n": 0,
          • "h": "string"
          },
        • "parent": {
          • "n": 0,
          • "h": "string"
          },
        • "summary": "same",
        • "details": {
          • "leftChanges": { },
          • "rightChanges": { }
          }
        }
      }
    ]
}

Create a change proposal

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.

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

Request Body schema: application/json
retracted
boolean
Default: false

Set to true to retract an existing proposal

Responses

Request samples

Content type
application/json
{
  • "retracted": false
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "comparison": {
    • "left": {
      • "n": 0,
      • "h": "string"
      },
    • "right": {
      • "n": 0,
      • "h": "string"
      },
    • "parent": {
      • "n": 0,
      • "h": "string"
      },
    • "summary": "same",
    • "details": {
      • "leftChanges": { },
      • "rightChanges": { }
      }
    }
}

Apply a change proposal

Apply a proposal's changes to the document. This merges the fork's changes into the trunk document.

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

proposalId
required
integer

ID of the proposal to apply

Responses

Response samples

Content type
application/json
{
  • "proposalId": 0,
  • "changes": { }
}

Reload a document

Closes and reopens the document, forcing the python engine to restart.

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

Responses

Flush document to storage

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.

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

Responses

Response samples

Content type
application/json
true

Reassign document to appropriate worker

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.

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

query Parameters
group
string

Update the document's worker group (requires special permit)

Responses

Response samples

Content type
application/json
true

Replace document content

Replace the current document content with content from another source. Can restore from a snapshot or copy from another document.

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

Request Body schema: application/json
sourceDocId
string

ID of document to copy content from

snapshotId
string

ID of snapshot to restore from

resetTutorialMetadata
boolean

Reset tutorial progress when replacing (for tutorial forks)

Responses

Request samples

Content type
application/json
{
  • "sourceDocId": "string",
  • "snapshotId": "string",
  • "resetTutorialMetadata": true
}

Set recovery mode for a document

Controls the recovery mode of a document. Recovery mode helps in recovering from errors or corrupted states. Only document owners can control recovery mode.

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

Request Body schema: application/json

Recovery mode settings

recoveryMode
boolean

Whether to enable recovery mode. Defaults to true if not specified.

Responses

Request samples

Content type
application/json
{
  • "recoveryMode": true
}

Response samples

Content type
application/json
{
  • "recoveryMode": true
}

Get formula timing status

Check if formula timing is enabled for a document and retrieve timing data if available. Only document owners can access timing information.

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

Responses

Response samples

Content type
application/json
{
  • "status": "disabled",
  • "timing": { }
}

Start formula timing

Start collecting timing information for formula calculations. Only document owners can start timing.

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

Responses

Stop formula timing

Stop collecting timing information and return the collected data. Only document owners can stop timing.

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

Responses

Response samples

Content type
application/json
{ }

Apply a list of user actions

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
Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

query Parameters
noparse
boolean

If true, string values are stored as-is without parsing (e.g. dates won't be auto-converted)

Request Body schema: application/json

An array of user actions to apply

Array
arrays

Responses

Request samples

Content type
application/json
[
  • [
    • "AddRecord",
    • "People",
    • null,
    • {
      • "Name": "Alice",
      • "Age": 30
      }
    ],
  • [
    • "UpdateRecord",
    • "People",
    • 1,
    • {
      • "Age": 31
      }
    ]
]

Response samples

Content type
application/json
{
  • "actionNum": 0,
  • "retValues": [ ]
}

records

Tables contain collections of records (also called rows).

Fetch records from a table

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

tableId
required
string

normalized table name (see TABLE ID in Raw Data) or numeric row ID in _grist_Tables

query Parameters
filter
string
Example: filter={"pet": ["cat", "dog"]}

This is a JSON object mapping column names to arrays of allowed values. For example, to filter column pet for values cat and dog, the filter would be {"pet": ["cat", "dog"]}. JSON contains characters that are not safe to place in a URL, so it is important to url-encode them. For this example, the url-encoding is %7B%22pet%22%3A%20%5B%22cat%22%2C%20%22dog%22%5D%7D. See https://rosettacode.org/wiki/URL_encoding for how to url-encode a string, or https://www.urlencoder.org/ to try some examples. Multiple columns can be filtered. For example the filter for pet being either cat or dog, AND size being either tiny or outrageously small, would be {"pet": ["cat", "dog"], "size": ["tiny", "outrageously small"]}.

sort
string
Example: sort=pet,-age

Order in which to return results. If a single column name is given (e.g. pet), results are placed in ascending order of values in that column. To get results in an order that was previously prepared manually in Grist, use the special manualSort column name. Multiple columns can be specified, separated by commas (e.g. pet,age). For descending order, prefix a column name with a - character (e.g. pet,-age). To include additional sorting options append them after a colon (e.g. pet,-age:naturalSort;emptyFirst,owner). Available options are: choiceOrder, naturalSort, emptyFirst. Without the sort parameter, the order of results is unspecified.

limit
number
Example: limit=5

Return at most this number of rows. A value of 0 is equivalent to having no limit.

hidden
boolean

Set to true to include the hidden columns (like "manualSort")

header Parameters
X-Sort
string
Example: pet,-age

Same as sort query parameter.

X-Limit
number
Example: 5

Same as limit query parameter.

Responses

Response samples

Content type
application/json
{
  • "records": [
    • {
      • "id": 1,
      • "fields": {
        • "pet": "cat",
        • "popularity": 67
        }
      },
    • {
      • "id": 2,
      • "fields": {
        • "pet": "dog",
        • "popularity": 95
        }
      }
    ]
}

Add records to a table

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

tableId
required
string

normalized table name (see TABLE ID in Raw Data) or numeric row ID in _grist_Tables

query Parameters
noparse
boolean

Set to true to prohibit parsing strings according to the column type.

Request Body schema: application/json

the records to add

required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "records": [
    • {
      • "fields": {
        • "pet": "cat",
        • "popularity": 67
        }
      },
    • {
      • "fields": {
        • "pet": "dog",
        • "popularity": 95
        }
      }
    ]
}

Response samples

Content type
application/json
{
  • "records": [
    • {
      • "id": 1
      },
    • {
      • "id": 2
      }
    ]
}

Modify records of a table

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

tableId
required
string

normalized table name (see TABLE ID in Raw Data) or numeric row ID in _grist_Tables

query Parameters
noparse
boolean

Set to true to prohibit parsing strings according to the column type.

Request Body schema: application/json

the records to change, with ids

required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "records": [
    • {
      • "id": 1,
      • "fields": {
        • "pet": "cat",
        • "popularity": 67
        }
      },
    • {
      • "id": 2,
      • "fields": {
        • "pet": "dog",
        • "popularity": 95
        }
      }
    ]
}

Add or update records of a table

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

tableId
required
string

normalized table name (see TABLE ID in Raw Data) or numeric row ID in _grist_Tables

query Parameters
noparse
boolean

Set to true to prohibit parsing strings according to the column type.

onmany
string
Enum: "first" "none" "all"

Which records to update if multiple records are found to match require.

  • first - the first matching record (default)
  • none - do not update anything
  • all - update all matches
noadd
boolean

Set to true to prohibit adding records.

noupdate
boolean

Set to true to prohibit updating records.

allow_empty_require
boolean

Set to true to allow require in the body to be empty, which will match and update all records in the table.

Request Body schema: application/json

The records to add or update. Instead of an id, a require object is provided, with the same structure as fields. If no query parameter options are set, then the operation is as follows. First, we check if a record exists matching the values specified for columns in require. If so, we update it by setting the values specified for columns in fields. If not, we create a new record with a combination of the values in require and fields, with fields taking priority if the same column is specified in both. The query parameters allow for variations on this behavior.

required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "records": [
    • {
      • "require": {
        • "pet": "cat"
        },
      • "fields": {
        • "popularity": 67
        }
      },
    • {
      • "require": {
        • "pet": "dog"
        },
      • "fields": {
        • "popularity": 95
        }
      }
    ]
}

Delete records of a table

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

tableId
required
string

normalized table name (see TABLE ID in Raw Data) or numeric row ID in _grist_Tables

Request Body schema: application/json

the IDs of records to remove

Array
integer

Responses

Request samples

Content type
application/json
[
  • 101,
  • 102,
  • 103
]

tables

Documents are structured as a collection of tables.

List tables in a document

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

Responses

Response samples

Content type
application/json
{
  • "tables": [
    • {
      • "id": "People",
      • "fields": {
        • "tableRef": 1,
        • "onDemand": false
        }
      },
    • {
      • "id": "Places",
      • "fields": {
        • "tableRef": 2,
        • "onDemand": false
        }
      }
    ]
}

Add tables to a document

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

Request Body schema: application/json

the tables to add

required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "tables": [
    • {
      • "id": "People",
      • "columns": [
        • {
          • "id": "pet",
          • "fields": {
            • "label": "Pet"
            }
          },
        • {
          • "id": "popularity",
          • "fields": {
            • "label": "Popularity ❤"
            }
          }
        ]
      }
    ]
}

Response samples

Content type
application/json
{
  • "tables": [
    • {
      • "id": "People"
      },
    • {
      • "id": "Places"
      }
    ]
}

Modify tables of a document

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)
Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

Request Body schema: application/json

the tables to modify, identified by their current id

required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "tables": [
    • {
      • "id": "People",
      • "fields": {
        • "tableId": "Persons"
        }
      },
    • {
      • "id": "Places",
      • "fields": {
        • "onDemand": true
        }
      }
    ]
}

columns

Tables are structured as a collection of columns.

List columns in a table

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

tableId
required
string

normalized table name (see TABLE ID in Raw Data) or numeric row ID in _grist_Tables

query Parameters
hidden
boolean

Set to true to include the hidden columns (like "manualSort")

Responses

Response samples

Content type
application/json
{
  • "columns": [
    • {
      • "id": "pet",
      • "fields": {
        • "label": "Pet"
        }
      },
    • {
      • "id": "popularity",
      • "fields": {
        • "label": "Popularity ❤",
        • "type": "Int"
        }
      }
    ]
}

Add columns to a table

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

tableId
required
string

normalized table name (see TABLE ID in Raw Data) or numeric row ID in _grist_Tables

Request Body schema: application/json

the columns to add

required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "columns": [
    • {
      • "id": "pet",
      • "fields": {
        • "label": "Pet"
        }
      },
    • {
      • "id": "popularity",
      • "fields": {
        • "label": "Popularity ❤",
        • "type": "Int"
        }
      },
    • {
      • "id": "Order",
      • "fields": {
        • "type": "Ref:Orders",
        • "visibleCol": 2
        }
      },
    • {
      • "id": "Formula",
      • "fields": {
        • "type": "Int",
        • "formula": "$A + $B",
        • "isFormula": true
        }
      },
    • {
      • "id": "Status",
      • "fields": {
        • "type": "Choice",
        • "widgetOptions": "{\"choices\":[\"New\",\"Old\"],\"choiceOptions\":{\"New\":{\"fillColor\":\"#FF0000\",\"textColor\":\"#FFFFFF\"}}}"
        }
      }
    ]
}

Response samples

Content type
application/json
{
  • "columns": [
    • {
      • "id": "pet"
      },
    • {
      • "id": "popularity"
      }
    ]
}

Modify columns of a table

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

tableId
required
string

normalized table name (see TABLE ID in Raw Data) or numeric row ID in _grist_Tables

Request Body schema: application/json

the columns to change, with ids

required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "columns": [
    • {
      • "id": "pet",
      • "fields": {
        • "label": "Pet"
        }
      },
    • {
      • "id": "popularity",
      • "fields": {
        • "label": "Popularity ❤",
        • "type": "Int"
        }
      }
    ]
}

Add or update columns of a table

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

tableId
required
string

normalized table name (see TABLE ID in Raw Data) or numeric row ID in _grist_Tables

query Parameters
noadd
boolean

Set to true to prohibit adding columns.

noupdate
boolean

Set to true to prohibit updating columns.

replaceall
boolean

Set to true to remove existing columns (except the hidden ones) that are not specified in the request body.

Request Body schema: application/json

The columns to add or update. We check whether the specified column ID exists: if so, the column is updated with the provided data, otherwise a new column is created. Also note that some query parameters alter this behavior.

required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "columns": [
    • {
      • "id": "pet",
      • "fields": {
        • "label": "Pet"
        }
      },
    • {
      • "id": "popularity",
      • "fields": {
        • "label": "Popularity ❤",
        • "type": "Int"
        }
      }
    ]
}

Delete a column of a table

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

tableId
required
string

normalized table name (see TABLE ID in Raw Data) or numeric row ID in _grist_Tables

colId
required
string

The column id (without the starting $) as shown in the column configuration below the label

Responses

data

Work with table data, using a (now deprecated) columnar format. We now recommend the records endpoints.

Fetch data from a table Deprecated

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.

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

tableId
required
string

normalized table name (see TABLE ID in Raw Data) or numeric row ID in _grist_Tables

query Parameters
filter
string
Example: filter={"pet": ["cat", "dog"]}

This is a JSON object mapping column names to arrays of allowed values. For example, to filter column pet for values cat and dog, the filter would be {"pet": ["cat", "dog"]}. JSON contains characters that are not safe to place in a URL, so it is important to url-encode them. For this example, the url-encoding is %7B%22pet%22%3A%20%5B%22cat%22%2C%20%22dog%22%5D%7D. See https://rosettacode.org/wiki/URL_encoding for how to url-encode a string, or https://www.urlencoder.org/ to try some examples. Multiple columns can be filtered. For example the filter for pet being either cat or dog, AND size being either tiny or outrageously small, would be {"pet": ["cat", "dog"], "size": ["tiny", "outrageously small"]}.

sort
string
Example: sort=pet,-age

Order in which to return results. If a single column name is given (e.g. pet), results are placed in ascending order of values in that column. To get results in an order that was previously prepared manually in Grist, use the special manualSort column name. Multiple columns can be specified, separated by commas (e.g. pet,age). For descending order, prefix a column name with a - character (e.g. pet,-age). To include additional sorting options append them after a colon (e.g. pet,-age:naturalSort;emptyFirst,owner). Available options are: choiceOrder, naturalSort, emptyFirst. Without the sort parameter, the order of results is unspecified.

limit
number
Example: limit=5

Return at most this number of rows. A value of 0 is equivalent to having no limit.

header Parameters
X-Sort
string
Example: pet,-age

Same as sort query parameter.

X-Limit
number
Example: 5

Same as limit query parameter.

Responses

Response samples

Content type
application/json
{
  • "id": [
    • 1,
    • 2
    ],
  • "pet": [
    • "cat",
    • "dog"
    ],
  • "popularity": [
    • 67,
    • 95
    ]
}

Add rows to a table Deprecated

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.

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

tableId
required
string

normalized table name (see TABLE ID in Raw Data) or numeric row ID in _grist_Tables

query Parameters
noparse
boolean

Set to true to prohibit parsing strings according to the column type.

Request Body schema: application/json

the data to add

property name*
additional property
Array of objects

Responses

Request samples

Content type
application/json
{
  • "pet": [
    • "cat",
    • "dog"
    ],
  • "popularity": [
    • 67,
    • 95
    ]
}

Response samples

Content type
application/json
[
  • 101,
  • 102,
  • 103
]

Modify rows of a table Deprecated

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.

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

tableId
required
string

normalized table name (see TABLE ID in Raw Data) or numeric row ID in _grist_Tables

query Parameters
noparse
boolean

Set to true to prohibit parsing strings according to the column type.

Request Body schema: application/json

the data to change, with ids

id
required
Array of integers
property name*
additional property
Array of objects

Responses

Request samples

Content type
application/json
{
  • "id": [
    • 1,
    • 2
    ],
  • "pet": [
    • "cat",
    • "dog"
    ],
  • "popularity": [
    • 67,
    • 95
    ]
}

Response samples

Content type
application/json
[
  • 101,
  • 102,
  • 103
]

Delete rows of a table Deprecated

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

tableId
required
string

normalized table name (see TABLE ID in Raw Data) or numeric row ID in _grist_Tables

Request Body schema: application/json

the IDs of rows to remove

Array
integer

Responses

Request samples

Content type
application/json
[
  • 101,
  • 102,
  • 103
]

attachments

Documents may include attached files. Data records can refer to these using a column of type Attachments.

List metadata of all attachments in a doc

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

query Parameters
filter
string
Example: filter={"pet": ["cat", "dog"]}

This is a JSON object mapping column names to arrays of allowed values. For example, to filter column pet for values cat and dog, the filter would be {"pet": ["cat", "dog"]}. JSON contains characters that are not safe to place in a URL, so it is important to url-encode them. For this example, the url-encoding is %7B%22pet%22%3A%20%5B%22cat%22%2C%20%22dog%22%5D%7D. See https://rosettacode.org/wiki/URL_encoding for how to url-encode a string, or https://www.urlencoder.org/ to try some examples. Multiple columns can be filtered. For example the filter for pet being either cat or dog, AND size being either tiny or outrageously small, would be {"pet": ["cat", "dog"], "size": ["tiny", "outrageously small"]}.

sort
string
Example: sort=pet,-age

Order in which to return results. If a single column name is given (e.g. pet), results are placed in ascending order of values in that column. To get results in an order that was previously prepared manually in Grist, use the special manualSort column name. Multiple columns can be specified, separated by commas (e.g. pet,age). For descending order, prefix a column name with a - character (e.g. pet,-age). To include additional sorting options append them after a colon (e.g. pet,-age:naturalSort;emptyFirst,owner). Available options are: choiceOrder, naturalSort, emptyFirst. Without the sort parameter, the order of results is unspecified.

limit
number
Example: limit=5

Return at most this number of rows. A value of 0 is equivalent to having no limit.

header Parameters
X-Sort
string
Example: pet,-age

Same as sort query parameter.

X-Limit
number
Example: 5

Same as limit query parameter.

Responses

Response samples

Content type
application/json
{
  • "records": [
    • {
      • "id": 1,
      • "fields": {
        • "fileName": "logo.png",
        • "fileSize": 12345,
        • "timeUploaded": "2020-02-13T12:17:19.000Z"
        }
      }
    ]
}

Upload attachments to a doc

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

Request Body schema: multipart/form-data

the files to add to the doc

upload
Array of strings <binary>

Responses

Response samples

Content type
application/json
[
  • 101,
  • 102,
  • 103
]

Get the metadata for an attachment

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

attachmentId
required
number (AttachmentId)

An integer ID

Responses

Response samples

Content type
application/json
{
  • "fileName": "logo.png",
  • "fileSize": 12345,
  • "timeUploaded": "2020-02-13T12:17:19.000Z"
}

Download the contents of an attachment

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

attachmentId
required
number (AttachmentId)

An integer ID

Responses

Download all attachments

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

query Parameters
format
string
Enum: "zip" "tar"

Responses

Upload missing attachments

Restores attachments which are missing from external storage.

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

Request Body schema: multipart/form-data

A .tar file downloaded from Grist, containing all the document's attachments.

file
string <binary>

The .tar file. Must have Content-Type=application/x-tar set.

Responses

Response samples

Content type
application/json
{
  • "added": 0,
  • "errored": 0,
  • "unused": 0
}

Get external store

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

Responses

Response samples

Content type
application/json
{
  • "type": "external"
}

Set external store

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

Request Body schema: application/json
type
string
Enum: "external" "internal"

Responses

Request samples

Content type
application/json
{
  • "type": "external"
}

Response samples

Content type
application/json
{
  • "store": "83395209-fc3b-4d02-8934-b2619efec712-filesystem"
}

List external attachment stores

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

Responses

Response samples

Content type
application/json
{
  • "type": "external"
}

Start transferring attachments

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

Responses

Response samples

Content type
application/json
{
  • "status": {
    • "pendingTransferCount": 19,
    • "isRunning": true
    },
  • "locationSummary": "mixed"
}

Get attachment transfer status

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

Responses

Response samples

Content type
application/json
{
  • "status": {
    • "pendingTransferCount": 19,
    • "isRunning": true
    },
  • "locationSummary": "mixed"
}

Delete unused attachments from the document

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.

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

query Parameters
expiredOnly
boolean

Only remove attachments that haven't been used for a period of time. This duration is set by host of the Grist instance.

Responses

Update attachment usage tracking

Recalculate which attachments are in use by scanning the document. This is mostly used for testing and maintenance.

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

Responses

Verify attachment file integrity

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.

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

Responses

webhooks

Document changes can trigger requests to URLs called webhooks.

Webhooks associated with a document

Returns all webhooks configured for this document, including their settings and delivery statistics.

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

Responses

Response samples

Content type
application/json
{
  • "webhooks": [
    • {
      • "id": "xxxxxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx",
      • "fields": {
        • "name": "new-project-email",
        • "memo": "Send an email when a project is added",
        • "url": "https://example.com/webhook/123",
        • "enabled": true,
        • "eventTypes": [
          • "add",
          • "update"
          ],
        • "isReadyColumn": null,
        • "tableId": "Projects",
        • "unsubscribeKey": "string"
        },
      • "usage": {
        • "numWaiting": 0,
        • "status": "idle",
        • "updatedTime": 1685637500424,
        • "lastSuccessTime": 1685637500424,
        • "lastFailureTime": 1685637500424,
        • "lastErrorMessage": null,
        • "lastHttpStatus": 200,
        • "lastEventBatch": {
          • "size": 1,
          • "attempts": 1,
          • "errorMessage": null,
          • "httpStatus": 200,
          • "status": "success"
          }
        }
      }
    ]
}

Create new webhooks for a document

Creates one or more webhooks that will POST to specified URLs when data in the document changes. Returns the IDs of the created webhooks.

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

Request Body schema: application/json

an array of webhook settings

required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "webhooks": [
    • {
      • "fields": {
        • "name": "new-project-email",
        • "memo": "Send an email when a project is added",
        • "url": "https://example.com/webhook/123",
        • "enabled": true,
        • "eventTypes": [
          • "add",
          • "update"
          ],
        • "isReadyColumn": null,
        • "tableId": "Projects"
        }
      }
    ]
}

Response samples

Content type
application/json
{
  • "webhooks": [
    • {
      • "id": "xxxxxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx"
      }
    ]
}

Modify a webhook

Update the configuration of an existing webhook, such as its URL, enabled state, or event types.

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

webhookId
required
string
Request Body schema: application/json

the changes to make

name
string or null
memo
string or null
url
string <uri>
enabled
boolean
eventTypes
Array of strings
isReadyColumn
string or null
tableId
string

Responses

Request samples

Content type
application/json
{
  • "name": "new-project-email",
  • "memo": "Send an email when a project is added",
  • "url": "https://example.com/webhook/123",
  • "enabled": true,
  • "eventTypes": [
    • "add",
    • "update"
    ],
  • "isReadyColumn": null,
  • "tableId": "Projects"
}

Remove a webhook

Permanently delete a webhook. Any pending deliveries in the queue for this webhook will also be removed.

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

webhookId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Empty a document's queue of undelivered payloads

Clear all pending webhook deliveries for this document. Use this if the queue has built up due to unreachable endpoints.

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

Responses

Clear queue for a specific webhook

Clear the queue of pending payloads for a specific webhook. Only document owners can call this endpoint.

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

webhookId
required
string

ID of the webhook

Responses

Response samples

Content type
application/json
{
  • "success": true
}

sql

Sql endpoint to query data from documents.

Run an SQL query against a document

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.

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

query Parameters
q
string

The SQL query to run. This GET endpoint is a simplified version of the corresponding POST endpoint, without support for parameters or options. See the POST endpoint for details of what's allowed in the SQL query string.

Responses

Response samples

Content type
application/json
{
  • "statement": "select * from Pets ...",
  • "records": [
    • {
      • "fields": {
        • "id": 1,
        • "pet": "cat",
        • "popularity": 67
        }
      },
    • {
      • "fields": {
        • "id": 2,
        • "pet": "dog",
        • "popularity": 95
        }
      }
    ]
}

Run an SQL query against a document, with options or parameters

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.

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

Request Body schema: application/json

Query options

sql
required
string

The SQL query to run. Must be a single SELECT statement, with no trailing semicolon. WITH clauses are permitted. All Grist documents are currently SQLite databases, and the SQL query is interpreted and run by SQLite, with various defensive measures. Statements that would modify the database are not supported.

Array of numbers or strings

Parameters for the query.

timeout
number

Timeout after which operations on the document will be interrupted. Specified in milliseconds. Defaults to 1000 (1 second). This default is controlled by an optional environment variable read by the Grist app, GRIST_SQL_TIMEOUT_MSEC. The default cannot be exceeded, only reduced.

Responses

Request samples

Content type
application/json
{
  • "sql": "select * from Pets where popularity >= ?",
  • "args": [
    • 50
    ],
  • "timeout": 500
}

Response samples

Content type
application/json
{
  • "statement": "select * from Pets ...",
  • "records": [
    • {
      • "fields": {
        • "id": 1,
        • "pet": "cat",
        • "popularity": 67
        }
      },
    • {
      • "fields": {
        • "id": 2,
        • "pet": "dog",
        • "popularity": 95
        }
      }
    ]
}

users

Grist users.

Delete a user from Grist

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 ⚠️

Authorizations:
ApiKey
path Parameters
userId
required
integer

A user id

Request Body schema: application/json
name
required
string

The user's name to delete (for confirmation, to avoid deleting the wrong account).

Responses

Request samples

Content type
application/json
{
  • "name": "John Doe"
}

Disable a user

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.

Authorizations:
ApiKey
path Parameters
userId
required
integer

A user id

Responses

Enable a user

If a user has been disabled, this will restore their access, including API access.

Only admin accounts can enable a user.

Authorizations:
ApiKey
path Parameters
userId
required
integer

A user id

Responses

service accounts

Impersonations to manage grist resources through REST APIs with specific rights.

Get all your service accounts

This lists all your service accounts with their details.

Authorizations:
ApiKey

Responses

Response samples

Content type
application/json
[
  • {
    • "id": 42,
    • "login": "aa52e4c7-e451-409a-8140-4eb17844e8b9@serviceaccounts.invalid",
    • "label": "n8n",
    • "description": "For data import workflow",
    • "expiresAt": "2042-10-10T00:00:00.000Z",
    • "hasValidKey": true
    }
]

Create a service account

This creates a new service account with a new API key.

Authorizations:
ApiKey
Request Body schema: application/json
label
string

The service account's display name

description
string

Description of service account's purpose

expiresAt
required
string

The service account's expiration date

Responses

Request samples

Content type
application/json
{
  • "label": "n8n",
  • "description": "For data update workflow",
  • "expiresAt": "2042-10-10"
}

Response samples

Content type
application/json
{
  • "id": 42,
  • "login": "aa52e4c7-e451-409a-8140-4eb17844e8b9@serviceaccounts.invalid",
  • "label": "n8n",
  • "description": "For data import workflow",
  • "expiresAt": "2042-10-10T00:00:00.000Z",
  • "hasValidKey": true,
  • "key": "1234567890abcdef"
}

Get a service account's details

This reports the details of a service account.

Authorizations:
ApiKey
path Parameters
saId
integer

A service account id

Responses

Response samples

Content type
application/json
{
  • "id": 42,
  • "login": "aa52e4c7-e451-409a-8140-4eb17844e8b9@serviceaccounts.invalid",
  • "label": "n8n",
  • "description": "For data import workflow",
  • "expiresAt": "2042-10-10T00:00:00.000Z",
  • "hasValidKey": true
}

Modify a service account

This updates a service account's label, description or expiration date.

Authorizations:
ApiKey
path Parameters
saId
integer

A service account id

Request Body schema: application/json
label
string

The service account's display name

description
string

Description of service account's purpose

expiresAt
string

The service account's expiration date

Responses

Request samples

Content type
application/json
{
  • "label": "n8n",
  • "description": "For data update workflow",
  • "expiresAt": "2042-10-10"
}

Delete a service account

This deletes a given service account.

Authorizations:
ApiKey
path Parameters
saId
integer

A service account id

Responses

Generate a new service account's api key

This renews an api key of a given service account. Useful especially to change the API key when it has been leaked.

Authorizations:
ApiKey
path Parameters
saId
integer

A service account id

Responses

Response samples

Content type
application/json
{
  • "id": 42,
  • "login": "aa52e4c7-e451-409a-8140-4eb17844e8b9@serviceaccounts.invalid",
  • "label": "n8n",
  • "description": "For data import workflow",
  • "expiresAt": "2042-10-10T00:00:00.000Z",
  • "hasValidKey": true,
  • "key": "1234567890abcdef"
}

Delete a service account's api key

Deletes the API key for a service account. The service account will no longer be able to authenticate until a new key is generated.

Authorizations:
ApiKey
path Parameters
saId
integer

A service account id

Responses

scim

SCIM

Retrieve list of users

Authorizations:
ApiKey
query Parameters
startIndex
integer
Example: startIndex=1

The starting index for pagination.

count
integer
Example: count=10

The number of resources to retrieve.

filter
string
Example: filter=displayName pr

Filter resources based on specific criteria.

Responses

Response samples

Content type
application/scim+json
{
  • "schemas": [
    • "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
  • "totalResults": 1,
  • "itemsPerPage": 20,
  • "startIndex": 1,
  • "Resources": [
    • {
      • "meta": {
        • "resourceType": "User",
        • "location": "/api/scim/v2/Users/1"
        },
      • "id": "1",
      • "schemas": [
        • "urn:ietf:params:scim:schemas:core:2.0:User"
        ],
      • "userName": "john.doe@example.com",
      • "name": {
        • "formatted": "John Doe"
        },
      • "emails": [
        • {
          • "value": "john.doe@example.com",
          • "primary": true
          }
        ],
      • "displayName": "John Doe",
      • "preferredLanguage": "en",
      • "locale": "en",
      • "photos": []
      }
    ]
}

Create a new user

Authorizations:
ApiKey
Request Body schema: application/scim+json

Data for the user to be created.

schemas
Array of strings
Items Value: "urn:ietf:params:scim:schemas:core:2.0:User"
userName
string

The unique username.

object
Array of objects
displayName
string

the display name of the user

preferredLanguage
string

Indicates the user's preferred written or spoken languages and is generally used for selecting a localized user interface.

locale
string

Used to indicate the User's default location for purposes of localizing such items as currency, date time format, or numerical representations.

Array of objects

The picture of the user. It is expected to have a single item in the context of Grist.

Responses

Request samples

Content type
application/scim+json
{
  • "schemas": [
    • "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
  • "userName": "john.doe@example.com",
  • "name": {
    • "formatted": "John Doe"
    },
  • "emails": [
    • {
      • "value": "john.doe@example.com",
      • "primary": true
      }
    ],
  • "displayName": "John Doe",
  • "preferredLanguage": "en",
  • "locale": "en",
  • "photos": []
}

Response samples

Content type
application/scim+json
{
  • "meta": {
    • "resourceType": "User",
    • "location": "/api/scim/v2/Users/1"
    },
  • "id": "1",
  • "schemas": [
    • "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
  • "userName": "john.doe@example.com",
  • "name": {
    • "formatted": "John Doe"
    },
  • "emails": [
    • {
      • "value": "john.doe@example.com",
      • "primary": true
      }
    ],
  • "displayName": "John Doe",
  • "preferredLanguage": "en",
  • "locale": "en",
  • "photos": []
}

Retrieve user by ID

Authorizations:
ApiKey
path Parameters
userId
required
integer

A user id

Responses

Response samples

Content type
application/scim+json
{
  • "meta": {
    • "resourceType": "User",
    • "location": "/api/scim/v2/Users/1"
    },
  • "id": "1",
  • "schemas": [
    • "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
  • "userName": "john.doe@example.com",
  • "name": {
    • "formatted": "John Doe"
    },
  • "emails": [
    • {
      • "value": "john.doe@example.com",
      • "primary": true
      }
    ],
  • "displayName": "John Doe",
  • "preferredLanguage": "en",
  • "locale": "en",
  • "photos": []
}

Update a user by ID

⚠️ This operation overwrites all the user's information. In order to pass only some properties to update, please use PATCH instead.

Authorizations:
ApiKey
path Parameters
userId
required
integer

A user id

Request Body schema: application/scim+json

Updated data for the user.

schemas
Array of strings
Items Value: "urn:ietf:params:scim:schemas:core:2.0:User"
userName
string

The unique username.

object
Array of objects
displayName
string

the display name of the user

preferredLanguage
string

Indicates the user's preferred written or spoken languages and is generally used for selecting a localized user interface.

locale
string

Used to indicate the User's default location for purposes of localizing such items as currency, date time format, or numerical representations.

Array of objects

The picture of the user. It is expected to have a single item in the context of Grist.

Responses

Request samples

Content type
application/scim+json
{
  • "schemas": [
    • "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
  • "userName": "john.doe@example.com",
  • "name": {
    • "formatted": "John Doe"
    },
  • "emails": [
    • {
      • "value": "john.doe@example.com",
      • "primary": true
      }
    ],
  • "displayName": "John Doe",
  • "preferredLanguage": "en",
  • "locale": "en",
  • "photos": []
}

Response samples

Content type
application/scim+json
{
  • "meta": {
    • "resourceType": "User",
    • "location": "/api/scim/v2/Users/1"
    },
  • "id": "1",
  • "schemas": [
    • "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
  • "userName": "john.doe@example.com",
  • "name": {
    • "formatted": "John Doe"
    },
  • "emails": [
    • {
      • "value": "john.doe@example.com",
      • "primary": true
      }
    ],
  • "displayName": "John Doe",
  • "preferredLanguage": "en",
  • "locale": "en",
  • "photos": []
}

Partially update a user by ID

Authorizations:
ApiKey
path Parameters
userId
required
integer

A user id

Request Body schema: application/scim+json

Data for the partial update of the user.

schemas
Array of strings
Items Value: "urn:ietf:params:scim:api:messages:2.0:PatchOp"
Array of objects

Responses

Request samples

Content type
application/scim+json
{}

Response samples

Content type
application/scim+json
{
  • "meta": {
    • "resourceType": "User",
    • "location": "/api/scim/v2/Users/1"
    },
  • "id": "1",
  • "schemas": [
    • "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
  • "userName": "john.doe@example.com",
  • "name": {
    • "formatted": "John Doe"
    },
  • "emails": [
    • {
      • "value": "john.doe@example.com",
      • "primary": true
      }
    ],
  • "displayName": "John Doe",
  • "preferredLanguage": "en",
  • "locale": "en",
  • "photos": []
}

Delete a user by ID.

⚠️ This action cannot be undone, please be cautious when using this endpoint ⚠️

Authorizations:
ApiKey
path Parameters
userId
required
integer

A user id

Responses

Search users

Authorizations:
ApiKey
Request Body schema: application/scim+json

Search criteria.

schemas
Array of strings
Items Value: "urn:ietf:params:scim:api:messages:2.0:SearchRequest"
filter
string

Filter expression for resources.

sortBy
string

Field to sort by.

sortOrder
string

Order of sorting (ascending or descending).

attributes
Array of strings

A multi-valued list of strings indicating the names of resource attributes to return in the response.

excludedAttributes
Array of strings

A multi-valued list of strings indicating the names of resource attributes to be removed from the default set of attributes to return.

startIndex
integer

The starting index for pagination.

count
integer

The number of resources to retrieve.

Responses

Request samples

Content type
application/scim+json
{
  • "schemas": [
    • "urn:ietf:params:scim:api:messages:2.0:SearchRequest"
    ],
  • "filter": "userName pr",
  • "sortBy": "userName",
  • "sortOrder": "ascending",
  • "attributes": [
    • "id",
    • "displayName"
    ],
  • "excludedAttributes": [
    • "locale"
    ],
  • "startIndex": 1,
  • "count": 10
}

Response samples

Content type
application/scim+json
{
  • "schemas": [
    • "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
  • "totalResults": 0,
  • "Resources": [
    • {
      • "meta": {
        • "resourceType": "User",
        • "location": "/api/scim/v2/Users/1"
        },
      • "id": "1",
      • "schemas": [
        • "urn:ietf:params:scim:schemas:core:2.0:User"
        ],
      • "userName": "john.doe@example.com",
      • "name": {
        • "formatted": "John Doe"
        },
      • "emails": [
        • {
          • "value": "john.doe@example.com",
          • "primary": true
          }
        ],
      • "displayName": "John Doe",
      • "preferredLanguage": "en",
      • "locale": "en",
      • "photos": []
      }
    ]
}

Retrieve information about oneself

When SCIM is enabled, this endpoint is accessible by anyone authentified in Grist.

Authorizations:
ApiKey

Responses

Response samples

Content type
application/scim+json
{
  • "meta": {
    • "resourceType": "User",
    • "location": "/api/scim/v2/Users/1"
    },
  • "id": "1",
  • "schemas": [
    • "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
  • "userName": "john.doe@example.com",
  • "name": {
    • "formatted": "John Doe"
    },
  • "emails": [
    • {
      • "value": "john.doe@example.com",
      • "primary": true
      }
    ],
  • "displayName": "John Doe",
  • "preferredLanguage": "en",
  • "locale": "en",
  • "photos": []
}

Bulk operation

Authorizations:
ApiKey
Request Body schema: application/scim+json

Operations to be performed in bulk.

schemas
Array of strings
Items Value: "urn:ietf:params:scim:api:messages:2.0:BulkRequest"
Array of objects

List of operations to be executed.

Responses

Request samples

Content type
application/scim+json
{
  • "schemas": [
    • "urn:ietf:params:scim:api:messages:2.0:BulkRequest"
    ],
  • "Operations": [
    • {
      • "method": "POST",
      • "path": "/scim/v2/Users",
      • "data": { }
      }
    ]
}

Retrieve SCIM schemas

Authorizations:
ApiKey

Responses

Retrieve service provider configuration

Authorizations:
ApiKey

Responses

Retrieve SCIM resource types

Authorizations:
ApiKey

Responses

Retrieve list of groups

Authorizations:
ApiKey
query Parameters
startIndex
integer
Example: startIndex=1

The starting index for pagination.

count
integer
Example: count=10

The number of resources to retrieve.

filter
string
Example: filter=displayName pr

Filter resources based on specific criteria.

Responses

Response samples

Content type
application/scim+json
{
  • "schemas": [
    • "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
  • "totalResults": 1,
  • "itemsPerPage": 20,
  • "startIndex": 1,
  • "Resources": [
    • {
      • "schemas": [
        • "urn:ietf:params:scim:schemas:core:2.0:Group"
        ],
      • "meta": {
        • "resourceType": "Group",
        • "location": "/api/scim/v2/Groups/1"
        },
      • "id": "1",
      • "displayName": "Engineering",
      • "members": [
        • {
          • "value": "1",
          • "display": "John Doe",
          • "type": "User",
          • "$ref": "/api/scim/v2/Users/1"
          }
        ]
      }
    ]
}

Create a new group

Authorizations:
ApiKey
Request Body schema: application/scim+json

Data for the group to be created.

schemas
Array of strings
Items Value: "urn:ietf:params:scim:schemas:core:2.0:Group"
displayName
string

The display name of the group.

Array of objects (MembersInRequest)

Responses

Request samples

Content type
application/scim+json
{
  • "schemas": [
    • "urn:ietf:params:scim:schemas:core:2.0:Group"
    ],
  • "displayName": "Engineering",
  • "members": [
    • {
      • "value": "1",
      • "display": "John Doe",
      • "type": "User",
      • "$ref": "/api/scim/v2/Users/1"
      }
    ]
}

Response samples

Content type
application/scim+json
{
  • "schemas": [
    • "urn:ietf:params:scim:schemas:core:2.0:Group"
    ],
  • "meta": {
    • "resourceType": "Group",
    • "location": "/api/scim/v2/Groups/1"
    },
  • "id": "1",
  • "displayName": "Engineering",
  • "members": [
    • {
      • "value": "1",
      • "display": "John Doe",
      • "type": "User",
      • "$ref": "/api/scim/v2/Users/1"
      }
    ]
}

Retrieve group by ID

Authorizations:
ApiKey
path Parameters
groupId
required
integer

A group id

Responses

Response samples

Content type
application/scim+json
{
  • "schemas": [
    • "urn:ietf:params:scim:schemas:core:2.0:Group"
    ],
  • "meta": {
    • "resourceType": "Group",
    • "location": "/api/scim/v2/Groups/1"
    },
  • "id": "1",
  • "displayName": "Engineering",
  • "members": [
    • {
      • "value": "1",
      • "display": "John Doe",
      • "type": "User",
      • "$ref": "/api/scim/v2/Users/1"
      }
    ]
}

Update a group by ID

⚠️ This operation overwrites all the group's information. In order to pass only some properties to update, please use PATCH instead.

Authorizations:
ApiKey
path Parameters
groupId
required
integer

A group id

Request Body schema: application/scim+json

Updated data for the group.

schemas
Array of strings
Items Value: "urn:ietf:params:scim:schemas:core:2.0:Group"
displayName
string

The display name of the group.

Array of objects (MembersInRequest)

Responses

Request samples

Content type
application/scim+json
{
  • "schemas": [
    • "urn:ietf:params:scim:schemas:core:2.0:Group"
    ],
  • "displayName": "Engineering",
  • "members": [
    • {
      • "value": "1",
      • "display": "John Doe",
      • "type": "User",
      • "$ref": "/api/scim/v2/Users/1"
      }
    ]
}

Response samples

Content type
application/scim+json
{
  • "schemas": [
    • "urn:ietf:params:scim:schemas:core:2.0:Group"
    ],
  • "meta": {
    • "resourceType": "Group",
    • "location": "/api/scim/v2/Groups/1"
    },
  • "id": "1",
  • "displayName": "Engineering",
  • "members": [
    • {
      • "value": "1",
      • "display": "John Doe",
      • "type": "User",
      • "$ref": "/api/scim/v2/Users/1"
      }
    ]
}

Partially update a group by ID

Authorizations:
ApiKey
path Parameters
groupId
required
integer

A group id

Request Body schema: application/scim+json

Data for the partial update of the group.

schemas
Array of strings
Items Value: "urn:ietf:params:scim:api:messages:2.0:PatchOp"
Array of objects

Responses

Request samples

Content type
application/scim+json
{
  • "schemas": [
    • "urn:ietf:params:scim:api:messages:2.0:PatchOp"
    ],
  • "Operations": [
    • {
      • "op": "replace",
      • "path": "members[display eq \"John Doe\"].value",
      • "value": "42"
      }
    ]
}

Response samples

Content type
application/scim+json
{
  • "schemas": [
    • "urn:ietf:params:scim:schemas:core:2.0:Group"
    ],
  • "meta": {
    • "resourceType": "Group",
    • "location": "/api/scim/v2/Groups/1"
    },
  • "id": "1",
  • "displayName": "Engineering",
  • "members": [
    • {
      • "value": "1",
      • "display": "John Doe",
      • "type": "User",
      • "$ref": "/api/scim/v2/Users/1"
      }
    ]
}

Delete a group by ID.

⚠️ This action cannot be undone, please be cautious when using this endpoint ⚠️

Authorizations:
ApiKey
path Parameters
groupId
required
integer

A group id

Responses

Search groups

Authorizations:
ApiKey
Request Body schema: application/scim+json

Search criteria.

schemas
Array of strings
Items Value: "urn:ietf:params:scim:api:messages:2.0:SearchRequest"
filter
string

Filter expression for resources.

sortBy
string

Field to sort by.

sortOrder
string

Order of sorting (ascending or descending).

attributes
Array of strings

A multi-valued list of strings indicating the names of resource attributes to return in the response.

excludedAttributes
Array of strings

A multi-valued list of strings indicating the names of resource attributes to be removed from the default set of attributes to return.

startIndex
integer

The starting index for pagination.

count
integer

The number of resources to retrieve.

Responses

Request samples

Content type
application/scim+json
{
  • "schemas": [
    • "urn:ietf:params:scim:api:messages:2.0:SearchRequest"
    ],
  • "filter": "displayName eq \"Engineering\"",
  • "sortBy": "displayName",
  • "sortOrder": "ascending",
  • "attributes": [
    • "id",
    • "displayName"
    ],
  • "excludedAttributes": [
    • "members"
    ],
  • "startIndex": 1,
  • "count": 10
}

Response samples

Content type
application/scim+json
{
  • "schemas": [
    • "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
  • "totalResults": 0,
  • "Resources": [
    • {
      • "schemas": [
        • "urn:ietf:params:scim:schemas:core:2.0:Group"
        ],
      • "meta": {
        • "resourceType": "Group",
        • "location": "/api/scim/v2/Groups/1"
        },
      • "id": "1",
      • "displayName": "Engineering",
      • "members": [
        • {
          • "value": "1",
          • "display": "John Doe",
          • "type": "User",
          • "$ref": "/api/scim/v2/Users/1"
          }
        ]
      }
    ]
}

Retrieve list of roles.

Roles are system-defined entities giving particular permissions to a given resource (document, workspace or organization). This API returns by default all these roles associated to all the resources. You may use the parameters to filter the results.

Authorizations:
ApiKey
query Parameters
startIndex
integer
Example: startIndex=1

The starting index for pagination.

count
integer
Example: count=10

The number of resources to retrieve.

filter
string
Example: filter=displayName pr

Filter resources based on specific criteria.

Responses

Response samples

Content type
application/scim+json
{
  • "schemas": [
    • "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
  • "totalResults": 1,
  • "itemsPerPage": 20,
  • "startIndex": 1,
  • "Resources": [
    • {
      • "schemas": [
        • "urn:ietf:params:scim:schemas:Grist:1.0:Role"
        ],
      • "meta": {
        • "resourceType": "Role",
        • "location": "/api/scim/v2/Roles/1"
        },
      • "id": "1",
      • "displayName": "owners",
      • "members": [
        • {
          • "value": "1",
          • "display": "Engineering",
          • "type": "Group",
          • "$ref": "/api/scim/v2/Groups/1"
          }
        ],
      • "orgId": 1
      }
    ]
}

Retrieve role by ID

Authorizations:
ApiKey
path Parameters
roleId
required
integer

A role id

Responses

Response samples

Content type
application/scim+json
{
  • "schemas": [
    • "urn:ietf:params:scim:schemas:Grist:1.0:Role"
    ],
  • "meta": {
    • "resourceType": "Role",
    • "location": "/api/scim/v2/Roles/1"
    },
  • "id": "1",
  • "displayName": "owners",
  • "members": [
    • {
      • "value": "1",
      • "display": "Engineering",
      • "type": "Group",
      • "$ref": "/api/scim/v2/Groups/1"
      }
    ],
  • "docId": "diHs5TB4mq6BQXw5RvBVu4"
}

Update a role by ID

⚠️ This operation overwrites all the memberships (the "members" property). In order to update part of the membership, please use PATCH instead. Only the memberships are authorized to be modified through this endpoint, other properties will be ignored.

Authorizations:
ApiKey
path Parameters
roleId
required
integer

A role id

Request Body schema: application/scim+json

Updated data for the role.

schemas
Array of strings
Items Value: "urn:ietf:params:scim:schemas:Grist:1.0:Role"
Array of objects (schemas-MembersInRequest)

Responses

Request samples

Content type
application/scim+json
{
  • "schemas": [
    • "urn:ietf:params:scim:schemas:Grist:1.0:Role"
    ],
  • "members": [
    • {
      • "value": "1",
      • "display": "Engineering",
      • "type": "Group",
      • "$ref": "/api/scim/v2/Groups/1"
      }
    ]
}

Response samples

Content type
application/scim+json
{
  • "schemas": [
    • "urn:ietf:params:scim:schemas:Grist:1.0:Role"
    ],
  • "meta": {
    • "resourceType": "Role",
    • "location": "/api/scim/v2/Roles/1"
    },
  • "id": "1",
  • "displayName": "owners",
  • "members": [
    • {
      • "value": "1",
      • "display": "Engineering",
      • "type": "Group",
      • "$ref": "/api/scim/v2/Groups/1"
      }
    ]
}

Partially update a role by ID

Only the memberships are authorized to be modified through this endpoint, other properties will be ignored.

Authorizations:
ApiKey
path Parameters
roleId
required
integer

A role id

Request Body schema: application/scim+json

Data for the partial update of the role.

schemas
Array of strings
Items Value: "urn:ietf:params:scim:api:messages:2.0:PatchOp"
Array of objects

Responses

Request samples

Content type
application/scim+json
{
  • "schemas": [
    • "urn:ietf:params:scim:api:messages:2.0:PatchOp"
    ],
  • "Operations": [
    • {
      • "op": "replace",
      • "path": "members[display eq \"John Doe\"].value",
      • "value": "42"
      }
    ]
}

Response samples

Content type
application/scim+json
{
  • "schemas": [
    • "urn:ietf:params:scim:schemas:Grist:1.0:Role"
    ],
  • "meta": {
    • "resourceType": "Role",
    • "location": "/api/scim/v2/Roles/1"
    },
  • "id": "1",
  • "displayName": "owners",
  • "members": [
    • {
      • "value": "1",
      • "display": "Engineering",
      • "type": "Group",
      • "$ref": "/api/scim/v2/Groups/1"
      }
    ]
}

templates

List available 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.

Authorizations:
ApiKey

Responses

Response samples

Content type
application/json
[
  • {
    • "id": 97,
    • "name": "Secret Plans",
    • "access": "owners",
    • "docs": [
      • {
        • "id": 145,
        • "name": "Project Lollipop",
        • "access": "owners",
        • "isPinned": true,
        • "urlId": null
        }
      ],
    • "orgDomain": "gristlabs"
    }
]

Get template details

Get information about a specific template.

Note: Requires a template organization to be configured on the server.

Authorizations:
ApiKey
path Parameters
templateId
required
string

ID of the template

Responses

Response samples

Content type
application/json
{
  • "id": 145,
  • "name": "Project Lollipop",
  • "access": "owners",
  • "isPinned": true,
  • "urlId": null,
  • "workspace": {
    • "id": 97,
    • "name": "Secret Plans",
    • "access": "owners",
    • "org": {
      • "id": 42,
      • "name": "Grist Labs",
      • "domain": "gristlabs",
      • "owner": {
        • "id": 101,
        • "name": "Helga Hufflepuff",
        • "picture": null
        },
      • "access": "owners",
      • "createdAt": "2019-09-13T15:42:35.000Z",
      • "updatedAt": "2019-09-13T15:42:35.000Z"
      }
    }
}

widgets

List available custom widgets

Get all widget definitions from the configured widget repository. Custom widgets extend Grist's functionality with specialized views.

Authorizations:
ApiKey

Responses

Response samples

Content type
application/json
[
  • {
    • "name": "string",
    • "url": "string",
    • "widgetId": "string"
    }
]

forms

Get form view data

Get the form configuration for a specific view section. Forms are a special view type that allows external users to submit data.

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

viewSectionId
required
integer

ID of the view section (form)

Responses

Response samples

Content type
application/json
{
  • "formFieldsById": { },
  • "formLayoutSpec": "string",
  • "formTableId": "string",
  • "formTitle": "string"
}

profile

Get current user's profile

Returns the profile information of the currently authenticated user.

Authorizations:
ApiKey

Responses

Response samples

Content type
application/json
{
  • "id": 101,
  • "name": "Helga Hufflepuff",
  • "picture": null
}

Update user's name

Update the display name for the current user.

Authorizations:
ApiKey
Request Body schema: application/json
name
required
string

New display name

Responses

Request samples

Content type
application/json
{
  • "name": "John Doe"
}

Update user's locale

Update the locale preference for the current user.

Authorizations:
ApiKey
Request Body schema: application/json
locale
string

Locale code (e.g. 'en-US', 'fr'). Set to null to clear.

Responses

Request samples

Content type
application/json
{
  • "locale": "en-US"
}

Get user's API key

Returns the current user's API key if one exists.

Authorizations:
ApiKey

Responses

Create or regenerate API key

Create a new API key or regenerate an existing one.

Authorizations:
ApiKey
Request Body schema: application/json
force
boolean

If true, regenerate even if a key already exists

Responses

Request samples

Content type
application/json
{
  • "force": true
}

Delete user's API key

Delete the current user's API key.

Authorizations:
ApiKey

Responses

session

Get active session information

Returns information about the active user and organization for the current session.

Authorizations:
ApiKey

Responses

Response samples

Content type
application/json
{
  • "user": {
    • "id": 101,
    • "name": "Helga Hufflepuff",
    • "picture": null
    },
  • "org": {
    • "id": 42,
    • "name": "Grist Labs",
    • "domain": "gristlabs",
    • "owner": {
      • "id": 101,
      • "name": "Helga Hufflepuff",
      • "picture": null
      },
    • "access": "owners",
    • "createdAt": "2019-09-13T15:42:35.000Z",
    • "updatedAt": "2019-09-13T15:42:35.000Z"
    },
  • "orgError": {
    • "error": "string",
    • "status": 0
    }
}

Set active user for organization

Switch which user account is active for a given organization. Useful when a user has multiple accounts logged in.

Authorizations:
ApiKey
Request Body schema: application/json
email
required
string

Email of the user to make active

org
string

Organization subdomain or 'current'

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "org": "string"
}

Response samples

Content type
application/json
{
  • "email": "string"
}

Get all session users and organizations

Returns all user profiles logged into the current session and all organizations they can access.

Authorizations:
ApiKey

Responses

Response samples

Content type
application/json
{
  • "users": [
    • {
      • "id": 101,
      • "name": "Helga Hufflepuff",
      • "picture": null
      }
    ],
  • "orgs": [
    • {
      • "id": 42,
      • "name": "Grist Labs",
      • "domain": "gristlabs",
      • "owner": {
        • "id": 101,
        • "name": "Helga Hufflepuff",
        • "picture": null
        },
      • "access": "owners",
      • "createdAt": "2019-09-13T15:42:35.000Z",
      • "updatedAt": "2019-09-13T15:42:35.000Z"
      }
    ]
}