A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Coda API is how an app or AI agent works with a Coda doc: listing tables and reading rows, inserting and updating rows, creating and editing pages, and triggering an automation. Access is granted through a personal API token that inherits its owner's reach, and the token can be restricted at creation to specific docs and to a read or write level, which bounds what each call can touch. Writes are processed asynchronously, so a change is accepted and applied to the doc a moment later rather than on the spot.
How an app or AI agent connects to Coda determines what it can reach. There is a route for making calls, a hosted server that exposes Coda tools to agents, and webhook-triggered automations for receiving events, and each is governed by the token behind it and the access that token carries.
The REST API answers at https://coda.io/apis/v1. A token is sent as 'Authorization: Bearer
Coda runs a hosted Model Context Protocol server at https://coda.io/apis/mcp that gives an AI client tools to read and write docs in plain language. It is in beta, so its tools and behavior can change, and a personal token can be scoped to read, write, or read and write on specific docs.
An automation rule inside a doc can be set to run when a webhook is received. An external system, holding a token with write access, posts to the rule's trigger endpoint to start the steps it defines.
A Coda API token is created in account settings and sent as a Bearer token. It inherits the access its owner has, so it can reach every doc that person can, unless it is restricted at creation.
When creating a token, its reach can be narrowed to specific docs or tables, and its level set to read, write, or read and write. This is the least-privilege choice, since the token can then touch only what it was scoped to.
The Coda API is split into areas an agent can act on, like docs, pages, tables, columns, rows, and sharing. Each area has its own methods, and writes to rows, pages, or sharing change real document data.
List the docs a token can reach, read a doc's info, create a doc, update its title or icon, and delete it.
List and read the pages in a doc, create a page, update a page's content in HTML or markdown, delete a page, and export page content.
List and read the tables and views in a doc, and list and read the columns that make up a table.
List and read rows in a table, insert or upsert rows, update a single row, delete rows, and press a button in a row.
List and read the named formulas and the controls, like sliders and toggles, defined in a doc.
Read a doc's sharing metadata and permissions, add or remove a permission, search who a doc can be shared with, and read or change the sharing settings.
Trigger a webhook-invoked automation rule inside a doc.
Read the current user's account info, resolve a browser link to API objects, and check the status of a queued write.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
DocsList the docs a token can reach, read a doc's info, create a doc, update its title or icon, and delete it.5 | ||||||
| GET | /docs | List the docs the token can access, with optional filters. | read | Token: read | Current | |
Listing docs has its own, lower rate limit than other reads. A token reaches only the docs its owner can access, and can be restricted further to specific docs at creation. Acts ondoc Permission (capability) Token: readVersionAvailable since the API’s base version Webhook eventNone Rate limit4 requests per 6 seconds SourceOfficial documentation ↗ | ||||||
| GET | /docs/{docId} | Get metadata about a single doc. | read | Token: read | Current | |
Returns the doc's name, owner, workspace, and folder. Acts ondoc Permission (capability) Token: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /docs | Create a new doc, optionally from a source doc or template. | write | Token: write | Current | |
Needs a token with write access. A token restricted to read only, or scoped to specific docs, cannot create new docs. Acts ondoc Permission (capability) Token: writeVersionAvailable since the API’s base version Webhook eventNone Rate limit10 requests per 6 seconds SourceOfficial documentation ↗ | ||||||
| PATCH | /docs/{docId} | Update a doc's title or icon. | write | Token: write | Current | |
Needs a token with write access. Acts ondoc Permission (capability) Token: writeVersionAvailable since the API’s base version Webhook eventNone Rate limit10 requests per 6 seconds SourceOfficial documentation ↗ | ||||||
| DELETE | /docs/{docId} | Delete a doc. | write | Token: write | Current | |
Permanently removes the doc. Needs a token with write access. Acts ondoc Permission (capability) Token: writeVersionAvailable since the API’s base version Webhook eventNone Rate limit10 requests per 6 seconds SourceOfficial documentation ↗ | ||||||
PagesList and read the pages in a doc, create a page, update a page's content in HTML or markdown, delete a page, and export page content.6 | ||||||
| GET | /docs/{docId}/pages | List the pages in a doc. | read | Token: read | Current | |
Returns page names and identifiers, not their content. Acts onpage Permission (capability) Token: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /docs/{docId}/pages/{pageIdOrName} | Get details about a single page. | read | Token: read | Current | |
A page can be addressed by its id or by its name. Acts onpage Permission (capability) Token: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /docs/{docId}/pages | Create a page in a doc, with content in HTML or markdown. | write | Token: write | Current | |
Writing page content counts against the lower content-write limit, not the general write limit. Acts onpage Permission (capability) Token: writeVersionIntroduced 2023-11-02 Webhook eventNone Rate limit5 requests per 10 seconds SourceOfficial documentation ↗ | ||||||
| PUT | /docs/{docId}/pages/{pageIdOrName} | Update a page, replacing or appending its content in HTML or markdown. | write | Token: write | Current | |
The insertionMode field chooses whether new content replaces or appends to the page. Counts against the content-write limit. Acts onpage Permission (capability) Token: writeVersionIntroduced 2023-11-02 Webhook eventNone Rate limit5 requests per 10 seconds SourceOfficial documentation ↗ | ||||||
| DELETE | /docs/{docId}/pages/{pageIdOrName} | Delete a page from a doc. | write | Token: write | Current | |
Needs a token with write access. Acts onpage Permission (capability) Token: writeVersionAvailable since the API’s base version Webhook eventNone Rate limit5 requests per 10 seconds SourceOfficial documentation ↗ | ||||||
| POST | /docs/{docId}/pages/{pageIdOrName}/export | Begin exporting a page's content in HTML or markdown. | read | Token: read | Current | |
Export is asynchronous: this starts a job, and a follow-up request fetches the finished content. Acts onpage Permission (capability) Token: readVersionIntroduced 2023-11-02 Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Tables & columnsList and read the tables and views in a doc, and list and read the columns that make up a table.4 | ||||||
| GET | /docs/{docId}/tables | List the tables and views in a doc. | read | Token: read | Current | |
A tableTypes filter can return base tables, views, or both. Acts ontable Permission (capability) Token: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /docs/{docId}/tables/{tableIdOrName} | Get details about a single table or view. | read | Token: read | Current | |
A table can be addressed by its id or by its name. Acts ontable Permission (capability) Token: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /docs/{docId}/tables/{tableIdOrName}/columns | List the columns in a table. | read | Token: read | Current | |
Returns each column's name, type, and formula where it has one. Acts oncolumn Permission (capability) Token: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /docs/{docId}/tables/{tableIdOrName}/columns/{columnIdOrName} | Get details about a single column. | read | Token: read | Current | |
A column can be addressed by its id or by its name. Acts oncolumn Permission (capability) Token: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
RowsList and read rows in a table, insert or upsert rows, update a single row, delete rows, and press a button in a row.7 | ||||||
| GET | /docs/{docId}/tables/{tableIdOrName}/rows | List the rows in a table, with optional query and sorting. | read | Token: read | Current | |
A query parameter filters rows by a column's value, and useColumnNames returns readable column names instead of ids. Acts onrow Permission (capability) Token: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /docs/{docId}/tables/{tableIdOrName}/rows/{rowIdOrName} | Get a single row. | read | Token: read | Current | |
A row can be addressed by its id or by the value in its display column. Acts onrow Permission (capability) Token: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /docs/{docId}/tables/{tableIdOrName}/rows | Insert rows, or update existing rows when key columns are given. | write | Token: write | Current | |
Passing keyColumns turns an insert into an upsert, updating any row whose key matches. Inserts must target a base table, not a view. Acts onrow Permission (capability) Token: writeVersionAvailable since the API’s base version Webhook eventNone Rate limit10 requests per 6 seconds SourceOfficial documentation ↗ | ||||||
| PUT | /docs/{docId}/tables/{tableIdOrName}/rows/{rowIdOrName} | Update the cells of a single row. | write | Token: write | Current | |
Needs a token with write access. The write is queued and applied a moment later. Acts onrow Permission (capability) Token: writeVersionAvailable since the API’s base version Webhook eventNone Rate limit10 requests per 6 seconds SourceOfficial documentation ↗ | ||||||
| DELETE | /docs/{docId}/tables/{tableIdOrName}/rows | Delete several rows at once by their ids. | write | Token: write | Current | |
Takes a list of row ids in the body. Needs a token with write access. Acts onrow Permission (capability) Token: writeVersionAvailable since the API’s base version Webhook eventNone Rate limit10 requests per 6 seconds SourceOfficial documentation ↗ | ||||||
| DELETE | /docs/{docId}/tables/{tableIdOrName}/rows/{rowIdOrName} | Delete a single row. | write | Token: write | Current | |
Needs a token with write access. Acts onrow Permission (capability) Token: writeVersionAvailable since the API’s base version Webhook eventNone Rate limit10 requests per 6 seconds SourceOfficial documentation ↗ | ||||||
| POST | /docs/{docId}/tables/{tableIdOrName}/rows/{rowIdOrName}/buttons/{columnIdOrName} | Press a button in a row to run its configured action. | write | Token: write | Current | |
Runs whatever action the button defines, which may itself change other data. Acts onbutton Permission (capability) Token: writeVersionAvailable since the API’s base version Webhook eventNone Rate limit10 requests per 6 seconds SourceOfficial documentation ↗ | ||||||
Formulas & controlsList and read the named formulas and the controls, like sliders and toggles, defined in a doc.4 | ||||||
| GET | /docs/{docId}/formulas | List the named formulas in a doc. | read | Token: read | Current | |
Named formulas are reusable values defined in the doc. Acts onformula Permission (capability) Token: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /docs/{docId}/formulas/{formulaIdOrName} | Get a single named formula and its current value. | read | Token: read | Current | |
Returns the formula's computed value at the time of the call. Acts onformula Permission (capability) Token: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /docs/{docId}/controls | List the controls in a doc, like buttons, sliders, and toggles. | read | Token: read | Current | |
Controls are the interactive inputs placed on a doc's pages. Acts oncontrol Permission (capability) Token: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /docs/{docId}/controls/{controlIdOrName} | Get a single control and its current value. | read | Token: read | Current | |
Returns the control's current setting. Acts oncontrol Permission (capability) Token: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Sharing & permissionsRead a doc's sharing metadata and permissions, add or remove a permission, search who a doc can be shared with, and read or change the sharing settings.7 | ||||||
| GET | /docs/{docId}/acl/metadata | Get sharing metadata for a doc. | read | Token: read | Current | |
Reports whether sharing can be changed and who owns the doc. Acts onsharing metadata Permission (capability) Token: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /docs/{docId}/acl/permissions | List the people and groups a doc is shared with. | read | Token: read | Current | |
Each entry pairs who it's for, a person or group, with their access level. Acts onpermission Permission (capability) Token: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /docs/{docId}/acl/permissions | Share a doc with a person or group at a chosen access level. | write | Token: write | Current | |
Grants someone access to the doc, which widens who can reach its data. Needs a token with write access. Acts onpermission Permission (capability) Token: writeVersionAvailable since the API’s base version Webhook eventNone Rate limit10 requests per 6 seconds SourceOfficial documentation ↗ | ||||||
| DELETE | /docs/{docId}/acl/permissions/{permissionId} | Remove a person or group's access to a doc. | write | Token: write | Current | |
Revokes a single share. Needs a token with write access. Acts onpermission Permission (capability) Token: writeVersionAvailable since the API’s base version Webhook eventNone Rate limit10 requests per 6 seconds SourceOfficial documentation ↗ | ||||||
| GET | /docs/{docId}/acl/principals/search | Search for people and groups a doc can be shared with. | read | Token: read | Current | |
Matches by name or email to find who a doc can be shared with. Acts onprincipal Permission (capability) Token: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /docs/{docId}/acl/settings | Read a doc's sharing settings. | read | Token: read | Current | |
Covers settings like whether copying or link sharing is allowed. Acts onsharing settings Permission (capability) Token: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /docs/{docId}/acl/settings | Change a doc's sharing settings. | write | Token: write | Current | |
Changes settings like link sharing and copying for the whole doc. Needs a token with write access. Acts onsharing settings Permission (capability) Token: writeVersionAvailable since the API’s base version Webhook eventNone Rate limit10 requests per 6 seconds SourceOfficial documentation ↗ | ||||||
AutomationsTrigger a webhook-invoked automation rule inside a doc.1 | ||||||
| POST | /docs/{docId}/automations/{ruleId}/trigger | Trigger a webhook-invoked automation rule in a doc. | write | Token: write | Current | |
The automation rule must be set to run when a webhook is received, and the request runs whatever steps that rule defines. Needs a token with write access to the doc. Acts onautomation Permission (capability) Token: writeVersionAvailable since the API’s base version Webhook eventNone Rate limit10 requests per 6 seconds SourceOfficial documentation ↗ | ||||||
Account & utilitiesRead the current user's account info, resolve a browser link to API objects, and check the status of a queued write.3 | ||||||
| GET | /whoami | Get information about the user the token belongs to. | read | Token: read | Current | |
Returns the account's name, email, workspace, and whether the token can act across the workspace. Acts onuser Permission (capability) Token: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /resolveBrowserLink | Resolve a Coda browser link to the API objects it points at. | read | Token: read | Current | |
Turns a shared doc, page, or row URL into the ids needed to call other methods. Acts onlink Permission (capability) Token: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /mutationStatus/{requestId} | Check whether a queued write has finished processing. | read | Token: read | Current | |
Writes return a requestId, and this method reports when that change has been applied to the doc. Acts onmutation status Permission (capability) Token: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Coda does not push general account events. Instead, an automation inside a doc can be set to run when a webhook is received, and the API can trigger that automation directly, so an external system can start work in a doc.
| Event | What it signals | Triggered by |
|---|
Coda limits how fast an app or AI agent can call, with separate per-user ceilings for reading data, writing data, writing document content, and listing docs, all counted across every doc the token can reach.
Coda sets separate per-user ceilings by the kind of call, counted across every doc a token can reach. Reading data is allowed at 100 requests per 6 seconds, writing data through POST, PUT, or PATCH at 10 requests per 6 seconds, writing document content such as pages at the lower rate of 5 requests per 10 seconds, and listing docs at 4 requests per 6 seconds, while reading analytics matches the general read limit. Exceeding any of these returns 429 Too Many Requests, and the documentation advises every script to detect 429, back off, and retry. The limits are subject to change without notice.
List methods return an items array along with a limit query parameter that sets the page size and a pageToken for fetching the next page. A response that has more results includes nextPageToken and a ready-made nextPageLink. The maximum page size can differ by method and change over time, so a caller should follow nextPageToken until it is absent rather than counting returned items against the requested limit.
Requests and responses are JSON. Writes are processed asynchronously: a write returns 202 Accepted with a requestId, and the change is applied to the doc a moment later, which the mutation status method confirms. Sending the header X-Coda-Doc-Version with the value latest forces a read to reflect the most recent edits, or return 400 if that version is not yet available.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | Bad Request | The request parameters did not match what the method expects, such as a malformed body or an unparseable cell value. The body carries statusCode, statusMessage, and message fields describing the problem. | Read the message, correct the named parameter, and resend. |
| 401 | Unauthorized | The API token is missing, invalid, or expired. | Check the token and the Authorization header, then send a valid Bearer token. |
| 403 | Forbidden | The token is valid but does not have access to the resource, for example a write with a read-only token, or a doc the token was not scoped to. | Use a token with the needed access, or widen the token's scope, then retry. |
| 404 | Not Found | The doc, table, row, or other object does not exist, or the token cannot see it. | Confirm the identifier is correct and the token has access to the object. |
| 429 | Too Many Requests | A rate limit was exceeded. Limits are counted per user across every doc the token can reach, and apply separately to reads, writes, content writes, and listing docs. | Back off and retry, honoring any retry-after hint, and slow the rate of calls. |
Coda runs a single v1 API with no dated versions to pin. New methods are added in place, like the expanded page endpoints that let an agent read and write page content.
The Coda API is a single v1 with no dated versions to pin. New methods are added in place, so an integration follows one current API rather than migrating between versions. The reference reports its internal spec version as 1.5.0.
Page content became readable and writable through the API. New methods let an integration create a page, update a page by replacing or appending its content in HTML or markdown, and export a page's content, where before only basic page metadata was available. It was announced on Thursday 2 November 2023.
There is one current API, so an integration does not pin or migrate a version.
Coda API reference ↗Bollard AI sits between a team's AI agents and Coda. Grant each agent exactly the access it needs, read or write, doc by doc, and every call is checked and logged.