Listing sites, documents, tables, and columns via API

We are getting questions from integrators about how to enumerate material a user has access to, so I thought I’d summarize the basics here.

First, a user can have access to several sites. Everyone has access to docs.getgrist.com, called the “personal site.” They may also belong to other sites. For example, I’m a member of gristlabs.getgrist.com, a private site for the team developing Grist. In our API, sites are called “orgs” and can be enumerated by fetching:

https://docs.getgrist.com/api/orgs

See /orgs doc for details. The results will list sites, and subdomains (like gristlabs) to use to access them. For example, here are the orgs you have access to.

Once we’ve picked a site, the user will have access to documents and (in paid plans) workspaces. You can enumerate all the documents they have access to by fetching:

https://{subdomain}.getgrist.com/api/orgs/current/workspaces

See /workspaces doc for details. For example, here are the docs in your personal site.

Once we’ve picked a document, the user will have access to several tables. You can enumerate the tables they have access to by fetching:

https://{subdomain}.getgrist.com/api/docs/{docId}/tables/_grist_Tables/records

Here’s the result for an example document. The tableId fields are particularly important, they are what you need to delve in to access data. Once you’ve picked a table (by tableId), you can list its columns by fetching:

https://{subdomain}.getgrist.com/api/docs/{docId}/tables/{tableId}/columns

See /columns doc for details. Here’s a result for an example table. The id fields are particularly important.

Finally, to get all the records from the table, just fetch:

https://{subdomain}.getgrist.com/api/docs/{docId}/tables/{tableId}/records

See /records doc for details. We’ve actually already seen an example result, for the special _grist_Tables table that … lists tables!

Ok, that’s a quick overview of the relevant endpoints, hope it is helpful!

3 Likes