Documentation Powered by ReDoc

Grist API (1.0.1)

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

Authentication

API Key

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

get/orgs
https://docs.getgrist.com/api/orgs
https://<TEAM>.getgrist.com/api/orgs

This enumerates all the team sites or personal areas available.

Authorizations:
API Key

Responses

200

An array of organizations

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    • "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

get/orgs/{orgId}
https://docs.getgrist.com/api/orgs/{orgId}
https://<TEAM>.getgrist.com/api/orgs/{orgId}
Authorizations:
API Key
path Parameters
orgId
required
any (OrgKey)

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

200

An organization

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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

patch/orgs/{orgId}
https://docs.getgrist.com/api/orgs/{orgId}
https://<TEAM>.getgrist.com/api/orgs/{orgId}
Authorizations:
API Key
path Parameters
orgId
required
any (OrgKey)

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

200

Success

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "name": "ACME Unlimited"
}

List users with access to org

get/orgs/{orgId}/access
https://docs.getgrist.com/api/orgs/{orgId}/access
https://<TEAM>.getgrist.com/api/orgs/{orgId}/access
Authorizations:
API Key
path Parameters
orgId
required
any (OrgKey)

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

200

Users with access to org

Response samples

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

Change who has access to org

patch/orgs/{orgId}/access
https://docs.getgrist.com/api/orgs/{orgId}/access
https://<TEAM>.getgrist.com/api/orgs/{orgId}/access
Authorizations:
API Key
path Parameters
orgId
required
any (OrgKey)

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

delta
required
object (OrgAccessWrite)

Request samples

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

List workspaces and documents within an org

get/orgs/{orgId}/workspaces
https://docs.getgrist.com/api/orgs/{orgId}/workspaces
https://<TEAM>.getgrist.com/api/orgs/{orgId}/workspaces
Authorizations:
API Key
path Parameters
orgId
required
any (OrgKey)

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

200

An org's workspaces and documents

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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",
  • "workspaces":
    [
    • {
      • "id": 97,
      • "name": "Secret Plans",
      • "access": "owners",
      • "docs":
        [
        • {
          • "id": 145,
          • "name": "Project Lollipop",
          • "access": "owners",
          • "isPinned": true,
          • "urlId": null
          }
        ]
      }
    ]
}

/workspaces

Sites can be organized into groups of documents called workspaces.

Create an empty workspace

post/orgs/{orgId}/workspaces
https://docs.getgrist.com/api/orgs/{orgId}/workspaces
https://<TEAM>.getgrist.com/api/orgs/{orgId}/workspaces
Authorizations:
API Key
path Parameters
orgId
required
any (OrgKey)

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

200

The workspace id

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "name": "Retreat Docs"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
155

Describe a workspace

get/workspaces/{workspaceId}
https://docs.getgrist.com/api/workspaces/{workspaceId}
https://<TEAM>.getgrist.com/api/workspaces/{workspaceId}
Authorizations:
API Key
path Parameters
workspaceId
required
integer (WorkspaceKey)

An integer id

Responses

200

A workspace

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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 a workspace

patch/workspaces/{workspaceId}
https://docs.getgrist.com/api/workspaces/{workspaceId}
https://<TEAM>.getgrist.com/api/workspaces/{workspaceId}
Authorizations:
API Key
path Parameters
workspaceId
required
integer (WorkspaceKey)

An integer id

Request Body schema: application/json

the changes to make

name
string

Responses

200

Success

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "name": "Retreat Docs"
}

Delete a workspace

delete/workspaces/{workspaceId}
https://docs.getgrist.com/api/workspaces/{workspaceId}
https://<TEAM>.getgrist.com/api/workspaces/{workspaceId}
Authorizations:
API Key
path Parameters
workspaceId
required
integer (WorkspaceKey)

An integer id

Responses

200

Success

List users with access to workspace

get/workspaces/{workspaceId}/access
https://docs.getgrist.com/api/workspaces/{workspaceId}/access
https://<TEAM>.getgrist.com/api/workspaces/{workspaceId}/access
Authorizations:
API Key
path Parameters
workspaceId
required
integer (WorkspaceKey)

An integer id

Responses

200

Users with access to workspace

Response samples

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

Change who has access to workspace

patch/workspaces/{workspaceId}/access
https://docs.getgrist.com/api/workspaces/{workspaceId}/access
https://<TEAM>.getgrist.com/api/workspaces/{workspaceId}/access
Authorizations:
API Key
path Parameters
workspaceId
required
integer (WorkspaceKey)

An integer id

Request Body schema: application/json

the changes to make

delta
required
object (WorkspaceAccessWrite)

Request samples

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

/docs

Workspaces contain collections of Grist documents.

Create an empty document

post/workspaces/{workspaceId}/docs
https://docs.getgrist.com/api/workspaces/{workspaceId}/docs
https://<TEAM>.getgrist.com/api/workspaces/{workspaceId}/docs
Authorizations:
API Key
path Parameters
workspaceId
required
integer (WorkspaceKey)

