coda

# Coda API Skill

Interact with the Coda REST API v1 to manage docs, tables, rows, pages, and automations.

## When to Use

Use this skill when the user wants to:
- List, search, create, or delete Coda docs
- Read from or write to tables (insert, upsert, update, delete rows)
- Explore doc structure (pages, tables, columns, formulas, controls)
- Trigger automations (push buttons)
- Export doc content or analytics

## When NOT to Use

- **Do NOT use** for general document editing advice unrelated to the API
- **Do NOT use** for Pack development (this skill covers Doc management, not Pack creation)
- **Do NOT use** for operations requiring Doc Maker permissions unless confirmed the user has them

## Prerequisites

1. **API Token**: Set environment variable `CODA_API_TOKEN` with your Coda API token
   - Get token at: https://coda.io/account -> API Settings
2. **Python 3.7+** with `requests` library installed
3. **Permissions**: Some operations (create doc, update doc title, create page) require Doc Maker role in the workspace

## CLI Tool Usage

The skill includes a Python CLI tool at `scripts/coda_cli.py`:

```bash
# Setup
export CODA_API_TOKEN="your_token_here"

# List docs
python scripts/coda_cli.py docs list --query "Project"

# Get doc info
python scripts/coda_cli.py docs get <doc-id>

# Create doc
python scripts/coda_cli.py docs create --title "My New Doc"

# List tables in doc
python scripts/coda_cli.py tables list <doc-id>

# List rows in table
python scripts/coda_cli.py rows list <doc-id> <table-id>

# Insert row
python scripts/coda_cli.py rows insert <doc-id> <table-id> --data '{"Name": "Task 1", "Status": "Done"}'

# Update row
python scripts/coda_cli.py rows update <doc-id> <table-id> <row-id> --data '{"Status": "In Progress"}'

# Delete row (requires confirmation)
python scripts/coda_cli.py rows delete <doc-id> <table-id> <row-id>

# List pages
python scripts/coda_cli.py pages list <doc-id>

# Trigger automation (push button)
python scripts/coda_cli.py automations trigger <doc-id> <button-id>

# Force delete without confirmation (use with caution)
python scripts/coda_cli.py docs delete <doc-id> --force
```

## Workflow Guidelines

### 1. Doc ID Extraction
Coda doc IDs can be extracted from browser URLs:
- URL: `https://coda.io/d/_dAbCDeFGH/Project-Tracker`
- Doc ID: `AbCDeFGH` (remove `_d` prefix)

The CLI tool accepts both full URLs and raw IDs.

### 2. Rate Limit Handling
The API has strict rate limits:
- **Read**: 100 requests per 6 seconds
- **Write (POST/PUT/PATCH)**: 10 requests per 6 seconds
- **Write doc content**: 5 requests per 10 seconds
- **List docs**: 4 requests per 6 seconds

The CLI tool automatically implements exponential backoff for 429 responses.

### 3. Asynchronous Operations
Write operations return HTTP 202 with a `requestId`. The CLI tool optionally polls for completion using `--wait` flag.

### 4. Safety Guardrails

**Delete Operations** (rows, docs, pages, folders):
- Always requires explicit user confirmation in interactive mode
- Use `--force` flag only in automation/scripts
- Shows preview of what will be deleted

**Publishing** (`docs publish`):
- Requires explicit `--confirm-publish` flag
- Cannot be combined with `--force`

**Permissions** (`acl` commands):
- Requires explicit `--confirm-permissions` flag for any changes
- Read operations (list permissions) are always allowed

**Automation Triggers**:
- Allowed without special flags but logged
- User should be aware that automations may trigger notifications or external actions

### 5. Pagination
List commands support:
- `--limit`: Maximum results (default 25, max varies by endpoint)
- `--page-token`: For fetching subsequent pages
- CLI auto-follows pages with `--all` flag

## Common Patterns

### Batch Row Operations
```bash
# Insert multiple rows from JSON file
python scripts/coda_cli.py rows insert-batch <doc-id> <table-id> --file rows.json

# Upsert rows (update if exists, insert if not) using key columns
python scripts/coda_cli.py rows upsert <doc-id> <table-id> --file rows.json --keys "Email"
```

### Sync Between Docs
```bash
# Export from source
python scripts/coda_cli.py rows list <source-doc> <table-id> --format json > export.json

# Import to destination
python scripts/coda_cli.py rows insert-batch <dest-doc> <table-id> --file export.json
```

### Explore Structure
```bash
# Get full doc structure
python scripts/coda_cli.py docs structure <doc-id>

# List all formulas
python scripts/coda_cli.py formulas list <doc-id>

# List all controls
python scripts/coda_cli.py controls list <doc-id>
```

## Error Handling

Common HTTP status codes:
- `400`: Bad request (invalid parameters)
- `401`: Invalid/expired API token
- `403`: Insufficient permissions (need Doc Maker role)
- `404`: Resource not found
- `429`: Rate limited (implement backoff)
- `202`: Accepted but not yet processed (async operation)

## Security Considerations

1. **Token Storage**: Never commit `CODA_API_TOKEN` to version control
2. **Token Scope**: The token has full access to all docs the user can access
3. **Workspace Restrictions**: Creating docs requires Doc Maker role in target workspace
4. **Data Exposure**: Row data may contain sensitive information; handle exports carefully

## Examples

### List and Filter Docs
```bash
python scripts/coda_cli.py docs list --is-owner --query "Project"
```

### Create Doc from Template
```bash
python scripts/coda_cli.py docs create --title "Q4 Planning" --source-doc "template-doc-id"
```

### Update Row Status
```bash
python scripts/coda_cli.py rows update AbCDeFGH grid-xyz row-123 \
  --data '{"Status": "Complete", "Completed Date": "2024-01-15"}'
```

### Delete Multiple Rows (with confirmation)
```bash
python scripts/coda_cli.py rows delete-batch AbCDeFGH grid-xyz \
  --filter '{"Status": "Archived"}' \
  --confirm "Delete all archived rows?"
```

### Export Table to CSV
```bash
python scripts/coda_cli.py rows list AbCDeFGH grid-xyz --format csv > export.csv
```

## Reference

- API Documentation: https://coda.io/developers/apis/v1
- OpenAPI Spec: https://coda.io/apis/v1/openapi.yaml
- Rate Limits: https://coda.io/developers/apis/v1#section/Rate-Limiting