Grist tables API
Documents are structured as a collection of tables.
OpenAPI Specification
openapi: 3.0.0
info:
description: 'An API for manipulating Grist sites, workspaces, and documents.
# Authentication
<SecurityDefinitions />
'
version: 1.0.1
title: Grist attachments tables API
servers:
- url: https://{gristhost}/api
variables:
subdomain:
description: The team name, or `docs` for personal areas
default: docs
security:
- ApiKey: []
tags:
- name: tables
description: Documents are structured as a collection of tables.
paths:
/docs/{docId}/tables:
get:
operationId: listTables
tags:
- tables
summary: List tables in a document
parameters:
- $ref: '#/components/parameters/docIdPathParam'
- $ref: '#/components/parameters/expandQueryParam'
responses:
200:
description: The tables in a document
content:
application/json:
schema:
$ref: '#/components/schemas/TablesList'
examples:
default:
summary: Without expand
value:
tables:
- id: People
fields:
tableRef: 1
onDemand: false
- id: Places
fields:
tableRef: 2
onDemand: false
expanded:
summary: With ?expand=column
value:
tables:
- id: People
fields:
tableRef: 1
onDemand: false
columns:
- id: Name
fields:
colRef: 2
label: Name
isFormula: false
type: Text
parentId: 1
formula: ''
- id: Age
fields:
colRef: 3
label: Age
isFormula: false
type: Numeric
parentId: 1
formula: ''
post:
operationId: addTables
tags:
- tables
summary: Add tables to a document
parameters:
- $ref: '#/components/parameters/docIdPathParam'
requestBody:
description: the tables to add
content:
application/json:
schema:
$ref: '#/components/schemas/CreateTables'
required: true
responses:
200:
description: The table created
content:
application/json:
schema:
$ref: '#/components/schemas/TablesWithoutFields'
patch:
operationId: modifyTables
tags:
- tables
summary: Modify tables of a document
description: 'Modify metadata for existing tables. This endpoint is primarily useful for:
- Renaming tables (via the `tableId` field)
- Setting on-demand loading (via the `onDemand` field)
'
parameters:
- $ref: '#/components/parameters/docIdPathParam'
requestBody:
description: the tables to modify, identified by their current id
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateTables'
required: true
responses:
200:
description: Success
components:
parameters:
docIdPathParam:
in: path
name: docId
schema:
type: string
description: A string id (UUID)
required: true
expandQueryParam:
in: query
name: expand
schema:
type: string
enum:
- column
description: Set to "column" to include column metadata for each table in the response.
required: false
schemas:
GetFields:
allOf:
- $ref: '#/components/schemas/Fields'
- type: object
properties:
recalcDeps:
type: array
items:
type: integer
description: 'An array of column identifiers (colRefs) that this column depends on, prefixed with "L" constant. If any of these columns change, the column will be recalculated. E.g.: <code>["L", 2, 3]</code>'
colRef:
type: integer
description: 'Column reference, e.g.: <code>2</code>'
CreateTables:
type: object
required:
- tables
properties:
tables:
type: array
items:
type: object
required:
- columns
properties:
id:
type: string
example: Table1
columns:
type: array
items:
type: object
properties:
id:
type: string
example: ColumnName
fields:
type: object
example:
tables:
- id: People
columns:
- id: pet
fields:
label: Pet
- id: popularity
fields:
label: Popularity ❤
UpdateTables:
type: object
required:
- tables
properties:
tables:
type: array
items:
type: object
required:
- id
- fields
properties:
id:
type: string
description: Current table identifier
fields:
type: object
properties:
tableId:
type: string
description: Set to a new value to rename the table
onDemand:
type: boolean
description: Whether the table should use on-demand loading
example:
tables:
- id: People
fields:
tableId: Persons
- id: Places
fields:
onDemand: true
TablesWithoutFields:
type: object
required:
- tables
properties:
tables:
type: array
items:
type: object
required:
- id
properties:
id:
type: string
example: Table1
example:
tables:
- id: People
- id: Places
Fields:
type: object
properties:
type:
type: string
description: Column type, by default Any. Ref, RefList and DateTime types requires a postfix, e.g. <code>DateTime:America/New_York</code>, <code>Ref:Users</code>
enum:
- Any
- Text
- Numeric
- Int
- Bool
- Date
- DateTime:<timezone>
- Choice
- ChoiceList
- Ref:<tableId>
- RefList:<tableId>
- Attachments
label:
type: string
description: Column label.
formula:
type: string
description: 'A python formula, e.g.: <code>$A + Table1.lookupOne(B=$B)</code>'
isFormula:
type: boolean
description: Use "true" to indicate that the column is a formula column. Use "false" for trigger formula column.
widgetOptions:
type: string
description: 'A JSON object with widget options, e.g.: <code>{"choices": ["cat", "dog"], "alignment": "right"}</code>'
untieColIdFromLabel:
type: boolean
description: Use "true" to indicate that the column label should not be used as the column identifier. Use "false" to use the label as the identifier.
recalcWhen:
type: integer
description: A number indicating when the column should be recalculated. <ol start='0'><li>On new records or when any field in recalcDeps changes, it's a 'data-cleaning'.</li><li>Never.</li><li>Calculate on new records and on manual updates to any data field.</li></ol>
visibleCol:
type: integer
description: For Ref and RefList columns, the colRef of a column to display
TablesList:
type: object
required:
- tables
properties:
tables:
type: array
items:
type: object
required:
- id
- fields
properties:
id:
type: string
example: Table1
fields:
type: object
properties:
tableRef:
type: integer
description: Row ID of the table in the _grist_Tables metadata table
onDemand:
type: boolean
description: Whether the table uses on-demand loading
columns:
type: array
description: Included when expand=column is set. Contains metadata for each column in the table.
items:
type: object
required:
- id
- fields
properties:
id:
type: string
example: ColumnName
fields:
$ref: '#/components/schemas/GetFields'
example:
tables:
- id: People
fields:
tableRef: 1
onDemand: false
- id: Places
fields:
tableRef: 2
onDemand: false
securitySchemes:
ApiKey:
type: http
scheme: bearer
bearerFormat: 'Authorization: Bearer XXXXXXXXXXX'
description: 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.