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

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
      }
    }
}

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

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
"8b97c8db-b4df-4b34-b72c-17459e70140a"

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 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
}

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
      }
    }
}

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.

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

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"
}

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
}

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

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
        }
      }
    ]
}

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": true
        }
      },
    • {
      • "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

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

Request Body schema: application/json

the tables to change, with ids

required
Array of objects

Responses

Request samples

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

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

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

webhooks

Document changes can trigger requests to URLs called webhooks.

Webhooks associated with a document

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

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

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

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

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

Responses

sql

Sql endpoint to query data from documents.

Run an SQL query against a document

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

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"
}

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 users to retrieve.

filter
string
Example: filter=userName pr

Filter users 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 override 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 users.

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 users to retrieve.

Responses

Request samples

Content type
application/scim+json
{
  • "schemas": [
    • "urn:ietf:params:scim:api:messages:2.0:SearchRequest"
    ],
  • "filter": "userName co \"john.doe\"",
  • "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