Grist

https://support.getgrist.com
Admin
Grist is a powerful spreadsheet-database hybrid tool that helps users manage and analyze data,...
Tokens:200,814
Snippets:2,656
Trust Score:9.9
Update:3 months ago
Show doc for...
Tokens:
Raw
### Schedule Format Examples

Source: https://support.getgrist.com/functions

Examples of valid schedule strings defining intervals and slots.

```text
annual: Jan-15, Apr-15, Jul-15  -- Three times a year on given dates at midnight.
annual: 1/15, 4/15, 7/15        -- Same as above.
monthly: /1 2pm, /15 2pm        -- The 1st and the 15th of each month, at 2pm.
3-months: /10, +1m /20           -- Every 3 months on the 10th of month 1, 20th of month 2.
weekly: Mo 9am, Tu 9am, Fr 2pm  -- Three times a week at specified times.
2-weeks: Mo, +1w Tu             -- Every 2 weeks on Monday of week 1, Tuesday of week 2.
daily: 07:30, 21:00             -- Twice a day at specified times.
2-day: 12am, 4pm, +1d 8am       -- Three times every two days, evenly spaced.
hourly: :15, :45                -- 15 minutes before and after each hour.
4-hour: :00, 1:20, 2:40         -- Three times every 4 hours, evenly spaced.
10-minute: +0s                  -- Every 10 minutes on the minute.
```

--------------------------------

### Example Forked Tutorial URL

Source: https://support.getgrist.com/document-tutorials

This is an example of a user's unique copy of a tutorial, automatically created when they open the Direct URL for the first time. Changes made here won't affect the original.

```url
https://docs.getgrist.com/doc/woXtXUBmiN5T~1eYN9joCXkuVokCD1p3EYt~12345
```

--------------------------------

### Python Schedule Usage Examples

Source: https://support.getgrist.com/functions

Interactive Python examples demonstrating the SCHEDULE function with various configurations.

```python
>>> def show(dates): return [d.strftime("%Y-%m-%d %H:%M") for d in dates]
```

```python
>>> start = datetime(2018, 9, 4, 14, 0);   # 2pm on Tue, Sep 4 2018.
```

```python
>>> show(SCHEDULE('annual: Jan-15, Apr-15, Jul-15, Oct-15', start=start, count=4))
['2018-10-15 00:00', '2019-01-15 00:00', '2019-04-15 00:00', '2019-07-15 00:00']
```

```python
>>> show(SCHEDULE('annual: 1/15, 4/15, 7/15', start=start, count=4))
['2019-01-15 00:00', '2019-04-15 00:00', '2019-07-15 00:00', '2020-01-15 00:00']
```

```python
>>> show(SCHEDULE('monthly: /1 2pm, /15 5pm', start=start, count=4))
['2018-09-15 17:00', '2018-10-01 14:00', '2018-10-15 17:00', '2018-11-01 14:00']
```

```python
>>> show(SCHEDULE('3-months: /10, +1m /20', start=start, count=4))
['2018-09-10 00:00', '2018-10-20 00:00', '2018-12-10 00:00', '2019-01-20 00:00']
```

```python
>>> show(SCHEDULE('weekly: Mo 9am, Tu 9am, Fr 2pm', start=start, count=4))
['2018-09-07 14:00', '2018-09-10 09:00', '2018-09-11 09:00', '2018-09-14 14:00']
```

```python
>>> show(SCHEDULE('2-weeks: Mo, +1w Tu', start=start, count=4))
['2018-09-11 00:00', '2018-09-17 00:00', '2018-09-25 00:00', '2018-10-01 00:00']
```

```python
>>> show(SCHEDULE('daily: 07:30, 21:00', start=start, count=4))
['2018-09-04 21:00', '2018-09-05 07:30', '2018-09-05 21:00', '2018-09-06 07:30']
```

```python
>>> show(SCHEDULE('2-day: 12am, 4pm, +1d 8am', start=start, count=4))
['2018-09-04 16:00', '2018-09-05 08:00', '2018-09-06 00:00', '2018-09-06 16:00']
```

```python
>>> show(SCHEDULE('hourly: :15, :45', start=start, count=4))
['2018-09-04 14:15', '2018-09-04 14:45', '2018-09-04 15:15', '2018-09-04 15:45']
```

```python
>>> show(SCHEDULE('4-hour: :00, +1H :20, +2H :40', start=start, count=4))
['2018-09-04 14:00', '2018-09-04 15:20', '2018-09-04 16:40', '2018-09-04 18:00']
```

--------------------------------

### Search Users Response Example

Source: https://support.getgrist.com/api

Example response body returned after a successful user search operation.

