Coda API Migration Guide
We recently
a new, stable release of the API, Version 1.
Per our deprecation policy for the beta API, please migrate to the Version 1 API within 30 days of our deprecation notifications, that is, by
August 21, 2020
.
Version 1 of the API will be supported for at least the next 6 months (through January 15, 2021) and we will give at least 3 months notice before making any breaking changes on or after that date.

Migration should generally be straightforward. The core change is to use
v1
in your API urls instead of
v1beta1
. For example, the endpoint to list documents is now
https://coda.io/apis/v1/docs
instead of
https://coda.io/apis/v1beta1/docs
.

If you use Google Apps Script, see the
for details.

There are a handful of breaking changes that may require your attention.

Breaking Changes

Endpoints for views have been removed and merged with endpoints for tables

Previously, you would use a separate endpoint to list and modify views than you would to list and modify tables. We have simplified the API to no longer require separate endpoints. You can now pass a view id to all table endpoints.

For example, previously, to list all the rows in a view, you would use this view-specific endpoint:
https://coda.io/apis/v1beta1/docs/<docId>/views/<viewId>/rows

In the v1 API, you will instead pass that view id to the shared /tables/ endpoint:

https://coda.io/apis/v1/docs/<docId>/tables/<viewId>/rows

There also used to be separate endpoints for listing tables and views:

https://coda.io/apis/v1beta1/docs/<docId>/tables
https://coda.io/apis/v1beta1/docs/<docId>/views

Those have been combined into a single endpoint, and hitting
https://coda.io/apis/v1/docs/<docId>/tables
will return both tables and views. If you wish to return only one or the other, include a url parameter of the form or to restrict the results.

Specifically, if you use any of the following endpoints, you should migrate to the given new endpoint.

Old Endpoint
New Endpoint
1
/docs/{docId}/
views
/docs/{docId}/
tables
?tableTypes=view
2
/docs/{docId}/
views
/{viewIdOrName}
/docs/{docId}/
tables
/{viewIdOrName}
3
/docs/{docId}/
views
/{viewIdOrName}/rows
/docs/{docId}/
tables
/{viewIdOrName}/rows
4
/docs/{docId}/
views
/{viewIdOrName}/rows/{rowIdOrName}
/docs/{docId}/
tables
/{viewIdOrName}/rows/{rowIdOrName}
5
/docs/{docId}/
views
/{viewIdOrName}/rows/{rowIdOrName}
/docs/{docId}/
tables
/{viewIdOrName}/rows/{rowIdOrName}
6
/docs/{docId}/
views
/{viewIdOrName}/columns
/docs/{docId}/
tables
/{viewIdOrName}/columns
7
/docs/{docId}/
views
/{viewIdOrName}/rows/{rowIdOrName}/buttons/{columnIdOrName}
/docs/{docId}/
tables
/{viewIdOrName}/rows/{rowIdOrName}/buttons/{columnIdOrName}
There are no rows in this table

Sections have become Pages

In May, inside the application
from Folders and Sections to Pages and Subpages. Version 1 of the API reflects this change.

The endpoints for folders and sections have been removed and consolidated into a new set of endpoints for pages. For the most part, functionality is the same, and you simply need to change the noun in the endpoint from
section
to
page
.

For example, to list the pages in a document, you now use the endpoint
https://coda.io/apis/v1/docs/<docId>/pages
instead of
https://coda.io/apis/v1beta1/docs/<docId>/sections
.

Previously, to find the sections within a given folder, you would make a request to a
folders
endpoint. Now, folders have been eliminated, and each Page object can have zero or more child pages nested underneath it. To traverse the hierarchy of pages, simply examine a Page object. The
children
property will be a list of references to child pages, if any, and the
parent
property will be a reference to the parent page, if any.

Specifically, if you use any of the following endpoints, you should migrate to the given new endpoint.
Old Endpoint
New Endpoint
1
/docs/{docId}/
sections
/docs/{docId}/
pages
2
/docs/{docId}/
sections
/{sectionIdOrName}
/docs/{docId}/
pages
/{pageIdOrName}
3
/docs/{docId}/
sections
/{sectionIdOrName}
/docs/{docId}/
pages
/{pageIdOrName}
There are no rows in this table

Pagination

We have solidified our usage of opaque tokens for pagination. This should not be a breaking change unless your usage was relying on undocumented aspects of the old API.

When using a list endpoint, such as
https://coda.io/apis/v1/docs
, if there are more results than can be returned on one page, the response will include a
nextPageToken
(if no
nextPageToken
is present, there are no further results). This value should be included in the
pageToken
of a subsequent request to the endpoint to get the next page of results. This is the only way to get a subsequent results page.

This behavior is consistent with the previous version of the API. However, savvy users may have observed that the
pageToken
was technically an offset and may have attempted to directly access a specific slice of the result set by supplying a custom offset. Now, the
pageToken
is an opaque string which can only be obtained from a results page response.

Previously, you could combine the
pageToken
with the
limit
parameter or other filter url parameters. Now, the
pageToken
encodes all the parameters you supplied with your original request. You need not supply any parameter other than the
pageToken
when getting subsequent pages, and indeed any additional parameters will be ignored.

The maximum size of a single result page is subject to change at any time, and may be different for different endpoints. You can pass your desired page size as the
limit
param but if it is larger than the current max page size, the limit will be ignored and the max page size will be used instead. The max page size is currently 100 for many endpoints, but as above, is subject to change and shouldn’t be relied upon. To get a specific number of results, keep fetching pages of results until you reach the desired number of results or until the absence of a
nextPageToken
indicates that there are no more results.

New Endpoint

Asynchronous updates can now be checked for completion

This is not a breaking change but a new addition to help you know when mutations you make to documents via the API have been applied.

Many of our endpoints that make changes to document content, like updating a row, return a
202 Accepted
status, indicating that the update has been queued for processing, and is applied a short time later. Now, each of those responses return a request id in the response, which you can pass to the new mutation status endpoint:
https://coda.io/apis/v1/mutationStatus/<requestId>
, which will return whether or not the update has been applied.

Want to print your doc?
This is not the way.
Try clicking the ⋯ next to your doc name or using a keyboard shortcut (
CtrlP
) instead.