Metabase

Metabase

Automate Metabase via API: reports (cards), dashboards, and chart settings.

Quick Start

Inputs (env vars)

• METABASE_URL (e.g., https://metabase.example.com)
• Preferred: METABASE_API_KEY
• Fallback: METABASE_USERNAME + METABASE_PASSWORD

Sanity checks

python3 frameworks/​shared-skills/​skills/​data-metabase/​scripts/​metabase_api.py health
python3 frameworks/​shared-skills/​skills/​data-metabase/​scripts/​metabase_api.py whoami

Live API documentation

Your Metabase instance serves OpenAPI docs at /​api/​docs (e.g., https://metabase.example.com/​api/​docs). Use this to discover version-specific endpoints and request shapes.

Workflow

1. Confirm API availability (GET /​api/​util/​health).
2. Authenticate with an API key (preferred) or a short-lived session (fallback).
3. Discover IDs (prefer discovery over hardcoding across environments):
   • collection_id for where to save
   • database id for dataset_query
   • source-table / field ids if using MBQL
4. Create/​update a card:
   • Prefer native SQL for stable automation.
   • Set display + visualization_settings explicitly.
5. Create/​update a dashboard and add cards with consistent layout.
6. Validate by running/​exporting results.

Key Concepts

• UI "Question" == API card
• Chart configuration lives on the card as display + visualization_settings
• Most viz keys are easiest to manage by copying from an existing card JSON, then editing

Guardrails

• Prefer Metabase "serialization" (Pro/​Enterprise) for bulk, cross-environment migrations; use direct API for incremental upserts.
• Do not hardcode numeric IDs across environments when you can discover them or use serialization/​entity IDs.
• Never commit METABASE_API_KEY, passwords, or session tokens.
• Prefer a dedicated, least-privileged automation account and collection.

References (read only as needed)

Scripts

scripts/​metabase_api.py is a small, dependency-free helper to test auth and upsert cards.

Examples:

# Print authenticated user (tries API key, then session)
python3 frameworks/​shared-skills/​skills/​data-metabase/​scripts/​metabase_api.py whoami

# Export an existing card JSON (use as a template for visualization_settings)
python3 frameworks/​shared-skills/​skills/​data-metabase/​scripts/​metabase_api.py export-card --id 123 --out card.json

# Export an existing dashboard JSON (use as a template for layout)
python3 frameworks/​shared-skills/​skills/​data-metabase/​scripts/​metabase_api.py export-dashboard --id 5 --out dashboard.json

# Create/​update a card from a JSON spec (see references/​reports-cards.md)
python3 frameworks/​shared-skills/​skills/​data-metabase/​scripts/​metabase_api.py upsert-card --spec card-spec.json

# Create/​update a dashboard from a JSON spec (base fields only)
python3 frameworks/​shared-skills/​skills/​data-metabase/​scripts/​metabase_api.py upsert-dashboard --spec dashboard-spec.json