Grist columns API
Tables are structured as a collection of columns.
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 columns API
servers:
- url: https://{gristhost}/api
variables:
subdomain:
description: The team name, or `docs` for personal areas
default: docs
security:
- ApiKey: []
tags:
- name: columns
description: Tables are structured as a collection of columns.
paths:
/docs/{docId}/tables/{tableId}/columns:
get:
operationId: listColumns
tags:
- columns
summary: List columns in a table
parameters:
- $ref: '#/components/parameters/docIdPathParam'
- $ref: '#/components/parameters/tableIdPathParam'
- $ref: '#/components/parameters/hiddenQueryParam'
responses:
200:
description: The columns in a table
content:
application/json:
schema:
$ref: '#/components/schemas/ColumnsList'
post:
operationId: addColumns
tags:
- columns
summary: Add columns to a table
parameters:
- $ref: '#/components/parameters/docIdPathParam'
- $ref: '#/components/parameters/tableIdPathParam'
requestBody:
description: the columns to add
content:
application/json:
schema:
$ref: '#/components/schemas/CreateColumns'
required: true
responses:
200:
description: The columns created
content:
application/json:
schema:
$ref: '#/components/schemas/ColumnsWithoutFields'
patch:
operationId: modifyColumns
tags:
- columns
summary: Modify columns of a table
parameters:
- $ref: '#/components/parameters/docIdPathParam'
- $ref: '#/components/parameters/tableIdPathParam'
requestBody:
description: the columns to change, with ids
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateColumns'
required: true
responses:
200:
description: Success
put:
operationId: replaceColumns
tags:
- columns
summary: Add or update columns of a table
parameters:
- $ref: '#/components/parameters/docIdPathParam'
- $ref: '#/components/parameters/tableIdPathParam'
- in: query
name: noadd
schema:
type: boolean
description: Set to true to prohibit adding columns.
- in: query
name: noupdate
schema:
type: boolean
description: Set to true to prohibit updating columns.
- in: query
name: replaceall
schema:
type: boolean
description: Set to true to remove existing columns (except the hidden ones) that are not specified in the request body.
requestBody:
description: '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.
'
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateColumns'
required: true
responses:
200:
description: Success
/docs/{docId}/tables/{tableId}/columns/{colId}:
delete:
operationId: deleteColumn
tags:
- columns
summary: Delete a column of a table
parameters:
- $ref: '#/components/parameters/docIdPathParam'
- $ref: '#/components/parameters/tableIdPathParam'
- $ref: '#/components/parameters/colIdPathParam'
responses:
200:
description: Success
components:
schemas:
CreateFields:
allOf:
- $ref: '#/components/schemas/Fields'
- type: object
properties:
recalcDeps:
type: string
description: 'An encoded array of column identifiers (colRefs) that this column depends on. If any of these columns change, the column will be recalculated. E.g.: <code>[2, 3]</code>'
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>'
ColumnsList:
type: object
properties:
columns:
type: array
items:
type: object
properties:
id:
type: string
example: ColumnName
fields:
$ref: '#/components/schemas/GetFields'
example:
columns:
- id: pet
fields:
label: Pet
- id: popularity
fields:
label: Popularity ❤
type: Int
CreateColumns:
type: object
required:
- columns
properties:
columns:
type: array
items:
type: object
properties:
id:
type: string
description: Column identifier
fields:
$ref: '#/components/schemas/CreateFields'
example:
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"}}}'
UpdateColumns:
type: object
required:
- columns
properties:
columns:
type: array
items:
type: object
required:
- id
- fields
properties:
id:
type: string
description: Column identifier
fields:
allOf:
- $ref: '#/components/schemas/CreateFields'
- type: object
properties:
colId:
type: string
description: Set it to the new column ID when you want to change it.
example:
columns:
- id: pet
fields:
label: Pet
- id: popularity
fields:
label: Popularity ❤
type: Int
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
ColumnsWithoutFields:
type: object
required:
- columns
properties:
columns:
type: array
items:
type: object
required:
- id
properties:
id:
type: string
example: ColumnName
example:
columns:
- id: pet
- id: popularity
parameters:
docIdPathParam:
in: path
name: docId
schema:
type: string
description: A string id (UUID)
required: true
colIdPathParam:
in: path
name: colId
schema:
type: string
description: The column id (without the starting `$`) as shown in the column configuration below the label
required: true
tableIdPathParam:
in: path
name: tableId
schema:
type: string
description: normalized table name (see `TABLE ID` in Raw Data) or numeric row ID in `_grist_Tables`
required: true
hiddenQueryParam:
in: query
name: hidden
schema:
type: boolean
description: Set to true to include the hidden columns (like "manualSort")
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.