tomevault-io 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
- Confirm API availability (
GET /api/util/health). - Authenticate with an API key (preferred) or a short-lived session (fallback).
- Discover IDs (prefer discovery over hardcoding across environments):
collection_idfor where to savedatabaseid fordataset_querysource-table/ field ids if using MBQL
- Create/update a card:
- Prefer native SQL for stable automation.
- Set
display+visualization_settingsexplicitly.
- Create/update a dashboard and add cards with consistent layout.
- 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)
| Topic | File |
|---|---|
| Authentication (API key + fallback) | references/api-auth.md |
| Reports (cards): create/edit patterns | references/reports-cards.md |
| Dashboards and card placement | references/dashboards.md |
Charts and visualization_settings |
references/charts-settings.md |
| Embedding & external integration | references/embedding-integration.md |
| Permissions & collections management | references/permissions-collections.md |
| Native SQL query patterns | references/native-query-patterns.md |
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
Fact-Checking
- Use web search/web fetch to verify current external facts, versions, pricing, deadlines, regulations, or platform behavior before final answers.
- Prefer primary sources; report source links and dates for volatile information.
- If web access is unavailable, state the limitation and mark guidance as unverified.
Converted and distributed by TomeVault — claim your Tome and manage your conversions.