```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": [
        {
          "value": "https://example.com/pics/john-doe.png",
          "primary": true,
          "type": "photo"
}
]
}
]

}
```

--------------------------------

### Add columns response example

Source: https://support.getgrist.com/api

Example JSON response returned after successfully adding columns to a table.

```json
{
  "columns": [
    {
      "id": "pet"
    },
    {
      "id": "popularity"
    }
  ]
}
```

--------------------------------

### List columns response example

Source: https://support.getgrist.com/api

Example JSON response structure when retrieving columns from a table.

```json
{
  "columns": [
    {
      "id": "pet",
      "fields": {
        "label": "Pet"
      }
    },
    {
      "id": "popularity",
      "fields": {
        "label": "Popularity ❤",
        "type": "Int"
      }
    }
  ]
}
```

--------------------------------

### POST /docs/{docId}/timing/start

Source: https://support.getgrist.com/api

Start collecting timing information for formula calculations. Only document owners can start timing.

```APIDOC
## POST /docs/{docId}/timing/start

### Description
Start collecting timing information for formula calculations. Only document owners can start timing.

### Method
POST

### Endpoint
https://{gristhost}/api/docs/{docId}/timing/start

### Parameters
#### Path Parameters
- **docId** (string) - Required - A string id (UUID)

### Response
#### Success Response (200)
- Timing started successfully
```

--------------------------------

### GET /widgets

Source: https://support.getgrist.com/api

Get all widget definitions from the configured widget repository.

```APIDOC
## GET /widgets

### Description
Get all widget definitions from the configured widget repository. Custom widgets extend Grist's functionality with specialized views.

### Method
GET

### Endpoint
https://{gristhost}/api/widgets

### Response
#### Success Response (200)
- **name** (string) - Widget name
- **url** (string) - Widget URL
- **widgetId** (string) - Unique widget identifier

#### Response Example
[
  {
    "name": "string",
    "url": "string",
    "widgetId": "string"
  }
]
```

--------------------------------

### SEARCH function examples

Source: https://support.getgrist.com/functions

Finds the starting position of a substring within a string, case-insensitive.

```python
>>> SEARCH("e", "Statements", 6)
7
```

```python
>>> SEARCH("margin", "Profit Margin")
8
```

```python
>>> SEARCH(" ", "Profit Margin")
7
```

```python
>>> SEARCH('"', 'The "boss" is here.')
5
```

```python
>>> SEARCH("gle", "Google")
4
```

```python
>>> SEARCH("GLE", "Google")
4
```

--------------------------------

### Gitea OIDC Configuration Example

Source: https://support.getgrist.com/install/oidc

Example environment variables for configuring Grist to use Gitea as an OIDC Identity Provider. Ensure Gitea application redirect URI is set to `https://<grist-domain>/oauth2/callback`.

```shell
GRIST_OIDC_SP_HOST=https://<grist-domain> # or http://localhost:8484
GRIST_OIDC_IDP_ISSUER=https://<gitea-domain> # the /.well-known/openid-configuration part is added automatically
GRIST_OIDC_IDP_SCOPES=openid profile email
```

--------------------------------

### GET SQL Query Response Format

Source: https://support.getgrist.com/api

Example JSON response structure returned by the GET /docs/{docId}/sql endpoint.

```json
{
  "statement": "select * from Pets ...",
  "records": [
    {
      "fields": {
        "id": 1,
        "pet": "cat",
        "popularity": 67
      }
    },
    {
      "fields": {
        "id": 2,
        "pet": "dog",
        "popularity": 95
      }
    }
  ]
}
```

--------------------------------

### Search Groups Response Example

Source: https://support.getgrist.com/api

Example JSON response returned by the search endpoint containing a list of matching groups.

```json
{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
],
  "totalResults": 0,
  "Resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group"
],
      "meta": {
        "resourceType": "Group",
        "location": "/api/scim/v2/Groups/1"
},
      "id": "1",
      "displayName": "Engineering",
      "members": [
        {
          "value": "1",
          "display": "John Doe",
          "type": "User",
          "$ref": "/api/scim/v2/Users/1"
}
]
}
]

}
```

--------------------------------

### SUM function examples

Source: https://support.getgrist.com/functions

Sums a series of numbers or arrays.

```python
>>> SUM([5,15,30])
50
```

```python
>>> SUM([5.,15,30], 2)
52.0
```

```python
>>> SUM(5,15,[30],[2])
52
```

--------------------------------

### Gitlab OIDC Configuration Example

Source: https://support.getgrist.com/install/oidc

Example environment variables for configuring Grist to use Gitlab as an OIDC Identity Provider. Ensure Gitlab application redirect URI is set to `https://<grist-domain>/oauth2/callback`.

