Skip to content
Coda API Migration Guide
Coda API Migration Guide
Google Apps Script Migration
More
Share
Explore

icon picker
Coda API Migration Guide

We recently
announced
⁠
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
Google Apps Script Migration
⁠
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
we changed the organizational structure within docs
⁠
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.

Breaking Changes
Endpoints for views have been removed and merged with endpoints for tables
Sections have become Pages
Pagination
New Endpoint
Asynchronous updates can now be checked for completion
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.