Coda API
Documentation Powered by ReDoc

Coda API (1.0.0)

API Support: help+api@coda.io URL: https://coda.io Terms of Service

Introduction

The Coda API is a RESTful API that lets you programmatically interact with Coda docs:

  • List and search Coda docs
  • Create new docs and copy existing ones
  • Share and publish docs
  • Discover pages, tables, formulas, and controls
  • Read, insert, upsert, update, and delete rows

Version 1 of the API will be supported until at least January 15, 2021. As we update and release newer versions of the API, we reserve the right to remove older APIs and functionality with a 3-month deprecation notice. We will post about such changes as well as announce new features in the Developers Central section of our Community, and update the API updates doc.

Getting Started

Our Getting Started Guide helps you learn the basic of working with the API and shows a few ways you can use it. Check it out, and learn how to:

  • Read data from Coda tables and write back to them
  • Build a one-way sync from one Coda doc to another
  • Automate reminders
  • Sync your Google Calendar to Coda

Using the API

Coda's REST API is designed to be straightforward to use. You can use the language and platform of your choice to make requests. To get a feel for the API, you can also use a tool like Postman or Insomnia.

API Endpoint

This API uses a base path of https://coda.io/apis/v1.

Rate Limiting

The Coda API sets a reasonable limit on the number of requests that can be made per minute. Once this limit is reached, calls to the API will start returning errors with an HTTP status code of 429. If you find yourself hitting rate limits and would like your individual rate to be raised, please contact us at help+api@coda.io.

Consistency

While edits made in Coda are shared with other collaborators in real-time, it can take a few seconds for them to become available via the API. You may also notice that changes made via the API, such as updating a row, are not immediate. These endpoints all return an HTTP 202 status code, instead of a standard 200, indicating that the edit has been accepted and queued for processing. This generally takes a few seconds, and the edit may fail if invalid. Each such edit will return a requestId in the response, and you can pass this requestId to the #getMutationStatus endpoint to find out if it has been applied.

Volatile Formulas

Coda exposes a number of "volatile" formulas, as as Today(), Now(), and User(). When used in a live Coda doc, these formulas affect what's visible in realtime, tailored to the current user.

Such formulas behave differently with the API. Time-based values may only be current to the last edit made to the doc. User-based values may be blank or invalid.

Free and Paid Workspaces

We make the Coda API available to all of our users free of charge, in both free and paid workspaces. However, API usage is subject to the role of the user associated with the API token in the workspace applicable to each API request. What this means is:

  • For the #createDoc endpoint specifically, the owner of the API token must be a Doc Maker (or Admin) in the workspace. If the "Any member can create docs" option in enabled in the workspace settings, they can be an Editor and will get auto-promoted to Doc Maker upon using this endpoint. Lastly, if in addition, the API key owner matches the "Approved email domains" setting, they will be auto-added to the workspace and promoted to Doc Maker upon using this endpoint

This behavior applies to the API as well as any integrations that may use it, such as Zapier.

Examples

To help you get started, this documentation provides code examples in Python, Unix shell, and Google Apps Script. These examples are based on a simple doc that looks something like this:

Python examples

These examples use Python 3.6+. If you don't already have the requests module, use pip or easy_install to get it.

Shell examples

The shell examples are intended to be run in a Unix shell. If you're on Windows, you will need to install WSL.

These examples use the standard cURL utility to pull from the API, and then process it with jq to extract and format example output. If you don't already have it, you can either install it or run the command without it to see the raw JSON output.

Google Apps Script examples

Google Apps Script makes it easy to write code in a JavaScript-like syntax and easily access many Google products with built-in libraries. You can set up your scripts to run periodically, which makes it a good environment for writing tools without maintaining your own server.

Coda provides a library for Google Apps Script. To use it, go into Resources -> Libraries... and enter the following library ID: 15IQuWOk8MqT50FDWomh57UqWGH23gjsWVWYFms3ton6L-UHmefYHS9Vl. If you want to see the library's source code, it's available here.

Google provides autocomplete for API functions as well as generated docs. You can access these docs via the Libraries dialog by clicking on the library name. Required parameters that would be included in the URL path are positional arguments in each of these functions, followed by the request body, if applicable. All remaining parameters can be specified in the options object.

OpenAPI/Swagger Spec

In an effort to standardize our API and make it accessible, we offer an OpenAPI 3.0 specification:

Swagger 2.0

We also offer a downgraded Swagger 2.0 version of our specification. This may be useful for a number of tools that haven't yet been adapted to OpenAPI 3.0. Here are the links:

Postman collection

To get started with prototyping the API quickly in Postman, you can use one of links above to import the Coda API into a collection. You'll then need to set the appropriate header and environment variables.

Client libraries

We do not currently support client libraries apart from Google Apps Script. To work with the Coda API, you can either use standard network libraries for your language, or use the appropriate Swagger Generator tool to auto-generate Coda API client libraries for your language of choice. We do not provide any guarantees that these autogenerated libraries are compatible with our API (e.g., some libraries may not work with Bearer authentication).

OpenAPI 3.0

Swagger Generator 3 (that link takes you to the docs for the generator API) can generate client libraries for these languages. It's relatively new and thus only has support for a limited set of languages at this time.

Swagger 2.0

Swagger Generator takes in a legacy Swagger 2.0 specification, but can generate client libraries for more languages. You can also use local CLI tools to generate these libraries.

Third-party client libraries

