← Documentation

Grist

Grist is an open-source, self-hostable alternative to spreadsheets that combines the simplicity of a spreadsheet with the power of a relational database, enabling real-time collaboration, customizable workflows, and automation—ideal for teams and developers.

The Grist add-on allows you manage your WordPress posts as Grist spreadsheets, transforming how you and your team handles WordPress content.

The add-on

The Grist REST API can be used to integrate your data in Grist with any external system. The API closely follows REST semantics, uses JSON to encode objects, and relies on standard HTTP codes to signal operation outcomes. To talk with this API the add-on implements a custom bridge class based on the generic REST bridge that requires Bearer credentials.

A Grist bridge will synchronize your posts with records from your Grist spreadsheets. Each field of your spreadsheet can be mapped to a post field, post meta or taxonomy term.

With Posts Bridge introspection API you’ll be able to inspect spreadsheet fields to easily map them to your post fields and taxonomies.

How to use

The first step to use the add-on is to activate it in the add-ons table in the general settings tab.

Screenshot of the add-on panel on the general settings tab with the Grist add-on activated

Once activated, a new tab will be visible in the settings page. If it’s your first time, it should looks like this:

Grist tab out of the box without bridge configurations.

Bridge set up

A Grist bridge will require the following components:

1. Credential

The Grist API works with Bearer tokens to grant access to its resources. To solve this authentication requirement, the add-on requires you to register an API key in your Grist account.

Once you have the token, you have to go to Settings > Posts Bridge > HTTP > Authentication and register a new authentication credential. Select Bearer as the authentication schema and put the key value as the Access token field.

Screenshot of an Grist account dashboard

2. Backend

To configure the Grist API as a backend, follow this steps:

  1. Register a new backend with a unique name (Grist API, for example), and a URL with https://docs.getgrist.com as value for cloud services, or the base URL of your self hosted Grist instance.
  2. Select the Bearer credential you’ve configured on the previous step.

3. Post type

Posts Bridge allows you to bridge any registered post type from your WordPress site. If you’ve not registered it yet, you can register it with Posts Bridge. Go to the CPTs tab and create a new custom post type. The registration form will inherit the registration defaults, but you can modify its values at any time. The only required fields are Name, Label and Singular label.

4. Bridge

The add-on’s bridge is an extension of the generic REST bridge with some predefined defaults. Like the REST bridge, the addon’s bridge requires a post type, a backend, and an endpoint.

The endpoint of a Grist bridge should be like /api/docs/{docId}/tables/{tableName}/records. The docId can be extracted from the table URL. For example, the in the URL https://docs.getgrist.com/abc123456789/Example/p/1 the baseId is “abc123456789”. The tableName parameter of the URL is the name of your table.

Troubleshooting

To troubleshooting your bridges you can use the plugin’s debug console from the General Settings page. Enable the debug mode and submit a sample form response to see what’s going on under the hood.

Common issues

  1. Authentication failures
    • Verify API key
    • Verify backend URL
  2. Missing data
    • Verify table endpoints
    • Verify column names
    • Check field mapping
    • Consider API quotas and potential costs