Solanasis Docs

coda-backup-playbook-for-ai

10 min read

Coda Local Backup Playbook for Claude Code

Purpose

This playbook captures the key parts of our discussion about backing up data from a free Coda account to local files using a script, so another AI agent such as Claude Code can pick it up and implement or improve it.

The target outcome is a repeatable backup flow that exports:

  • Pages as Markdown (.md)
  • Tables/views as CSV (.csv)
  • Metadata/manifests as JSON (.json)

This is meant to supplement, not replace, Coda’s own built-in account export in the UI.

Executive Summary

Core conclusion

Yes — Coda data can be backed up locally with a script.

Best practical approach

Use two layers of backup:

  1. Coda UI export as a baseline/manual safety net
  2. Scripted API backup for repeatable local exports to Markdown and CSV

Role of Claude Code

Claude Code is not the export mechanism by itself. Instead, it can:

  • write the backup script
  • refine it
  • run it locally
  • troubleshoot failures
  • extend it with incremental backups, scheduling, logging, and validation

What We Determined

1) There is no native “Claude Code → back up all of Coda” button

Claude Code does not appear to have a built-in one-click feature that mirrors Coda’s full account export UI.

So the realistic path is:

  • get a Coda API token
  • run a local script
  • have Claude Code help write/maintain that script

2) Coda’s UI export is still useful

Coda’s own export flow is the fastest official fallback when you just want a baseline dump of data.

Use it for:

  • immediate safety backup
  • comparison against your scripted output
  • occasional sanity checks

3) The public API is good enough for a strong working backup

The API supports the pieces needed for a very usable local backup workflow:

  • list docs
  • list pages
  • export page content to Markdown
  • list tables/views
  • list columns
  • fetch rows
  • write CSV locally

4) The backup script should be multi-step, not “one magic endpoint”

The script should walk your account/doc structure and export each part methodically.

Option A — Minimum viable backup

Use the UI export manually from time to time.

Pros

  • fastest
  • official
  • low effort

Cons

  • manual
  • not very automation-friendly
  • less structured for ongoing AI workflows

Option B — Recommended operational backup

Create a script that backs up all owned docs to local folders.

Pros

  • repeatable
  • scriptable
  • Claude Code can maintain it
  • better for long-term operational use
  • easier to diff, inspect, and feed to other AI tools

Cons

  • more initial setup
  • requires API token and local runtime
  • needs pagination/retry handling

Recommendation

Do both.

  • Use UI export now for a baseline snapshot.
  • Use scripted backups going forward for your ongoing workflow.

Target Output Structure

A good local structure looks like this:

coda-backups/
  2026-03-08/
    docs/
      Example Doc/
        metadata.json
        pages/
          Home.md
          SOPs.md
          Notes/
            Weekly Review.md
        tables/
          CRM Contacts.csv
          Opportunities.csv
          Tasks.csv
      Another Doc/
        metadata.json
        pages/
        tables/
    backup_manifest.json
    backup_log.txt

Why this structure works

  • easy to inspect manually
  • easy for AI tools to traverse
  • easy to version with Git if desired
  • separates content types cleanly

Functional Requirements for the Script

The script should:

  1. authenticate using a Coda API token
  2. list all docs you own
  3. create a local folder for each doc
  4. export each page as Markdown
  5. export each table/view as CSV
  6. save metadata for docs/pages/tables
  7. handle pagination
  8. handle retry/backoff for throttling/errors
  9. create a manifest of what was exported
  10. support reruns without duplicating chaos

Nice-to-have features

  • incremental mode
  • “changed since last run” logic
  • log file output
  • dry-run mode
  • doc include/exclude filters
  • filename sanitization
  • structured error summary

Architecture for the Backup Flow

Step 1 — Authentication

Use an API token stored in an environment variable.

Recommended env var name:

CODA_API_TOKEN

Avoid hardcoding the token into the script.

Step 2 — List all owned docs