An integer id

Request Body schema: application/json

settings for the document

name
string
isPinned
boolean

Responses

200

The document id

Request samples

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

Response samples

Content type
application/json
Copy
 Expand all Collapse all
"8b97c8db-b4df-4b34-b72c-17459e70140a"

Describe a document

get/docs/{docId}
https://docs.getgrist.com/api/docs/{docId}
https://<TEAM>.getgrist.com/api/docs/{docId}
Authorizations:
API Key
path Parameters
docId
required
string (DocKey)

A string id (UUID)

Responses

200

A document's metadata

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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)

patch/docs/{docId}
https://docs.getgrist.com/api/docs/{docId}
https://<TEAM>.getgrist.com/api/docs/{docId}
Authorizations:
API Key
path Parameters
docId
required
string (DocKey)

A string id (UUID)

Request Body schema: application/json

the changes to make

name
string
isPinned
boolean

Responses

200

Success

Request samples

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

Delete a document

delete/docs/{docId}
https://docs.getgrist.com/api/docs/{docId}
https://<TEAM>.getgrist.com/api/docs/{docId}
Authorizations:
API Key
path Parameters
docId
required
string (DocKey)

A string id (UUID)

Responses

200

Success

Move document to another workspace in the same org.

patch/docs/{docId}/move
https://docs.getgrist.com/api/docs/{docId}/move
https://<TEAM>.getgrist.com/api/docs/{docId}/move
Authorizations:
API Key
path Parameters
docId
required
string (DocKey)

A string id (UUID)

Request Body schema: application/json

the target workspace

workspace
required
integer

Responses

200

Success

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "workspace": 597
}

List users with access to document

get/docs/{docId}/access
https://docs.getgrist.com/api/docs/{docId}/access
https://<TEAM>.getgrist.com/api/docs/{docId}/access
Authorizations:
API Key
path Parameters
docId
required
string (DocKey)

A string id (UUID)

Responses

200

Users with access to document

Response samples

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

Change who has access to document

patch/docs/{docId}/access
https://docs.getgrist.com/api/docs/{docId}/access
https://<TEAM>.getgrist.com/api/docs/{docId}/access
Authorizations:
API Key
path Parameters
docId
required
string (DocKey)

A string id (UUID)

Request Body schema: application/json

the changes to make

delta
required
object (WorkspaceAccessWrite)

Request samples

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

Content of document, as an Sqlite file

get/docs/{docId}/download
https://docs.getgrist.com/api/docs/{docId}/download
https://<TEAM>.getgrist.com/api/docs/{docId}/download
Authorizations:
API Key
path Parameters
docId
required
string (DocKey)

A string id (UUID)

Responses

200

A document's content in Sqlite form

Content of document, as an Excel file

get/docs/{docId}/download/xlsx
https://docs.getgrist.com/api/docs/{docId}/download/xlsx
https://<TEAM>.getgrist.com/api/docs/{docId}/download/xlsx
Authorizations:
API Key
path Parameters
docId
required
string (DocKey)

A string id (UUID)

Responses

200

A documents's content in Excel form

Content of table, as a CSV file

get/docs/{docId}/download/csv
https://docs.getgrist.com/api/docs/{docId}/download/csv
https://<TEAM>.getgrist.com/api/docs/{docId}/download/csv
Authorizations:
API Key
path Parameters
docId
required
string (DocKey)

A string id (UUID)

query Parameters
tableId
required
string

Name of a table (normalized).

Responses

200

A table's content in CSV form

/records

Tables contain collections of records (also called rows).

Fetch records from a table

get/docs/{docId}/tables/{tableId}/records
https://docs.getgrist.com/api/docs/{docId}/tables/{tableId}/records
https://<TEAM>.getgrist.com/api/docs/{docId}/tables/{tableId}/records
Authorizations:
API Key
path Parameters
docId
required
string (DocKey)

A string id (UUID)

tableId
required
string

name of a table (normalized)

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

200

Records from the table

Response samples

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

Add records to a table

post/docs/{docId}/tables/{tableId}/records
https://docs.getgrist.com/api/docs/{docId}/tables/{tableId}/records
https://<TEAM>.getgrist.com/api/docs/{docId}/tables/{tableId}/records
Authorizations:
API Key
path Parameters
docId
required
string (DocKey)

A string id (UUID)

tableId
required
string

name of a table (normalized)

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

records
required
Array of objects

Responses

200

IDs of records added

Request samples

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

Response samples

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

Modify records of a table

patch/docs/{docId}/tables/{tableId}/records
https://docs.getgrist.com/api/docs/{docId}/tables/{tableId}/records
https://<TEAM>.getgrist.com/api/docs/{docId}/tables/{tableId}/records
Authorizations:
API Key
path Parameters
docId
required
string (DocKey)

A string id (UUID)

tableId
required
string

name of a table (normalized)

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

records
required
Array of objects

Responses

200

Success

Request samples

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

