You can do many things with the Coda API, but for a long time there was one part of a Coda doc that was almost completely inaccessible: pages. While it did provide some basic metadata about the pages in a doc, the content of those pages was off limits.
Why? Because pages are complicated! Trying to come up with a stable API representation for a rich and quickly evolving document model is not an easy task.
However we heard from our developer community pretty consistently over the years that you want some way to work with page content, and over the last few months we’ve rolled out some changes that we think you’ll like. Specifically:
- Page content can now be read or written in either HTML or markdown format.
- When updating a page, you can replace the page content or append to it.
- We’ve added new endpoints for creating pages and for exporting pages.
Creating a page
To create a page, send a POST request to the endpoint https://coda.io/apis/v1/docs/{docId}/pages. You can optionally include metadata like the page name, subtitle, icon, cover image, and parent page.
You can also set the initial content of the page at the same time, specified as HTML or Markdown, or a URL to use as the source of an Embed page. (Note that a page cannot be toggled between a regular canvas page and an Embed page after the fact, this can only be set at creation time.)
Here’s an example request body which creates a new page, specifying all available attributes, including HTML content:
{
"name": "Launch Status",
"subtitle": "See the status of launch-related tasks.",
"iconName": "rocket",
"imageUrl": "https://example.com/image.jpg",
"parentPageId": "canvas-tuVwxYz",
"pageContent": {
"type": "canvas",
"canvasContent": {
"format": "html",
"content": "<p><b>This</b> is rich text</p>"
}
}
}
Updating a page
To update a page, send a PUT request to https://coda.io/apis/v1/docs/{docId}/pages/{pageIdOrName}. You can modify much of the metadata of the page, and any fields you omit will remain unchanged.
For regular canvas pages you can also update the content of the page, either replacing the existing page content or appending to it. Insertion of content at arbitrary points in the page is not currently supported.
Here is a sample request body which updates the page name and appends new content to the end of the page using Markdown:
{
"name": "New Page Name",
"contentUpdate": {
"insertionMode": "append",
"canvasContent": {
"format": "markdown",
"content": "# New Section\n\nThis is a new section of the page."
}
}
}
Exporting a page
To read the content of a page you need to export it to HTML or markdown. Because pages can get very large, exporting content must be queued up and processed asynchronously. Exporting the page content involves the following steps:
- Send a POST request to https://coda.io/apis/v1/docs/{docId}/pages/{pageIdOrName}/export to begin a new export, making sure to specify the desired output format (”html” or ”markdown”).
The response will contain the id of the export and an href where you can fetch information about it. - Make a GET request to the href URL to check the status of the export. Continue to poll this endpoint until the status is “complete”.
A completed export will include a downloadLink field which is the URL of a temporary file that contains the exported content. - Make a request to the URL specified in the downloadLink to retrieve the exported page content.
Be aware
- HTML and markdown can’t perfectly represent all of the features of a Coda doc, so a round trip in either format may lose some information. These endpoints are best used for import or export scenarios, not page editing.
- While the exported file remains live for a few days, the downloadLink returned by the API expires after only a few minutes. To get a fresh URL to your export simply make another request to retrieve the export status.
- If you begin a new export and then immediately check it’s status you might get a 404 Not Found error response. This is because our backend hasn’t caught up just yet. Simply wait a second and retry.
We hope these new endpoints simplify your workflows and open up new use cases!
