New API feature request : POST grist file

Hello everyone,

At now the Grist API allows to download a document in its grist format (sqlite) : GET /{docId}/download.

We would also like to be able to POST a grist document. Alternatively, it could also be a route to call the duplicate function that already exists in grist.

Our use case : we have a template file (with specific views, access rules etc) that we want to use as a base file when we create a new document.

Would it be conceivable to add this feature ? Does anyone would be also interested by this feature ?

Do I create a new issue on github about it ?

Thank you,


PS : @dmitry-grist we could have a budget to see this feature added

POSTing a grist document is just about possible through some undocumented heroics. It would definitely be great to have a simple, documented endpoint for this.

First, there is undocumented endpoint that almost works - you can POST a .grist file to /api/docs - but it will only give you an “unsaved” document, not something in a workspace:

The endpoint has a TODO to support specifying a workspace which, if implemented, would allow creating a regular document in a workspace. I suspect completing the TODO would not be difficult, it just wasn’t necessary for the specific job this was put in place for.

There is an alternative sequence of operations possible to POST a document to a workspace, using a pair of undocumented endpoints, /uploads and /api/workspaces/<workspace-id>/import. I see that sequence used in tests:

This is basically the process used by the Grist web app when the user uploads a .grist file. It is way more convoluted than it needs to be, because of steps in how Grist evolved from a pure desktop app to something that may involve multiple servers.

Creating an issue on github would be a good start. There are two main teams developing Grist: Grist Labs, and ANCT, and we collaborate primarily via github issues. We are also getting a stream of contributions from other Grist users.

I think @georgegevoian was looking at something adjacent to this recently related to copying documents, and may be adding a simplification there - but I don’t know if that is touching direct uploads, is it @georgegevoian ?

Unfortunately, the simplification targets a slightly different use case: making a copy of an already-uploaded Grist document. But as you mentioned, the /docs endpoint is almost there, and I think it would make a good first issue.

Agree. And the last issue that Florent tagged as a good-first-issue got picked up and implemented pretty quickly :slight_smile:

Thank you for your answers @paul-grist and @georgegevoian. The issue has just been created : API enhancement : upload a new document in a workspace · Issue #635 · gristlabs/grist-core · GitHub


Hello everybody,

We would need it pretty quickly.

Waiting for the issue to be implemented, we are trying to use the /uploads and /workspaces/:wid/import approach. Can we call the /uploads endpoint with the same bearer token we use for other api calls or is it intended to be authenticated through an app session ?

Thank you !

Also, our use-case could be very well answered by an easy way to make a copy of our template, which is a grist document on the same instance at now.

Hi @Xavier_de_Rochefort.

I’ll look into adding workspaceId as a parameter of /api/docs this week. The approach with the 2 undocumented endpoints has some gotchas, so I wouldn’t recommend it.


Thanks a lot @georgegevoian. Do you think that the docker image will be updated with that feature in the same time ?

The latest tag gets updated daily, so as soon as this PR is reviewed and merged the next update should include it.

1 Like

This is good news ! Thanks a lot !

1 Like

The next update to the image will include this feature. You just have to pass along workspaceId (either in the JSON body or form data), and (optionally) a documentName to the endpoint.

The same endpoint will soon also support duplicating a document, with an option to exclude all table data. (Essentially making it an API equivalent of the Duplicate Document dialog.)


Thanks a lot @georgegevoian ! That is very good news for us.