From fc5ff604c62f7298197afd246b5a7837f45354b4 Mon Sep 17 00:00:00 2001 From: Florent Date: Tue, 23 Jul 2024 22:05:40 +0200 Subject: [PATCH] Add history action removal API documentation (#366) --- api/grist.yml | 21 ++++++++++++++++ help/en/docs/api.md | 58 +++++++++++++++++++++++---------------------- 2 files changed, 51 insertions(+), 28 deletions(-) diff --git a/api/grist.yml b/api/grist.yml index 7abe0fd00..54f891958 100644 --- a/api/grist.yml +++ b/api/grist.yml @@ -443,6 +443,27 @@ paths: text/json: schema: $ref: '#/components/schemas/TableSchemaResult' + /docs/{docId}/states/remove: + post: + operationId: deleteActions + tags: + - docs + summary: "Truncate the document's action history" + parameters: + - $ref: '#/components/parameters/docIdPathParam' + requestBody: + content: + application/json: + schema: + type: object + required: + - keep + properties: + keep: + type: integer + description: "The number of the latest history actions to keep" + example: + keep: 3 /docs/{docId}/force-reload: post: operationId: forceReload diff --git a/help/en/docs/api.md b/help/en/docs/api.md index d1889f72e..6d12d2b53 100644 --- a/help/en/docs/api.md +++ b/help/en/docs/api.md @@ -51,7 +51,7 @@ REST API for manipulating documents, workspaces, and team sites.
-
API docs by Redocly
API docs by Redocly
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"
}

Reload a document

Close and reopen the document, forcing the python engine to reload

+

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

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

@@ -150,17 +152,17 @@ REST API for manipulating documents, workspaces, and team sites.
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)

+

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)

+

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)

+

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.

@@ -174,29 +176,29 @@ REST API for manipulating documents, workspaces, and team sites.
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.

+

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)

+

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

+

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)

+

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)

+

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)

+

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.

@@ -204,7 +206,7 @@ REST API for manipulating documents, workspaces, and team sites.
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)

+

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

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.

+

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.

+

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)

+

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.

+

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.

@@ -242,40 +244,40 @@ Also note that some query parameters alter this behavior.

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)

+

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)

+

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)

+

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)

+

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)

+

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)

+

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)

+

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

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)

+

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

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