```shell
GRIST_OIDC_SP_HOST=https://<grist-domain> # or http://localhost:8484
GRIST_OIDC_IDP_ISSUER=https://gitlab.com/.well-known/openid-configuration
GRIST_OIDC_IDP_SCOPES=openid profile email

# the client ID generated by Gitlab for the application
GRIST_OIDC_IDP_CLIENT_ID=...

# the client secret generated by Gitlab for the application
GRIST_OIDC_IDP_CLIENT_SECRET=...

# Gitlab doesn't propose `end_session_endpoint`
GRIST_OIDC_IDP_SKIP_END_SESSION_ENDPOINT=true
```

--------------------------------

### T function examples

Source: https://support.getgrist.com/functions

Returns the input if it is text, otherwise returns an empty string.

```python
>>> T('Text')
u'Text'
```

```python
>>> T(826)
u''
```

```python
>>> T('826')
u'826'
```

```python
>>> T(False)
u''
```

```python
>>> T('100 points')
u'100 points'
```

```python
>>> T(AltText('Text'))
u'Text'
```

```python
>>> T(float('nan'))
u''
```

--------------------------------

### Describe Organization Response

Source: https://support.getgrist.com/api

Example JSON response for a single organization object.

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

--------------------------------

### Prepare Host Environment

Source: https://support.getgrist.com/install/example-docker-nginx

Create the required directory structure for configuration, data, and database storage.

```bash
sudo -u "$(id -un 1000):$(id -un 1000)" mkdir -p ./config/nginx/site-confs ./data ./database/data
```

--------------------------------

### Example Direct URL for Tutorial

Source: https://support.getgrist.com/document-tutorials

This is the main link to your Grist document. When marked as a tutorial, visiting this URL automatically redirects users to their own fork.

```url
https://docs.getgrist.com/doc/woXtXUBmiN5T
```

--------------------------------

### Set Up Grist Snapshots with MinIO

Source: https://support.getgrist.com/self-managed

Example of running Grist locally with a MinIO instance for document snapshots using Docker.

```bash
# Make a network
docker network create grist

# Start Redis in our network (recommended for snapshots)
docker run --rm --network grist --name redis redis

# Start MinIO in our network
docker run --rm --network grist --name minio \
  -v /tmp/minio:/data \
  -p 9000:9000 -p 9001:9001 \
  -e MINIO_ROOT_USER=grist -e MINIO_ROOT_PASSWORD=admingrist \
   -it minio/minio server /data -console-address ":9001"

# Visit http://localhost:9000 and set up a bucket called grist-docs.
# Make sure to enable versioning on the bucket.

# Hook Grist up to Redis and MinIO
docker run --rm --network grist \
  -e GRIST_DOCS_MINIO_ACCESS_KEY=grist \
  -e GRIST_DOCS_MINIO_SECRET_KEY=admingrist \
  -e GRIST_DOCS_MINIO_USE_SSL=0 \
  -e GRIST_DOCS_MINIO_BUCKET=grist-docs \
  -e GRIST_DOCS_MINIO_ENDPOINT=minio \
  -e GRIST_DOCS_MINIO_PORT=9000 \
  -e REDIS_URL=redis://redis \
  -v /tmp/grist:/persist -p 8484:8484 -it gristlabs/grist
```

--------------------------------

### Example Default Mode URL for Tutorial

Source: https://support.getgrist.com/document-tutorials

This link opens the original version of the Grist document, allowing the owner to edit the tutorial directly. Append '/m/default' to the Direct URL to access this mode.

```url
https://docs.getgrist.com/doc/woXtXUBmiN5T/m/default
```

--------------------------------

### GET /docs/{docId}/forms/{viewSectionId}

Source: https://support.getgrist.com/api

Get the form configuration for a specific view section.

```APIDOC
## GET /docs/{docId}/forms/{viewSectionId}

### Description
Get the form configuration for a specific view section. Forms are a special view type that allows external users to submit data.

### Method
GET

### Endpoint
https://{gristhost}/api/docs/{docId}/forms/{viewSectionId}

### Parameters
#### Path Parameters
- **docId** (string) - Required - A string id (UUID)
- **viewSectionId** (integer) - Required - ID of the view section (form)

### Response
#### Success Response (200)
- **formFieldsById** (object) - Form fields mapping
- **formLayoutSpec** (string) - Layout specification
- **formTableId** (string) - Table ID associated with the form
- **formTitle** (string) - Title of the form

#### Response Example
{
  "formFieldsById": { },
  "formLayoutSpec": "string",
  "formTableId": "string",
  "formTitle": "string"
}
```

--------------------------------

### View boot key in logs

Source: https://support.getgrist.com/install/first-run-setup

Locate the boot key in the server startup output to authenticate the initial session.

