coda

Files (3)

• SKILL.md
• _meta.json
• coda_cli.py · scripts/

SKILL.md (first lines)

# 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

From Trompetilla/Skills, MIT.

More from Trompetilla/Skills