coda

通过 Coda REST API v1 与 Coda.io 文档、表格、行、页面和自动化交互。 当用户想要读取、写入、更新或删除 Coda 文档中的数据时使用。也使用时 他们提到“Coda”、“Coda doc”、“Coda 表”、“Coda 行”、“Coda API”、“同步到 Coda”、 “从 Coda 读取”、“写入 Coda”、“Coda 自动化”、“Coda 页面”、“Coda 公式”、 “共享 Coda 文档”或“Coda 权限”。涵盖文档、页面、表格、列、行、 公式、控件、文件夹、权限、发布、自动化和分析。

# Coda API Skill

Interact with Coda.io via its REST API v1. Base URL: `https://coda.io/apis/v1`

## Setup

1. Get API token at https://coda.io/account → "API settings" → "Generate API token"
2. Set env var: `export CODA_API_TOKEN="<token>"`
3. Verify: `bash scripts/coda.sh whoami`

## Helper Script

`scripts/coda.sh` wraps common operations. Run `bash scripts/coda.sh help` for usage.

Examples:
```bash
# 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

1. `list-docs` → find the doc ID
2. `list-tables <docId>` → find the table ID
3. `list-columns <docId> <tableId>` → discover column IDs/names
4. `list-rows <docId> <tableId>` → read data

## Workflow: Writing Data

1. Discover column IDs first (step 3 above)
2. Build row JSON with `cells` array using column IDs
3. `insert-rows` (new data) or `upsert-rows` (with `keyColumns` for idempotent writes)
4. 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)

```bash
curl -s -H "Authorization: Bearer $CODA_API_TOKEN" \
  "https://coda.io/apis/v1/docs/{docId}/tables/{tableId}/rows?useColumnNames=true&limit=50"
```

For writes:
```bash
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](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.

---

## 中文说明

# Coda API 技能

通过 Coda 的 REST API v1 与 Coda.io 交互。基础 URL：`https://coda.io/apis/v1`

## 设置

1. 在 https://coda.io/account → "API settings" → "Generate API token" 获取 API 令牌
2. 设置环境变量：`export CODA_API_TOKEN="<token>"`
3. 验证：`bash scripts/coda.sh whoami`

## 辅助脚本

`scripts/coda.sh` 封装了常见操作。运行 `bash scripts/coda.sh help` 查看用法。

示例：
```bash
# 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
```

## 工作流：读取数据

1. `list-docs` → 找到文档 ID
2. `list-tables <docId>` → 找到表格 ID
3. `list-columns <docId> <tableId>` → 发现列 ID/名称
4. `list-rows <docId> <tableId>` → 读取数据

## 工作流：写入数据

1. 首先发现列 ID（上面的第 3 步）
2. 使用列 ID 构建带 `cells` 数组的行 JSON
3. `insert-rows`（新数据）或 `upsert-rows`（带 `keyColumns` 实现幂等写入）
4. 写操作返回 HTTP 202 + `requestId` → 如需确认，使用 `mutation-status` 轮询

## 关键概念

- **ID 优先于名称**：使用资源 ID（稳定）而非名称（用户可编辑）
- **最终一致性**：写入是异步的（HTTP 202）。使用 `mutation-status` 轮询以确认。
- **分页**：列表端点返回 `nextPageToken`。将其作为 `pageToken` 传递以获取下一页。
- **速率限制**：读取 100/6s，写入 10/6s，文档内容写入 5/10s。遵守 429 并退避。
- **新鲜读取**：添加请求头 `X-Coda-Doc-Version: latest` 以确保数据非陈旧（可能返回 400）。
- **valueFormat**：`simple`（默认）、`simpleWithArrays`、`rich` 用于结构化数据。
- **从 URL 获取文档 ID**：`https://coda.io/d/Title_d<DOC_ID>` → `_d` 之后的部分就是文档 ID。

## 直接 curl（脚本未覆盖时）

```bash
curl -s -H "Authorization: Bearer $CODA_API_TOKEN" \
  "https://coda.io/apis/v1/docs/{docId}/tables/{tableId}/rows?useColumnNames=true&limit=50"
```

用于写入：
```bash
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"
```

## 完整 API 参考

完整的端点列表（含参数、请求体模式和响应详情）请参见 [references/api-endpoints.md](references/api-endpoints.md)。

可按章节搜索：Account, Folders, Docs, Pages, Tables, Columns, Rows, Formulas, Controls, Permissions, Publishing, Automations, Analytics, Miscellaneous。