```text
┌──────────────────────────────────────────┐
│                                          │
│   BOOT KEY: ••••••••••••••••••••••••••   │
│                                          │
│   Use this key at /boot to sign in.      │
│                                          │
└──────────────────────────────────────────┘
```

--------------------------------

### Grist Object Type Examples

Source: https://support.getgrist.com/code/modules/GristData

Examples of how different Grist object types are represented as tuples.

```json
["L", "foo", "bar"]
```

```json
["l", value, options]
```

```json
["O", {key: value, ...}]
```

```json
["D", 1704945919, "UTC"]
```

```json
["d", 1704844800]
```

```json
["C"]
```

```json
["R", "People", 17]
```

```json
["r", "People", [1,2]]
```

```json
["E", "ValueError"]
```

```json
["P"]
```

```json
["U", text_representation]
```

```json
["V", version_obj]
```

--------------------------------

### Get users for View As feature response

Source: https://support.getgrist.com/api

The response structure for the GET /docs/{docId}/usersForViewAs endpoint.

```json
{
  "users": [
    {
      "id": 101,
      "name": "Helga Hufflepuff",
      "picture": null
    }
  ],
  "attributeTableUsers": [
    {
      "id": 101,
      "name": "Helga Hufflepuff",
      "picture": null
    }
  ],
  "exampleUsers": [
    {
      "id": 101,
      "name": "Helga Hufflepuff",
      "picture": null
    }
  ]
}
```

--------------------------------

### Tutorial Opened Event

Source: https://support.getgrist.com/telemetry-full

This event is triggered whenever a tutorial is opened by a user, capturing details about the tutorial and user progress.

```APIDOC
## tutorialOpened#

### Description
Triggered when a tutorial is opened.

### Fields
- **tutorialForkIdDigest** (string) - A hash of the tutorial fork id.
- **tutorialTrunkIdDigest** (string) - A hash of the tutorial trunk id.
- **lastSlideIndex** (number) - The 0-based index of the last tutorial slide the user had open.
- **numSlides** (number) - The total number of slides in the tutorial.
- **percentComplete** (number) - Percentage of tutorial completion.
- **userId** (number) - The id of the user that triggered this event.
- **altSessionId** (string) - A random, session-based identifier for the user that triggered this event.
```

--------------------------------

### grist.ready

Source: https://support.getgrist.com/widget-custom

Initializes the widget and registers configuration handlers.

```APIDOC
## grist.ready(config)

### Description
Signals that the widget is ready and provides configuration handlers, such as onEditOptions for custom configuration screens.

### Parameters
- **config** (object) - Required - Configuration object containing the onEditOptions handler.
```

--------------------------------

### Initialize Grist Widget and Subscribe to Events

Source: https://support.getgrist.com/widget-custom

Use these methods to signal readiness and listen for changes in records or configuration.

```javascript
grist.ready();
grist.onRecord(function (record) {
  // Cursor has moved.
});
grist.onRecords(function (records) {
  // Data in the table has changed.
});
grist.onOptions(function (options, interaction) {
  // Configuration has changed.
});
```

--------------------------------

### lookupRecords implementation example

Source: https://support.getgrist.com/references-lookups

An example of using lookupRecords to match emails between the All_Registrations table and the current table.

```Grist Formula
All_Registrations.lookupRecords(Registration_Email=$Email)
```

--------------------------------

### Retrieve list of roles response sample

Source: https://support.getgrist.com/api

Example JSON response for a successful request to list all roles.

```json
{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
],
  "totalResults": 1,
  "itemsPerPage": 20,
  "startIndex": 1,
  "Resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:Grist:1.0:Role"
],
      "meta": {
        "resourceType": "Role",
        "location": "/api/scim/v2/Roles/1"
},
      "id": "1",
      "displayName": "owners",
      "members": [
        {
          "value": "1",
          "display": "Engineering",
          "type": "Group",
          "$ref": "/api/scim/v2/Groups/1"
}
],
      "orgId": 1
}
]

}
```

--------------------------------

### Install Python packages in JupyterLite

Source: https://support.getgrist.com/widget-custom

Use the %pip magic command to install third-party libraries directly within a notebook cell.

```python
%pip install pandas
```

--------------------------------

### Enable custom CSS styling

Source: https://support.getgrist.com/self-managed

Set APP_STATIC_INCLUDE_CUSTOM_CSS to true to load a custom.css file. Rules should use !important to ensure precedence.

```bash
docker run
  ...
  -e APP_STATIC_INCLUDE_CUSTOM_CSS=true \
  ...
```

--------------------------------

### Configure OpenRouter endpoint and key

Source: https://support.getgrist.com/install/assistant

Set the required environment variables to use OpenRouter as the AI provider.

