Listing sites, documents, tables, and columns via API

Developers
1

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
3

Context

  • I am self-hosting Grist using the docker-compose file + the specific instructions to allow remote clients.
  • I am now trying to access the records in a table via Grist’s API and I am adapting the above instructions. I am using Insomnia to streamline and modularize the connection process.

What I am able to access

  • the “Organization” : Insomnia authorization + http://[server_ip]:8384/api/orgs
  • the “Documents” : Insomnia authorization + http://[server_ip]:8384/api/orgs/current/workspaces
  • the detail of a specific Document: http://[server_ip]:8384/api/docs/[doc_id]

What I would need help with

I would now like to access:

  1. the tables in the specific document
  2. then the records in a specific table of the specific document

So, for #1, I tried (as per the above documentation):
http://[server_ip]:8384/api/docs/[doc_id]/tables/_grist_Tables/records

But it did not work and I get an error: not found.

What am I doing wrong?
Best,
Stephen

4

Your URL looks right and works for me.

/records is fairly new, I wonder if somehow you have an outdated docker image or something. Do you get a result if you replace /records with /data?