The script should first discover which docs to back up.

The intended behavior is:

  • pull docs accessible to the token
  • restrict to docs you own where possible
  • paginate until finished

Important note

“Owned docs” is the safest first target because it matches the spirit of Coda’s own account export more closely than “everything accessible.”

Step 3 — Export pages as Markdown

For each doc:

  • list its pages
  • start an export job for each page in Markdown format
  • poll until the export is ready
  • download the exported content
  • save it as .md

Why Markdown matters

Markdown is ideal because:

  • Claude Code works with it naturally
  • it is portable
  • it is diff-friendly
  • it is future-proof enough for notes, SOPs, and docs

Caveat

Some complex page content may not serialize perfectly into elegant Markdown. You should still capture it because imperfect Markdown is often better than no backup.

Step 4 — Export tables and views as CSV

For each doc:

  • list tables/views
  • fetch columns
  • fetch rows
  • convert row values into flat output where feasible
  • write CSV files

CSV export goals

The backup should prioritize:

  • readability
  • tabular recovery
  • AI-ingest friendliness

Caveat

Rich cell types may need normalization, such as:

  • people objects
  • lookup values
  • arrays
  • structured references

In practice, serialize complex objects into JSON strings inside CSV cells when necessary.

Step 5 — Save metadata

For each doc and backup run, save JSON metadata such as:

  • doc name
  • doc id
  • page ids/titles
  • table ids/names
  • timestamps from the API when available
  • export time
  • row counts
  • errors/warnings

This makes future incremental or validation workflows much easier.

Step 6 — Manifest and logging

At the end of a run, produce:

  • backup_manifest.json
  • backup_log.txt

The manifest should summarize:

  • docs attempted
  • pages exported
  • tables exported
  • failures
  • timing

Error Handling Requirements

The script should be resilient.

It must handle:

  • pagination
  • temporary API failures
  • rate limits / throttling
  • missing permissions on specific items
  • empty docs/tables
  • strange filenames
  • partial failures without aborting the whole run

Failure philosophy

Do not fail the whole backup just because one page or table breaks.

Instead:

  • log the error
  • continue processing
  • report failures at the end

Incremental Backup Guidance

A smart next version should support incremental runs.

Phase 1 — Full backup first

Start with full export of:

  • all owned docs
  • all pages
  • all tables

Phase 2 — Incremental mode

Then add logic such as:

  • compare against previous manifest
  • skip unchanged content when reliable metadata exists
  • optionally use updatedAt-style fields where available

Important caution

Incremental mode is useful, but only after the full-backup version is reliable.

Security Guidance

Store secrets safely

Use environment variables or a local secrets store.

Do not:

  • commit the token to Git
  • paste the token into random docs
  • hardcode it into the script

Local backup safety

If your Coda docs include sensitive information, treat the backup folder like sensitive data.

Recommended practices:

  • store on encrypted disk if possible
  • include it in your overall backup policy deliberately
  • avoid syncing it blindly to insecure cloud folders

Suggested Local Tech Stack

For your use case, Python is the best first implementation.

  • Python 3.11+
  • requests
  • built-in csv
  • built-in json
  • built-in pathlib
  • optional tenacity for retries

Why Python

  • easy for Claude Code to maintain
  • cross-platform
  • good for APIs and filesystem work
  • easy to schedule later

Good future additions

  • PowerShell wrapper for Windows convenience
  • scheduled task / cron entry
  • Git-based snapshotting

Script Behavior Specification

A solid CLI should support commands like:

python coda_backup.py --output ./coda-backups
python coda_backup.py --output ./coda-backups --incremental
python coda_backup.py --output ./coda-backups --doc "Sales CRM"
python coda_backup.py --output ./coda-backups --pages-only
python coda_backup.py --output ./coda-backups --tables-only
  • --output
  • --incremental
  • --doc
  • --pages-only
  • --tables-only
  • --dry-run
  • --verbose