```bash
ASSISTANT_CHAT_COMPLETION_ENDPOINT=https://openrouter.ai/api/v1/chat/completions
ASSISTANT_API_KEY=your_openrouter_api_key_here
```

--------------------------------

### Markdown widget templating function example

Source: https://support.getgrist.com/newsletters/2024-07

Provides an example of an updated Markdown widget templating function for Grist. This function simplifies replacing fields within a template, including those nested within references.

```Grist Formula
f"{{ """Hello {{user.name}}!""" | markdown }}"
```

--------------------------------

### grist.ready

Source: https://support.getgrist.com/widget-custom

Initializes the widget and defines the required or optional columns that the user must map in the creator panel.

```APIDOC
## grist.ready(options)

### Description
Notifies Grist that the widget is ready and provides configuration for column mapping. This triggers the display of column pickers in the creator panel.

### Parameters
- **options** (object) - Required - Configuration object containing:
  - **columns** (array) - List of column definitions (strings or objects).
  - **requiredAccess** (string) - Access level required (e.g., 'read table').

### Column Definition Object
- **name** (string) - The internal field name.
- **title** (string) - Friendly label for the user.
- **optional** (boolean) - Whether the column is required.
- **type** (string) - Expected column type (e.g., 'Text', 'Int', 'Date').
- **description** (string) - Helper text for the user.
- **allowMultiple** (boolean) - Whether to allow multiple column selection.
```

--------------------------------

### Tutorial Restarted Event

Source: https://support.getgrist.com/telemetry-full

This event is triggered when a user restarts a tutorial, capturing context about the restart.

```APIDOC
## tutorialRestarted#

### Description
Triggered when a tutorial is restarted.

### Fields
- **tutorialForkIdDigest** (string) - A hash of the tutorial fork id.
- **tutorialTrunkIdDigest** (string) - A hash of the tutorial trunk id.
- **docIdDigest** (string) - A hash of the doc id.
- **siteId** (number) - The site id.
- **siteType** (string) - The site type.
- **altSessionId** (string) - A random, session-based identifier for the user that triggered this event.
- **access** (string) - The document access level of the user that triggered this event.
- **userId** (number) - The id of the user that triggered this event.
```

--------------------------------

### FACT Function Examples

Source: https://support.getgrist.com/functions

Calculates the factorial of a number.

```python
>>> FACT(5)
120
```

```python
>>> FACT(1.9)
1
```

```python
>>> FACT(0)
1
```

```python
>>> FACT(1)
1
```

```python
>>> FACT(-1)
Traceback (most recent call last):
  ...
ValueError: factorial() not defined for negative values
```

--------------------------------

### Signup First Visit Event

Source: https://support.getgrist.com/telemetry-full

This event fires when a new user opens the Grist application for the very first time after signing up.

```APIDOC
## signupFirstVisit#

### Description
Triggered when a new user first opens the Grist app.

### Fields
- **loginMethod** (string) - The login method on getgrist.com. May be “Email + Password” or “Google”.
- **siteId** (number) - The site id of first visit after signup.
- **siteType** (string) - The site type of first visit after signup.
- **userId** (number) - The id of the user that signed up.
- **altSessionId** (string) - A random, session-based identifier for the user that triggered this event.
```

--------------------------------

### DEGREES Function Examples

Source: https://support.getgrist.com/functions

Converts radians to degrees.

```python
>>> round(DEGREES(ACOS(-0.5)), 10)
120.0
```

```python
>>> DEGREES(PI())
180.0
```

--------------------------------

### Implement Custom Image Display Widget

Source: https://support.getgrist.com/widget-custom

A complete example showing how to load the Grist API and display data from specific columns.

```html
<script src="https://docs.getgrist.com/grist-plugin-api.js"></script>
<img id="image" src=""/>
<div id="title"></div>
<script>
  grist.ready({requiredAccess: 'read table'});
  grist.onRecord(function (record) {
    document.getElementById('image').src = record.Link;
    document.getElementById('title').innerText = record.Title;
  });
</script>
```

--------------------------------

### GET /api/service-accounts

Source: https://support.getgrist.com/api

Lists all service accounts associated with the user.

```APIDOC
## GET /api/service-accounts

### Description
Lists all your service accounts with their details.

### Method
GET

### Endpoint
https://{gristhost}/api/service-accounts

### Responses
#### Success Response (200)
- **id** (integer) - Service account ID
- **login** (string) - Service account login identifier
- **label** (string) - Service account display name
- **description** (string) - Purpose of the service account
- **expiresAt** (string) - Expiration date
- **hasValidKey** (boolean) - Status of the API key

#### Response Example
[
  {
    "id": 42,
    "login": "aa52e4c7-e451-409a-8140-4eb17844e8b9@serviceaccounts.invalid",
    "label": "n8n",
    "description": "For data import workflow",
    "expiresAt": "2042-10-10T00:00:00.000Z",
    "hasValidKey": true
  }
]
```