Add or update records of a table

put/docs/{docId}/tables/{tableId}/records
https://docs.getgrist.com/api/docs/{docId}/tables/{tableId}/records
https://<TEAM>.getgrist.com/api/docs/{docId}/tables/{tableId}/records
Authorizations:
API Key
path Parameters
docId
required
string (DocKey)

A string id (UUID)

tableId
required
string

name of a table (normalized)

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.

records
required
Array of objects

Responses

200

Success

Request samples

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

/columns

Tables are structured as a collection of columns.

List columns in a table

get/docs/{docId}/tables/{tableId}/columns
https://docs.getgrist.com/api/docs/{docId}/tables/{tableId}/columns
https://<TEAM>.getgrist.com/api/docs/{docId}/tables/{tableId}/columns
Authorizations:
API Key
path Parameters
docId
required
string (DocKey)

A string id (UUID)

tableId
required
string

name of a table (normalized)

Responses

200

The columns in a table

Response samples

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

/data

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

Fetch data from a table Deprecated

get/docs/{docId}/tables/{tableId}/data
https://docs.getgrist.com/api/docs/{docId}/tables/{tableId}/data
https://<TEAM>.getgrist.com/api/docs/{docId}/tables/{tableId}/data

Deprecated in favor of records endpoints. We have no immediate plans to remove these endpoints, but consider records a better starting point for new projects.

Authorizations:
API Key
path Parameters
docId
required
string (DocKey)

A string id (UUID)

tableId
required
string

name of a table (normalized)

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

200

Cells from the table

Response samples

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

Add rows to a table Deprecated

post/docs/{docId}/tables/{tableId}/data
https://docs.getgrist.com/api/docs/{docId}/tables/{tableId}/data
https://<TEAM>.getgrist.com/api/docs/{docId}/tables/{tableId}/data

Deprecated in favor of records endpoints. We have no immediate plans to remove these endpoints, but consider records a better starting point for new projects.

Authorizations:
API Key
path Parameters
docId
required
string (DocKey)

A string id (UUID)

tableId
required
string

name of a table (normalized)

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*
Array of any

Responses

200

IDs of rows added

Request samples

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

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • 101,
  • 102,
  • 103
]

Modify rows of a table Deprecated

patch/docs/{docId}/tables/{tableId}/data
https://docs.getgrist.com/api/docs/{docId}/tables/{tableId}/data
https://<TEAM>.getgrist.com/api/docs/{docId}/tables/{tableId}/data

Deprecated in favor of records endpoints. We have no immediate plans to remove these endpoints, but consider records a better starting point for new projects.

Authorizations:
API Key
path Parameters
docId
required
string (DocKey)

A string id (UUID)

tableId
required
string

name of a table (normalized)

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*
Array of any

Responses

200

IDs of rows modified

Request samples

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

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • 101,
  • 102,
  • 103
]

Delete rows of a table

post/docs/{docId}/tables/{tableId}/data/delete
https://docs.getgrist.com/api/docs/{docId}/tables/{tableId}/data/delete
https://<TEAM>.getgrist.com/api/docs/{docId}/tables/{tableId}/data/delete
Authorizations:
API Key
path Parameters
docId
required
string (DocKey)

A string id (UUID)

tableId
required
string

name of a table (normalized)

Request Body schema: application/json

the IDs of rows to remove

Array
integer

Responses

200

Nothing returned

Request samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • 101,
  • 102,
  • 103
]

Response samples

Content type
application/json
Copy
 Expand all Collapse all
null

/attachments

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

Upload attachments to a doc

post/docs/{docId}/attachments
https://docs.getgrist.com/api/docs/{docId}/attachments
https://<TEAM>.getgrist.com/api/docs/{docId}/attachments
Authorizations:
API Key
path Parameters
docId
required
string (DocKey)

A string id (UUID)

Request Body schema: multipart/form-data

the files to add to the doc

upload
Array of File

Responses

200

IDs of attachments added, one per file.

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • 101,
  • 102,
  • 103
]

Get the metadata for an attachment

get/docs/{docId}/attachments/{attachmentId}
https://docs.getgrist.com/api/docs/{docId}/attachments/{attachmentId}
https://<TEAM>.getgrist.com/api/docs/{docId}/attachments/{attachmentId}
Authorizations:
API Key
path Parameters
docId
required
string (DocKey)

A string id (UUID)

attachmentId
required
number (AttachmentId)

An integer ID

Responses

200

Attachment metadata

Response samples

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

Download the contents of an attachment

get/docs/{docId}/attachments/{attachmentId}/download
https://docs.getgrist.com/api/docs/{docId}/attachments/{attachmentId}/download
https://<TEAM>.getgrist.com/api/docs/{docId}/attachments/{attachmentId}/download
Authorizations:
API Key
path Parameters
docId
required
string (DocKey)

A string id (UUID)

attachmentId
required
number (AttachmentId)

An integer ID

Responses

200

Attachment contents, with suitable Content-Type.