Claude Code Handoff Prompt

Use this prompt with Claude Code:

You are helping maintain a local Coda backup utility.
 
Goal:
Create or improve a Python script that backs up all Coda docs I own into local files.
 
Required outputs:
- Pages exported as Markdown (.md)
- Tables/views exported as CSV (.csv)
- Metadata/manifests exported as JSON (.json)
 
Requirements:
- Read CODA_API_TOKEN from environment variables
- List all docs I own
- Handle pagination correctly
- Export each page as Markdown using the proper async export flow
- Export each table/view as CSV by fetching columns and rows
- Sanitize filenames safely
- Continue on partial failures
- Produce a final backup_manifest.json and backup_log.txt
- Support an --incremental mode
- Use clean, production-lean code with comments and basic error handling
 
Implementation preferences:
- Python 3.11+
- requests preferred unless there is a strong reason otherwise
- Keep the code easy to extend
- Add clear TODO comments where the API may return inconsistent object shapes
 
Please also:
1. Review the script for correctness
2. Point out edge cases
3. Suggest any endpoint or schema assumptions that may break
4. Refactor for maintainability if needed

Practical Workflow for You

Immediate action plan

1. Do a manual Coda UI export now

This gives you a baseline backup immediately.

2. Store your Coda API token locally

Use an environment variable.

3. Use the starter script as v1

Run a full backup into a dated folder.

4. Inspect output quality

Check:

  • Markdown exports readable?
  • CSVs structurally sound?
  • Any pages/tables missing?

5. Use Claude Code to harden the script

Have it improve:

  • retries
  • incremental mode
  • normalization
  • logging
  • scheduling

6. Schedule regular runs later

After the script is reliable, schedule it.

Validation Checklist

Use this after your first run:

  • all expected docs appear locally
  • each doc has a metadata file
  • major pages exist as .md
  • important tables exist as .csv
  • no obvious truncation
  • errors are logged instead of silently ignored
  • rerunning does not create chaos
  • filenames are safe on your OS
  • sensitive backups are stored securely

Common Edge Cases to Watch

1. Docs not returned because of scope/ownership assumptions

The first script version should be explicit about whether it is backing up:

  • owned docs only
  • all accessible docs

2. Nested or oddly named pages

You may want folder nesting for parent/child pages, or flattening with unique filenames.

3. Rich content that Markdown can’t represent perfectly

Expect some imperfections.

4. Complex cell values in tables

Normalize them consistently rather than pretending everything is a plain string.

5. API throttling

Add backoff and retries.

6. Large docs

Be mindful of polling, pagination, and timeouts.

What “Good Enough” Looks Like

A successful v1 backup system is one where:

  • you can run one script command in the future
  • all owned docs get exported locally
  • pages become Markdown
  • tables become CSV
  • failures are visible
  • the structure is organized enough for another AI to work with it

That is the right target. Not perfection on day one.

Final Recommendation

Build the system around this principle:

Official UI export for baseline safety. Scripted API export for repeatable operational backups.

That gives you:

  • immediate safety
  • local ownership
  • AI-friendly file formats
  • a workflow Claude Code can keep improving over time

Companion Files

This playbook pairs well with:

  • coda_backup.py — starter Python backup script
  • a .env or local environment variable setup for CODA_API_TOKEN
  • a future PowerShell wrapper if you want one-command execution on Windows

Suggested Next Iteration

After v1 is working, have Claude Code add:

  1. stronger incremental backup logic
  2. better CSV normalization for rich cell types
  3. scheduled execution
  4. checksum or diff reporting
  5. restore-oriented documentation
  6. optional Git snapshotting of Markdown outputs

One-Sentence Summary for Another AI

Create and maintain a Python-based Coda backup utility that exports all owned docs locally, saving pages as Markdown, tables/views as CSV, and metadata/manifests as JSON, with pagination, retries, safe filenames, and incremental support.

Graph View