--------------------------------

### GET /api/orgs/{orgId}

Source: https://support.getgrist.com/api

Retrieves details for a specific organization.

```APIDOC
## GET /api/orgs/{orgId}

### Description
Retrieves details for a specific organization identified by ID or subdomain.

### Method
GET

### Endpoint
https://{gristhost}/api/orgs/{orgId}

### Parameters
#### Path Parameters
- **orgId** (integer or string) - Required - 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

### Response
#### Success Response (200)
- **Object** - An organization
```

--------------------------------

### PostgreSQL Environment Variables

Source: https://support.getgrist.com/install/example-docker-nginx

Configuration file for the PostgreSQL database credentials.

```text
# https://hub.docker.com/_/postgres

POSTGRES_DB=grist
POSTGRES_USER=grist
POSTGRES_PASSWORD=mysupersecretpassword CHANGE THIS!!!!
```

--------------------------------

### Event Handling and Lifecycle Methods

Source: https://support.getgrist.com/code/modules/grist_plugin_api

Methods for registering event listeners and declaring widget readiness.

```APIDOC
## on

### Description
Adds a listener function for a specific event name.

### Parameters
#### Request Body
- **eventName** (string | symbol) - Required - The name of the event.
- **listener** (function) - Required - The callback function.

### Returns
- **Rpc** - Reference to the EventEmitter for chaining.

## onNewRecord

### Description
Adds a handler called whenever a new (blank) row is selected.

### Parameters
#### Request Body
- **callback** (function) - Required - Handler receiving mappings.

## onOptions

### Description
Adds a handler called whenever widget options change.

### Parameters
#### Request Body
- **callback** (function) - Required - Handler receiving options and interaction settings.

## onRecord

### Description
Adds a handler called whenever the row with the cursor changes.

### Parameters
#### Request Body
- **callback** (function) - Required - Handler receiving row data and mappings.
- **options** (FetchSelectedOptions) - Optional - Fetch options.

## onRecords

### Description
Adds a handler called whenever the selected records change.

### Parameters
#### Request Body
- **callback** (function) - Required - Handler receiving array of records and mappings.
- **options** (FetchSelectedOptions) - Optional - Fetch options.

## ready

### Description
Declares that the component is prepared to receive messages from Grist.

### Parameters
#### Request Body
- **settings** (ReadyPayload) - Optional - Initialization settings.
```

--------------------------------

### RIGHT function examples

Source: https://support.getgrist.com/functions

Extracts a substring from the end of a string.

```python
>>> RIGHT("Sale Price", 5)
'Price'
```

```python
>>> RIGHT('Stock Number')
'r'
```

```python
>>> RIGHT('Text', 100)
'Text'
```

```python
>>> RIGHT('Text', -1)
Traceback (most recent call last):
...
ValueError: num_chars invalid
```

--------------------------------

### INT Function Examples

Source: https://support.getgrist.com/functions

Rounds a number down to the nearest integer.

```python
>>> INT(8.9)
8
```

```python
>>> INT(-8.9)
-9
```

```python
>>> 19.5-INT(19.5)
0.5
```

--------------------------------

### config.create

Source: https://support.getgrist.com/install/audit-log-events

Logs an event when a configuration item is created.

```APIDOC
## POST /config/create

### Description
A configuration item was created.

### Method
POST

### Endpoint
/config/create

### Request Body
- **config** (object) - Required - The created configuration item.
  - **config.id** (number) - Required - The configuration item ID.
  - **config.key** (string) - Required - The configuration item key.
  - **config.value** (any) - Required - The configuration item value.
  - **config.site** (object) - Optional - The site this configuration item belongs to.
    - **config.site.id** (number) - Required - The site ID.
    - **config.site.name** (string) - Required - The site name.
    - **config.site.domain** (string) - Required - The site domain.

### Request Example
```json
{
  "config": {
    "id": 18,
    "key": "audit_log_streaming_destinations",
    "value": [
      {
        "id": "ee6971af-80f5-4654-9bd2-5c6ab33e7ccf",
        "name": "splunk",
        "url": "https://hec.example.com:8088/services/collector/event",
        "token": "Splunk B5A79AAD-D822-46CC-80D1-819F80D7BFB0"
      }
    ],
    "site": {
      "id": 42,
      "name": "Grist Labs",
      "domain": "gristlabs"
    }
  }
}
```

### Response
#### Success Response (200)
- **config** (object) - The created configuration item.
  - **config.id** (number) - The configuration item ID.
  - **config.key** (string) - The configuration item key.
  - **config.value** (any) - The configuration item value.
  - **config.site** (object) - Optional - The site this configuration item belongs to.
    - **config.site.id** (number) - The site ID.
    - **config.site.name** (string) - The site name.
    - **config.site.domain** (string) - The site domain.

#### Response Example
```json
{
  "config": {
    "id": 18,
    "key": "audit_log_streaming_destinations",
    "value": [
      {
        "id": "ee6971af-80f5-4654-9bd2-5c6ab33e7ccf",
        "name": "splunk",
        "url": "https://hec.example.com:8088/services/collector/event",
        "token": "Splunk B5A79AAD-D822-46CC-80D1-819F80D7BFB0"
      }
    ],
    "site": {
      "id": 42,
      "name": "Grist Labs",
      "domain": "gristlabs"
    }
  }
}
```
```

