Coda API Skill
Interact with Coda.io via its REST API v1. Base URL: https://coda.io/apis/v1
Setup
- Get API token at https://coda.io/account → "API settings" → "Generate API token"
- Set env var:
export CODA_API_TOKEN="<token>"
- Verify:
bash scripts/coda.sh whoami
Helper Script
scripts/coda.sh wraps common operations. Run bash scripts/coda.sh help for usage.
Examples:
# List docs
bash scripts/coda.sh list-docs | jq '.items[].name'
# List tables in a doc
bash scripts/coda.sh list-tables AbCDeFGH | jq '.items[] | {id, name}'
# List columns (discover IDs before writing)
bash scripts/coda.sh list-columns AbCDeFGH grid-abc | jq '.items[] | {id, name}'
# Read rows with column names
bash scripts/coda.sh list-rows AbCDeFGH grid-abc 10 true | jq '.items'
# Insert rows
echo '{"rows":[{"cells":[{"column":"c-abc","value":"Hello"}]}]}' | \
bash scripts/coda.sh insert-rows AbCDeFGH grid-abc
# Upsert rows (match on key column)
echo '{"rows":[{"cells":[{"column":"c-abc","value":"Hello"},{"column":"c-def","value":42}]}],"keyColumns":["c-abc"]}' | \
bash scripts/coda.sh upsert-rows AbCDeFGH grid-abc
# Share doc
bash scripts/coda.sh share-doc AbCDeFGH user@example.com write
Workflow: Reading Data
list-docs → find the doc IDlist-tables <docId> → find the table IDlist-columns <docId> <tableId> → discover column IDs/nameslist-rows <docId> <tableId> → read data
Workflow: Writing Data
- Discover column IDs first (step 3 above)
- Build row JSON with
cells array using column IDs
insert-rows (new data) or upsert-rows (with keyColumns for idempotent writes)- Write ops return HTTP 202 +
requestId → poll with mutation-status if confirmation needed
Key Concepts
- IDs over names: Use resource IDs (stable) rather than names (user-editable)
- Eventual consistency: Writes are async (HTTP 202). Poll
mutation-status to confirm.
- Pagination: List endpoints return
nextPageToken. Pass as pageToken for next page.
- Rate limits: Read 100/6s, Write 10/6s, Doc content write 5/10s. Respect 429 with backoff.
- Fresh reads: Add header
X-Coda-Doc-Version: latest to ensure non-stale data (may 400).
- valueFormat:
simple (default), simpleWithArrays, rich for structured data.
- Doc ID from URL:
https://coda.io/d/Title_d<DOC_ID> → the part after _d is the doc ID.
Direct curl (when script doesn't cover it)
curl -s -H "Authorization: Bearer $CODA_API_TOKEN" \
"https://coda.io/apis/v1/docs/{docId}/tables/{tableId}/rows?useColumnNames=true&limit=50"
For writes:
curl -s -H "Authorization: Bearer $CODA_API_TOKEN" \
-H "Content-Type: application/json" \
-X POST -d '{"rows":[...]}' \
"https://coda.io/apis/v1/docs/{docId}/tables/{tableId}/rows"
Full API Reference
See references/api-endpoints.md for complete endpoint listing with parameters, body schemas, and response details.
Searchable by section: Account, Folders, Docs, Pages, Tables, Columns, Rows, Formulas, Controls, Permissions, Publishing, Automations, Analytics, Miscellaneous.
1---2name: coda-23description: Interact with Coda.io docs, tables, rows, pages, and automations via the Coda REST API v1. Use when the user wants to read, write, update, or delete data in Coda docs. Also use when they mention "Coda", "Coda doc", "Coda table", "Coda rows", "Coda API", "sync to Coda", "read from Coda", "write to Coda", "Coda automation", "Coda pages", "Coda formulas", "share Coda doc", or "Coda permissions". Covers docs, pages, tables, columns, rows, formulas, controls, folders, permissions, publishing, automations, and analytics.4---5
6# Coda API Skill
7
8Interact with Coda.io via its REST API v1. Base URL: `https://coda.io/apis/v1`
9
10## Setup
11
121. Get API token at https://coda.io/account → "API settings" → "Generate API token"
132. Set env var: `export CODA_API_TOKEN="<token>"`
143. Verify: `bash scripts/coda.sh whoami`
15
16## Helper Script
17
18`scripts/coda.sh` wraps common operations. Run `bash scripts/coda.sh help` for usage.
19
20Examples:
21```bash
22# List docs
23bash scripts/coda.sh list-docs | jq '.items[].name'
24
25# List tables in a doc
26bash scripts/coda.sh list-tables AbCDeFGH | jq '.items[] | {id, name}'
27
28# List columns (discover IDs before writing)
29bash scripts/coda.sh list-columns AbCDeFGH grid-abc | jq '.items[] | {id, name}'
30
31# Read rows with column names
32bash scripts/coda.sh list-rows AbCDeFGH grid-abc 10 true | jq '.items'
33
34# Insert rows
35echo '{"rows":[{"cells":[{"column":"c-abc","value":"Hello"}]}]}' | \
36 bash scripts/coda.sh insert-rows AbCDeFGH grid-abc
37
38# Upsert rows (match on key column)
39echo '{"rows":[{"cells":[{"column":"c-abc","value":"Hello"},{"column":"c-def","value":42}]}],"keyColumns":["c-abc"]}' | \
40 bash scripts/coda.sh upsert-rows AbCDeFGH grid-abc
41
42# Share doc
43bash scripts/coda.sh share-doc AbCDeFGH user@example.com write
44```
45
46## Workflow: Reading Data
47
481. `list-docs` → find the doc ID
492. `list-tables <docId>` → find the table ID
503. `list-columns <docId> <tableId>` → discover column IDs/names
514. `list-rows <docId> <tableId>` → read data
52
53## Workflow: Writing Data
54
551. Discover column IDs first (step 3 above)
562. Build row JSON with `cells` array using column IDs
573. `insert-rows` (new data) or `upsert-rows` (with `keyColumns` for idempotent writes)
584. Write ops return HTTP 202 + `requestId` → poll with `mutation-status` if confirmation needed
59
60## Key Concepts
61
62- **IDs over names**: Use resource IDs (stable) rather than names (user-editable)
63- **Eventual consistency**: Writes are async (HTTP 202). Poll `mutation-status` to confirm.
64- **Pagination**: List endpoints return `nextPageToken`. Pass as `pageToken` for next page.
65- **Rate limits**: Read 100/6s, Write 10/6s, Doc content write 5/10s. Respect 429 with backoff.
66- **Fresh reads**: Add header `X-Coda-Doc-Version: latest` to ensure non-stale data (may 400).
67- **valueFormat**: `simple` (default), `simpleWithArrays`, `rich` for structured data.
68- **Doc ID from URL**: `https://coda.io/d/Title_d<DOC_ID>` → the part after `_d` is the doc ID.
69
70## Direct curl (when script doesn't cover it)
71
72```bash
73curl -s -H "Authorization: Bearer $CODA_API_TOKEN" \
74 "https://coda.io/apis/v1/docs/{docId}/tables/{tableId}/rows?useColumnNames=true&limit=50"
75```
76
77For writes:
78```bash
79curl -s -H "Authorization: Bearer $CODA_API_TOKEN" \
80 -H "Content-Type: application/json" \
81 -X POST -d '{"rows":[...]}' \
82 "https://coda.io/apis/v1/docs/{docId}/tables/{tableId}/rows"
83```
84
85## Full API Reference
86
87See [references/api-endpoints.md](references/api-endpoints.md) for complete endpoint listing with parameters, body schemas, and response details.
88
89Searchable by section: Account, Folders, Docs, Pages, Tables, Columns, Rows, Formulas, Controls, Permissions, Publishing, Automations, Analytics, Miscellaneous.
dvcrn