Agent-Skills.md

Agent Skills: Metabase

Metabase REST API automation: auth, export/upsert cards and dashboards, visualization_settings. Use when scripting Metabase via API.

UncategorizedID: vasilyu1983/ai-agents-public/data-metabase

Repository

vasilyu1983/ai-agents-public
vasilyu1983License: MIT
4911

Install this agent skill to your local

pnpm dlx add-skill https://github.com/vasilyu1983/AI-Agents-public/tree/HEAD/frameworks/shared-skills/skills/data-metabase

Skill Files

Browse the full folder contents for data-metabase.

Download Skill

Loading file tree…

frameworks/shared-skills/skills/data-metabase/SKILL.md

Skill Metadata

Name
data-metabase
Description
"Metabase REST API automation: auth, export/upsert cards and dashboards, visualization_settings. Use when scripting Metabase via API."

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)

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