--------------------------------

### Organization Usage Summary Response

Source: https://support.getgrist.com/api

Example JSON response showing organization usage statistics and data limits.

```json
{
  "countsByDataLimitStatus": {
    "approachingLimit": 0,
    "gracePeriod": 0,
    "deleteOnly": 0
  },
  "attachments": {
    "totalBytes": 0,
    "limitExceeded": true
  }
}
```

--------------------------------

### FACTDOUBLE Function Examples

Source: https://support.getgrist.com/functions

Calculates the double factorial of a number.

```python
>>> FACTDOUBLE(6)
48
```

```python
>>> FACTDOUBLE(7)
105
```

```python
>>> FACTDOUBLE(3)
3
```

```python
>>> FACTDOUBLE(4)
8
```

--------------------------------

### COS Function Examples

Source: https://support.getgrist.com/functions

Calculates the cosine of an angle in radians.

```python
>>> round(COS(1.047), 7)
0.5001711
```

```python
>>> round(COS(60*PI()/180), 10)
0.5
```

```python
>>> round(COS(RADIANS(60)), 10)
0.5
```

--------------------------------

### Configure custom widget gallery

Source: https://support.getgrist.com/self-managed

Set GRIST_WIDGET_LIST_URL to a manifest.json file to provide a list of pre-built custom widgets in the UI.

```bash
docker run
  ...
  -e GRIST_WIDGET_LIST_URL="https://github.com/gristlabs/grist-widget/releases/download/latest/manifest.json" \
  ...
```

--------------------------------

### GET /profile/user

Source: https://support.getgrist.com/api

Returns the profile information of the currently authenticated user.

```APIDOC
## GET /profile/user

### Description
Returns the profile information of the currently authenticated user.

### Method
GET

### Endpoint
https://{gristhost}/api/profile/user

### Response
#### Success Response (200)
- **id** (integer) - User ID
- **name** (string) - User display name
- **picture** (null) - User profile picture

#### Response Example
{
  "id": 101,
  "name": "Helga Hufflepuff",
  "picture": null
}
```

--------------------------------

### GET /scim/v2/Groups/{groupId}

Source: https://support.getgrist.com/api

Retrieves the details of a specific group by its ID.

```APIDOC
## GET /scim/v2/Groups/{groupId}

### Description
Retrieves the details of a group identified by the provided groupId. Requires an API key for authorization.

### Method
GET

### Endpoint
https://{gristhost}/api/scim/v2/Groups/{groupId}

### Parameters
#### Path Parameters
- **groupId** (integer) - Required - A group id

### Response
#### Success Response (200)
- **id** (string) - The ID of the group.
- **displayName** (string) - The display name of the group.

#### Response Example
{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "meta": {
    "resourceType": "Group",
    "location": "/api/scim/v2/Groups/1"
  },
  "id": "1",
  "displayName": "Engineering",
  "members": [
    {
      "value": "1",
      "display": "John Doe",
      "type": "User",
      "$ref": "/api/scim/v2/Users/1"
    }
  ]
}
```

--------------------------------

### Get all widget options

Source: https://support.getgrist.com/code/modules/grist_plugin_api

Use `getOptions` to retrieve all options stored by the widget. Options are stored as a plain JSON object.

```javascript
getOptions()
```

--------------------------------

### GET /scim/v2/Schemas

Source: https://support.getgrist.com/api

Retrieve the SCIM schemas supported by the Grist instance.

```APIDOC
## GET /scim/v2/Schemas

### Description
Retrieve the SCIM schemas supported by the Grist instance.

### Method
GET

### Endpoint
https://{gristhost}/api/scim/v2/Schemas

### Response
#### Success Response (200)
- Successfully retrieved schemas.

#### Error Response
- 401: Unauthenticated
- 500: Internal server error
```

--------------------------------

### assistantStartDocument Event

