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
- API Token: Set environment variable
CODA_API_TOKEN with your Coda API token
- Python 3.7+ with
requests library installed
- Permissions: Some operations (create doc, update doc title, create page) require Doc Maker role in the workspace
The skill includes a Python CLI tool at scripts/coda_cli.py:
# 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
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
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
# 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
# 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
# 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 token403: Insufficient permissions (need Doc Maker role)404: Resource not found429: Rate limited (implement backoff)202: Accepted but not yet processed (async operation)
Security Considerations
- Token Storage: Never commit
CODA_API_TOKEN to version control
- Token Scope: The token has full access to all docs the user can access
- Workspace Restrictions: Creating docs requires Doc Maker role in target workspace
- Data Exposure: Row data may contain sensitive information; handle exports carefully
Examples
List and Filter Docs
python scripts/coda_cli.py docs list --is-owner --query "Project"
Create Doc from Template
python scripts/coda_cli.py docs create --title "Q4 Planning" --source-doc "template-doc-id"
Update Row Status
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)
python scripts/coda_cli.py rows delete-batch AbCDeFGH grid-xyz \
--filter '{"Status": "Archived"}' \
--confirm "Delete all archived rows?"
Export Table to CSV
python scripts/coda_cli.py rows list AbCDeFGH grid-xyz --format csv > export.csv
Reference