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_id for where to save

• database id for dataset_query

• source-table / field ids if using MBQL

• Create/update a card:

• Prefer native SQL for stable automation.

• Set display

• visualization_settings explicitly.

• 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.