Source: https://support.getgrist.com/telemetry-full

This event is triggered when a user begins the process of creating a document using the AI Assistant.

```APIDOC
## assistantStartDocument

### Description
Triggered when a user begins the process of creating a document using the AI Assistant.

### Method
POST

### Endpoint
/websites/support_getgrist

### Request Body
- **userId** (number) - Required - The id of the user that triggered this event.
- **altSessionId** (string) - Required - A random, session-based identifier for the user that triggered this event.
- **prompt** (string) - Required - The message sent to the AI Assistant.

### Request Example
```json
{
  "userId": 101,
  "altSessionId": "session_abcde",
  "prompt": "Create a document about project management."
}
```

### Response
#### Success Response (200)
(No specific response fields defined for this event.)
```

--------------------------------

### Sample Config Created Event

Source: https://support.getgrist.com/install/audit-log-events

This JSON represents an audit log event when a configuration item is created. It includes details of the new configuration.

```json
{
  "config": {
    "id": 18,
    "key": "audit_log_streaming_destinations",
    "value": [
      {
        "id": "ee6971af-80f5-4654-9bd2-5c6ab33e7ccf",
        "name": "splunk",
        "url": "https://hec.example.com:8088/services/collector/event",
        "token": "Splunk B5A79AAD-D822-46CC-80D1-819F80D7BFB0"
      }
    ],
    "site": {
      "id": 42,
      "name": "Grist Labs",
      "domain": "gristlabs"
    }
  }
}

```

--------------------------------

### GET /api/scim/v2/Users/{userId}

Source: https://support.getgrist.com/api

Retrieves the details of a specific user by their ID.

```APIDOC
## GET /api/scim/v2/Users/{userId}

### Description
Retrieves user details for a specified user ID.

### Method
GET

### Endpoint
https://{gristhost}/api/scim/v2/Users/{userId}

### Parameters
#### Path Parameters
- **userId** (integer) - Required - A user id

### Response
#### Success Response (200)
- **meta** (object) - Resource metadata
- **id** (string) - User ID
- **schemas** (array) - SCIM schema URNs
- **userName** (string) - User email/username
- **name** (object) - User name details
- **emails** (array) - List of email objects
- **displayName** (string) - User display name
- **preferredLanguage** (string) - Preferred language
- **locale** (string) - User locale
- **photos** (array) - List of photo objects

#### Response Example
{
  "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": [{ "value": "https://example.com/pics/john-doe.png", "primary": true, "type": "photo" }]
}
```

--------------------------------

### GET /docs/{docId}/attachments/archive

Source: https://support.getgrist.com/api

Downloads all attachments for a document as an archive.

```APIDOC
## GET /docs/{docId}/attachments/archive

### Description
Downloads all attachments associated with a document in a compressed archive format.

### Method
GET

### Endpoint
https://{gristhost}/api/docs/{docId}/attachments/archive

### Parameters
#### Path Parameters
- **docId** (string) - Required - A string id (UUID)

#### Query Parameters
- **format** (string) - Optional - Archive format: "zip" or "tar"

### Response
#### Success Response (200)
- Archive of all attachments, in either .zip or .tar format.
```

--------------------------------

### answeredUseCaseQuestion

Source: https://support.getgrist.com/telemetry-full

Triggered for each selected use case in the welcome questionnaire.

```APIDOC
## answeredUseCaseQuestion

### Description
Triggered for each selected use case in the welcome questionnaire.

### Request Body
- **useCase** (string) - The selected use case. If “Other”, the response is also included.
- **userId** (number) - The id of the user that triggered this event.
```

--------------------------------

### GET /docs/{docId}

Source: https://support.getgrist.com/api

Retrieves metadata for a specific document by its ID.

```APIDOC
## GET /docs/{docId}

### Description
Retrieves metadata for a specific document.

### Method
GET

### Endpoint
https://{gristhost}/api/docs/{docId}

### Parameters
#### Path Parameters
- **docId** (string) - Required - A string id (UUID)

### Response
#### Success Response (200)
- **metadata** (object) - A document's metadata

#### Response Example
{
  "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"
    }
  }
}
```

--------------------------------

### SUMPRODUCT function examples

Source: https://support.getgrist.com/functions

Multiplies corresponding components in arrays and returns the sum of products.

```python
>>> SUMPRODUCT([3,8,1,4,6,9], [2,6,5,7,7,3])
156
```

```python
>>> SUMPRODUCT([], [], [])
0
```

```python
>>> SUMPRODUCT([-0.25], [-2], [-3])
-1.5
```

```python
>>> SUMPRODUCT([-0.25, -0.25], [-2, -2], [-3, -3])
-3.0
```
Tokens:
Raw