Some members of our amazing community have written libraries to work with our API. These aren't officially supported by Coda, but are listed here for convenience. (Please let us know if you've written a library and would like to have it included here.)

  • PHP by Daniel Stieber
  • Node-RED by Mori Sugimoto
  • NodeJS by Parker McMullin
  • Ruby by Carlos Muñoz at Getro
  • Python by Mikhail Beliansky

Authentication

Bearer

The Coda API can be accessed using an API token, which can be obtained from My account in Coda. This token should be specified by setting a header as follows.

Authorization: Bearer <api_token>

Keep your token safe, as anyone who gets access to it can access your account. Once a token is created it cannot be viewed or modified, so don't lose it.

If you're logged into Coda, you can also query the API directly using your browser. Note that only GET endpoints are supported; for anything else, you'll have to use Bearer authentication.

Restricting token authorization

By default, bearer tokens created for the Coda API can perform any action that the user who created the token can perform. However, Coda API bearer tokens can also be created with restrictions. These restrictions can limit what objects can be operated on and the types of operations that can be performed.

Operation types

The table below describes the types of authorization restrictions that can be placed on a Coda API token.

RestrictionDescriptionAllowed HTTP Methods
Read access Allows access to API methods that read the state of an object GET
Write access Allows access to API methods that write the state of an object POST, PUT, DELETE
Read and write access Allows access to all methods for an object All

Object types

Coda API tokens can be restricted to the following types of objects.

  • Documents: Restricts access to only allow API calls for /docs/${DOC_ID}
  • Tables: Restricts access to only allow API calls for /docs/${DOC_ID}/tables/${TABLE_ID}

Special cases

There are a few special case methods that violate the above restrictions.

  • /whoami: This method can be called by all Coda API tokens.
  • /resolveBrowserLink: This method can be called by all Coda API tokens, but will only return a result if the token has access (read or write) to the object referenced by the URL.

Feedback

This feature is under development and we'd love to hear your feedback and bug reports. Please visit us at the Developers Central forum within the Coda Community.

Security Scheme Type HTTP
HTTP Authorization Scheme bearer
Bearer format "UUID"

Docs

Coda docs are foundational, top-level collaborative projects that contain pages. The API lets you list and search your docs to obtain basic metadata like titles and ownership information.

List available docs

Returns a list of Coda docs accessible by the user. These are returned in the same order as on the docs page: reverse chronological by the latest event relevant to the user (last viewed, edited, or shared).

Authorizations:
Bearer
query Parameters
isOwner
boolean

Show only docs owned by the user.

query
string

Search term used to filter down results.

sourceDoc
string

Show only docs copied from the specified doc ID.

isStarred
boolean

If true, returns docs that are starred. If false, returns docs that are not starred.

inGallery
boolean

Show only docs visible within the gallery.

workspaceId
string

Show only docs belonging to the given workspace.

folderId
string

Show only docs belonging to the given folder.

limit
integer
Example: limit=10

Maximum number of results to return in this query.

pageToken
string
Example: pageToken=20

An opaque token used to fetch the next page of results.

Responses

200

List of Coda docs matching the query.

401

The API token is invalid or has expired.

404

The resource could not be located with the current API token.

429

The client has sent too many requests.

get/docs

Coda API (v1)

/https://coda.io/apis/v1/docs

Request samples

Copy
import requests

headers = {'Authorization': 'Bearer <your API token>'}
uri = 'https://coda.io/apis/v1/docs'
params = {
  'isOwner': True,
  'query': 'New',
}
res = requests.get(uri, headers=headers, params=params).json()

print(f'First doc is: {res["items"][0]["name"]}')
# => First doc is: New Document

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "items":
    [
    ],
  • "href": "https://coda.io/apis/v1/docs?limit=20",
  • "nextPageToken": "20",
  • "nextPageLink": "https://coda.io/apis/v1/docs?limit=20&pageToken=20"
}

Create doc

Creates a new Coda doc, optionally copying an existing doc. Note that creating a doc requires you to be a Doc Maker in the applicable workspace (or be auto-promoted to one).

Authorizations:
Bearer
Request Body schema: application/json

Parameters for creating the doc.

title
string

Title of the new doc. Defaults to 'Untitled'.

sourceDoc
string

An optional doc ID from which to create a copy.

timezone
string

The timezone to use for the newly created doc.

folderId
string

The ID of the folder within which to create this doc. Defaults to your "My Docs" folder in the oldest workspace you joined; this is subject to change. You can get this ID by opening the folder in the docs list on your computer and grabbing the folderId query parameter.

Responses

201

Info about the created doc.

400

The request parameters did not conform to expectations.

401

The API token is invalid or has expired.

403

The API token does not grant access to this resource.

429

The client has sent too many requests.

post/docs

Coda API (v1)

/https://coda.io/apis/v1/docs

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "title": "Project Tracker",
  • "sourceDoc": "iJKlm_noPq",
  • "timezone": "America/Los_Angeles",
  • "folderId": "fl-ABcdEFgHJi"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "AbCDeFGH",
  • "type": "doc",
  • "href": "https://coda.io/apis/v1/docs/AbCDeFGH",
  • "browserLink": "https://coda.io/d/_dAbCDeFGH",
  • "icon":
    {},
  • "name": "Product Launch Hub",
  • "owner": "user@example.com",
  • "ownerName": "Some User",
  • "docSize":
    {
    },
  • "sourceDoc":
    {
    },
  • "createdAt": "2018-04-11T00:18:57.946Z",
  • "updatedAt": "2018-04-11T00:18:57.946Z",
  • "published":
    {
    }
}

Get info about a doc

Returns metadata for the specified doc.

Authorizations:
Bearer