Skip to content

Grist API Usage#

Grist has an API for manipulating documents, workspaces, and team sites.

Authentication#

To access the Grist API, you’ll need an API key. An API key is owned by a single user, and has the same permissions as that user.

Connected apps

An API key carries your full account access. For tools that act on your data on your behalf – partner products, internal apps, AI agents – a connected app is a safer choice: it can be authorized for specific documents and revoked individually, for greater security, control, and visibility. For building such tools, see OAuth apps.

API keys#

To enable API access for yourself, visit the Developer page of your account settings. You can always find this page by clicking your profile picture or initial on the top right of the screen, and selecting ‘Account settings’:

Account settings in user menu

The ‘Developer’ page has a section for API keys:

API key settings

Click on the ‘Create’ button to create an API Key. Copy it for use when making API calls.

You can revoke your API key by clicking the ‘Remove’ button at any time. You’ll then have the option to create a new one if you wish.

To test your API key, try this from the command-line (substituting your API key): 

curl -H "Authorization: Bearer <API-KEY-GOES-HERE>" https://docs.getgrist.com/api/orgs

This should return a list of organizations, i.e. team sites you have access to, and your personal site.

Usage#

To access documents on your personal site via the API, simply continue using the docs.getgrist.com domain. To access documents and workspaces on a team site, use <TEAM>.getgrist.com.

For example, to list all the workspaces and documents you have access to on a site, do:

curl -H "Authorization: Bearer <API-KEY-GOES-HERE>" \
  https://<docs|TEAM>.getgrist.com/api/orgs/current/workspaces

When making changes via the API, and passing data via the request body, be sure to set the Content-Type header to application/json. For example, to change the name of a document, you could do:

curl -XPATCH \
  -H "Authorization: Bearer <API-KEY-GOES-HERE>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Lesson Plans"}' \
  https://<docs|TEAM>.getgrist.com/api/docs/<DOC-ID-GOES-HERE>

For details of the endpoints available, see our API docs or the interactive API console.

API clients#

There are two client libraries developed and maintained by Grist Labs:

There are also several community-created and maintained clients in other flavors: