API: List Docs returning incomplete response

I’m trying to list all the docs that a user has access to using the API.

The docs say that the /docs endpoint should give me “a list of Coda docs accessible by the user.”

It’s not doing this though; it’s just giving me a list of the docs that the user has gone ahead and opened at some point (it’s not including docs that were shared with the user, whether directly or via folder-level or workspace-level sharing, but not yet opened).

It’s not an API key scoping issue; I can open a doc, re-run the API call, and get the new doc included in the response.

(The reason this is coming up is that I’m doing some stuff with the Doc List Pack, and thought it prudent to create a service account that didn’t have access to all my private docs, since I want to share the Pack account / API key with other users of this doc. So it’s worth noting that this user is only ~half an hour old - could be contributing to the issue…?)

I’ve tried this in Postman, and in the Coda Doc List Pack; same results.

Anybody experience this? Am I misinterpreting the intended behaviour?

Thanks for raising this @Nick_HE. I spoke with some engineers, and it looks like the API documentation is currently out of sync with the API behavior. Namely, the API only returns the docs the user has opened / accessed, not all the docs that are accessible. Truly returning all the docs that are accessible would be strange behavior, as it would include every doc that users share publicly.

The Coda UI uses a slightly different heuristic, including docs that are shared with you personally, with the workspace, etc. However for publicly shared docs it sensibly only includes the ones that the user has opened / accessed.

Long term we hope to bring the API and Coda UI in sync, but doing so may be considered a breaking change, so we’ll need to think about it carefully. In the mean time I’ll update the API documentation to better reflect the current state of the endpoint.

In that case, how do you recommend approaching this use case?

  • We have a folder shared amongst our team that contains project tracking docs, one per project
  • I need to get a list of all the docs in this folder. Some were created by me, but some were created by my colleagues. However, we need to see a list of all the docs created by everyone.
  • Since we don’t all work on the same projects, none of us has opened every doc in the folder

I think that the behaviour should be “all Coda docs accessible by the user”, though I agree with you that “all Coda docs accessible by the user” should be defined as “specifically shared directly with the user, residing in a folder the user is shared on, or shared with the user’s workspace, but NOT all public Coda docs in the world (only those they’ve opened/accessed)”.

Since the API is designed to manipulate Coda data programmatically, I don’t think it should be contingent on something UI-ish like opening a doc.

Perhaps this could be a separate API endpoint so as not to break things for others?

Somewhat tangentially: I was surprised to see that in the UI, my service account user could see all the docs that I (as my regular user) had previously shared as public, i.e. “anyone with the link”.

While of course a doc with those permissions shouldn’t be considered strictly confidential, I had been relying on a certain amount of security through obscurity, and didn’t expect it to surface in search results / doc lists (whether inside or outside my Coda org). This is the behaviour I’ve come to expect from other services (YouTube, for example), where “unlisted” / “anyone with the link” means that knowing the link is the only way to discover the content.

What are your thoughts on this? Is there another permission set I should be using here?

Might as well continue with the API theme here. Is there no way to move docs between folders with the API (not copy, but move)? Perhaps that could be added if not?

Agree - this is concerning and the YouTube example is how I would have expected Coda to function as well

I use the “anyone with link” option often but do rely on users having to be GIVEN the link itself in order to access.

G docs works this way, YouTube, etc

1 Like

I did some testing, and it looks like when you filter by the folderId then all the docs in that folder are returned, whether you’ve opened them or not. Try limiting your query to the specific folder and see if that works.

I think the idea is that opening or interacting with the doc is a sort of consent that the doc is meaningful to you.

Good feedback! Probably worth posting in Suggestion Box to get more eyes on it.

Ah ok great, that will work for my case then. I’ll need to make my own Pack, because the first-party Doc List Pack doesn’t have a folder parameter, oddly. Unless you know who I need to talk to for that feature request?

Thanks for your help.