card-creation（卡片制作）

Domo Card CRUD API Reference

CLI vs API: The Java CLI supports backup-card and restore-card for duplicating existing cards to new pages. Try CLI first for simple card copy operations. Fall back to this REST API when you need to create cards from scratch with full control over chart type, columns, beast modes, and overrides — or when CLI restore-card fails (it does not support all chart types).

Complete reference for programmatic KPI card management via the Domo Product API. Verified February 2026 against live Domo instance. All 207 chart types documented with complete override data. 206/207 confirmed working for card creation (only badge_line fails). All edit operations (title, description, aliases, overrides, chart type changes) verified working.

Source code: gemini/documentation/_shared/tools/domo_card_tools.py (10 tool functions, production-ready) Last verified: 2026-02-27

Table of Contents

1. CRUD Endpoints
2. Complete Body Schema
3. Column Mapping
4. Beast Modes
5. Chart Types Reference
6. Conditional Formats
7. Code Examples
8. Gotchas

1. CRUD Endpoints

Base URL: https://{instance}.domo.com/api Auth Header: X-Domo-Authentication: {SID} (preferred — use a session SID from domo login / ryuu token exchange) or X-DOMO-Developer-Token: {your_token} (fallback — some endpoints reject dev tokens; SID works universally) Content-Type: application/json

READ Request Body

The READ endpoint is unusual -- it uses PUT, not GET, and requires a specific body:

{
  "dynamicText": true,
  "variables": true,
  "urn": "CARD_ID_HERE"
}

Supporting Endpoints

2. Complete Body Schema

This is the exact structure required for CREATE and UPDATE operations. Copied from the verified _build_card_body() function.

{
  "definition": {
    "subscriptions": {
      "big_number": {
        "name": "big_number",
        "columns": [
          {
            "column": "Revenue",
            "aggregation": "SUM",
            "alias": "Revenue",
            "format": {"type": "abbreviated", "format": "#A"}
          }
        ],
        "filters": []
      },
      "main": {
        "name": "main",
        "columns": [
          {"column": "Team", "mapping": "ITEM"},
          {"column": "Revenue", "mapping": "VALUE", "aggregation": "SUM"}
        ],
        "filters": [],
        "orderBy": [],
        "groupBy": [{"column": "Team"}],
        "fiscal": false,
        "projection": false,
        "distinct": false
      }
    },
    "formulas": {
      "dsUpdated": [],
      "dsDeleted": [],
      "card": []
    },
    "annotations": {
      "new": [],
      "modified": [],
      "deleted": []
    },
    "conditionalFormats": {
      "card": [],
      "datasource": []
    },
    "controls": [],
    "segments": {
      "active": [],
      "create": [],
      "update": [],
      "delete": []
    },
    "charts": {
      "main": {
        "component": "main",
        "chartType": "badge_vert_bar",
        "overrides": {},
        "goal": null
      }
    },
    "dynamicTitle": {
      "text": [{"text": "My Card Title", "type": "TEXT"}]
    },
    "dynamicDescription": {
      "text": [{"text": "Card description here", "type": "TEXT"}],
      "displayOnCardDetails": true
    },
    "chartVersion": "12",
    "inputTable": false,
    "noDateRange": false,
    "title": "My Card Title",
    "description": "Card description here"
  },
  "dataProvider": {
    "dataSourceId": "DATASET_UUID_HERE"
  },
  "variables": true,
  "columns": false
}

Field-by-Field Explanation

Root Level

definition.subscriptions.big_number

Controls the summary number shown at the top of the card. The subscription object is always required, but its columns array should be empty for single-value chart types (badge_singlevalue) since the card itself already displays the number — populating big_number would show it twice.

For all other chart types (bars, lines, tables, etc.), populate columns with the first VALUE column from main.

definition.subscriptions.main

The primary data subscription. This is where columns, filters, and groupings live.

Filter object structure:

{
  "column": "Type",
  "values": ["New Business"],
  "filterType": "LEGACY",
  "operand": "IN"
}

definition.formulas

Beast mode (calculated field) storage.

definition.annotations

definition.conditionalFormats

CRITICAL: Must be an object, NOT an array.

definition.controls

Array of interactive filter controls. Empty array [] for most cards.

definition.segments

CRITICAL: Must be an object, NOT an array.

definition.charts.main

definition.dynamicTitle / dynamicDescription

{
  "text": [{"text": "Title goes here", "type": "TEXT"}]
}

dynamicDescription also has "displayOnCardDetails": true.

Other definition fields

3. Column Mapping

Columns define what data appears in the card and how it maps to visual elements.

Mapping Types

Column Object Structure

For dataset columns:

{
  "column": "Team",
  "mapping": "ITEM",
  "aggregation": "SUM",
  "alias": "Team Name",
  "format": {"type": "number", "format": "###,##0"}
}

For beast mode columns:

{
  "formulaId": "calculation_123456",
  "mapping": "VALUE",
  "aggregation": "SUM",
  "alias": "Win Rate %"
}

Field Reference

*One of column or formulaId is required.

Examples by Chart Type

Bar chart (category + measure):

[
  {"column": "Region", "mapping": "ITEM"},
  {"column": "Revenue", "mapping": "VALUE", "aggregation": "SUM"}
]

Stacked bar (category + measure + series):

[
  {"column": "Region", "mapping": "ITEM"},
  {"column": "Revenue", "mapping": "VALUE", "aggregation": "SUM"},
  {"column": "Product Line", "mapping": "SERIES"}
]

Single value (measure only):

[
  {"column": "Revenue", "mapping": "VALUE", "aggregation": "SUM", "alias": "Total Revenue"}
]

Table (multiple items):

[
  {"column": "Name", "mapping": "ITEM"},
  {"column": "Department", "mapping": "ITEM"},
  {"column": "Revenue", "mapping": "VALUE", "aggregation": "SUM"},
  {"column": "Deals", "mapping": "VALUE", "aggregation": "COUNT"}
]

groupBy Auto-Generation

The groupBy array in subscriptions.main is auto-built from ITEM and SERIES columns:

group_by = []
for c in columns:
    if c.get("mapping") in ("ITEM", "SERIES") and "column" in c:
        group_by.append({"column": c["column"]})

4. Beast Modes

Beast Modes are Domo's calculated fields -- custom formulas that create new virtual columns from existing data.

Card-Level vs Dataset-Level

Creating a Beast Mode (Dataset-Level)

Endpoint: POST /query/v1/functions/template?strict=false

{
  "name": "Revenue per Deal",
  "owner": 705231757,
  "locked": false,
  "global": false,
  "expression": "SUM(`Distinct Closed Won ACV`) / COUNT(`Opportunity ID`)",
  "links": [
    {
      "resource": {"type": "DATA_SOURCE", "id": "DATASET_UUID"},
      "visible": true,
      "active": false,
      "valid": "VALID"
    }
  ],
  "aggregated": true,
  "analytic": false,
  "nonAggregatedColumns": [],
  "dataType": "DECIMAL",
  "status": "VALID",
  "cacheWindow": "non_dynamic",
  "columnPositions": [],
  "functions": [],
  "functionTemplateDependencies": [],
  "archived": false,
  "hidden": false,
  "variable": false
}

The response includes id (new UUID) and legacyId -- the legacyId is what you use as formulaId when referencing it in card columns.

dataType Options

Card-Level Beast Mode Structure

Card-level beast modes go in definition.formulas.card[] with full metadata including the formula expression, data type, and link to the dataset.

Referencing in Columns

Once created, reference a beast mode by its formulaId (the legacyId from the creation response):

{
  "formulaId": "calculation_123456789",
  "mapping": "VALUE",
  "aggregation": "SUM",
  "alias": "Revenue per Deal"
}

Note: Use formulaId instead of column -- they are mutually exclusive.

5. Chart Types Reference

Complete reference for all 207 chart types available in Domo's card API. Every type listed below has been verified to have override options and is available for programmatic card creation. Data sourced from the complete chart type options extraction (chart_type_options_complete.json).

Important: badge_line is the only known type that returns HTTP 400 on creation. Use badge_two_trendline or badge_spark_line instead.

Summary Table -- All 207 Chart Types

5.1 Bar Charts (24 types)

Standard, stacked, nested, percent, multi-axis, running total, overlay, and symbol bar variants.

Notable overrides unique to bar charts:

• width_percentage / height_percentage -- Control bar thickness
• fixed_bar_width / fixed_bar_height -- Absolute bar sizing
• allow_wide_bars / allow_tall_bars -- Allow bars to exceed default width
• datalabel_show_total -- Show stacked bar totals
• regression_line -- Trend line on bar charts (vert_bar, vert_stackedbar)
• last_value_projection / multi-period_projection -- Forecasting on bar charts
• value_scale_(left) / value_scale_(right) -- Dual Y axes on multibar
• show_as_trellis -- Small multiples / trellis mode

5.2 Line Charts (16 types)

Trend lines, curved lines, step lines, symbol lines, stacked trends, and variance lines.

Notable overrides unique to line charts:

• line_style -- Solid, Dashed, Dotted
• line_thickness -- Line weight
• outlier_filtering -- outliers_above, outliers_below to filter outlier data points
• scale_marker_range -- Shaded range bands (sm_min_val, sm_max_val, mkr_color)
• total_line -- Show aggregated total line (badge_two_trendline)
• line_labels_(right) -- show_line_labels, right_label_scale_display
• actual_line / target_line -- Variance line actual vs target styling
• show_linear_regression -- Trend/regression line overlay
• last_value_projection / multi-period_projection -- Forecasting projections

5.3 Combo Charts (18 types)

Line + bar, symbol + bar, curved line + bar, and nested line + bar combinations.

Notable overrides unique to combo charts:

• set_line_count -- Number of series rendered as lines vs bars
• value_scale_line / value_scale_bar -- Separate Y axes for line and bar
• value_scale_symbols -- Dedicated scale for symbol overlays
• last_bar_value_projection -- Bar-specific projection (project_bar_val_method, proj_bar_value)
• last_line_value_projection -- Line-specific projection (project_line_val_method, proj_line_value)
• title_line / title_bar -- Separate axis titles for line and bar scales

5.4 Area Charts (16 types)

Overlay, stacked, 100% area, with curved and step variants in both vertical and horizontal orientations.

Notable overrides unique to area charts:

• Area charts share standard chart overrides (grid_lines, data_labels, scales)
• No bar_settings (unlike bar and combo charts)
• Vertical variants include data_table; horizontal variants do not
• 100% area variants omit scale_marker (value axis is always 0-100%)
• Curved, step, and standard line interpolation variants share identical override structures

5.5 Dot Plot Charts (10 types)

Single, multi-series, stacked, and line+dot combinations.

Notable overrides unique to dot plot charts:

• Dot plots use standard axis/grid/label overrides (no bar_settings)
• Line + dot variants have dual scales: value_scale_line and value_scale_bar
• Stacked dot plots have the highest override counts in the group (149 vert, 144 horiz)
• All dot plot types support trellis_tiered_date_settings for small multiples

5.6 Pie / Donut / Rose (5 types)

Circular charts including standard pie, donut, nautilus spiral, and nightingale rose.

Notable overrides unique to pie/donut/rose:

• max_before_other -- Number of slices before grouping into "Other"
• other_fill_color -- Color for the "Other" slice
• border_color -- Slice border color
• hide_pie_labels -- Toggle slice labels
• legend_value -- Show values in the legend
• hvr_legend_title_text / hvr_legend_title_value -- Hover legend customization
• hide_hover_legend -- Toggle hover legend panel

5.7 Tables (5 types)

Basic, pivot, flex, standard, and heatmap table variants.

Notable overrides unique to tables:

• padding / header_padding / total_padding -- Row height controls
• enable_sorting / alphanumeric_sorting -- Interactive sorting
• header_row_fill_color / header_row_font_color -- Header styling
• total_row / total_row_label / total_row_suppress_count -- Total row config
• subtotal_rows / all_group_names -- Subtotal grouping
• use_heatmap_colors / color_theme / range_by_column -- Heatmap mode (basic_table)
• column_definitions -- Inline chart config (flex_table)
• graph_settings / graph_data_label_settings -- Inline chart styling (flex_table)
• excel_export_row_limit -- Export limits
• use_logscale -- Log scale for heatmap_table

5.8 Single Value & Gauges (14 types)

Big numbers, filled gauges, radial gauges, shape gauges, progress bars, and comparison gauges.

Notable overrides unique to gauges:

• value_type / value_format / value_label -- Value display config
• target_value / target_label / target_line_color -- Target line (filledgauge)
• min_value / max_value / hide_min_value / hide_max_value -- Gauge range
• radial_style / radial_indicator -- Gauge appearance (gauge)
• range1_min through range10_max / range1_color through range10_color -- Up to 10 color ranges (shapegauge)
• out_of_range_fill_color / out_of_range_symbol -- Out-of-range handling (shapegauge)
• shape_bkg_fill -- Shape background (shapegauge)
• green_range / yellow_range / red_range -- Traffic light ranges (facegauge)
• color_direction / gauge_val_displayed -- Comparison gauge config
• fill_color / bkg_ring_style / bkg_ring_fill_color -- Radial progress styling
• image_fit / default_imageurl / url_prefix -- Image gauge (imagegauge, only 4 overrides)
• gauge_style / gauge_width_pct / in_rng_fill_color -- In-range gauge config

5.9 Multi-Value (2 types)

Multi-metric summary cards with individual value formatting.

Notable overrides unique to multi-value:

• gauge_layout / gauge_sizing / item_padding -- Layout configuration
• title_text / title_font_color / title_font_family -- Per-value title styling
• hide_single_value / single_value_type / value_font_color -- Value display
• hide_change_value / comp_val_displayed / comp_data_used -- Comparison value config
• addl_text / addl_text_font_color -- Additional text per metric
• show_date_grain / date_grain_font_color -- Date grain display (multi_value only)
• tooltip1_value_type through tooltip3_value_type -- Tooltip metric selection

5.10 Maps (42 types)

World map, US state/county, lat/long, route, and 36 country-specific maps.

Country/region maps (all 114 overrides, identical categories: theme, general, diverging, hover_legend, data_label_settings, hover_text, values, number_format, ranges, cities):

badge_map_africa, badge_map_asia, badge_map_australia, badge_map_austria, badge_map_brazil, badge_map_canada, badge_map_chile, badge_map_china, badge_map_europe, badge_map_france, badge_map_france2016, badge_map_france_dept (115), badge_map_germany, badge_map_ghana, badge_map_india, badge_map_indonesia, badge_map_italy, badge_map_japan, badge_map_malaysia, badge_map_mexico, badge_map_middle_east, badge_map_new_zealand, badge_map_nigeria, badge_map_north_america, badge_map_panama, badge_map_peru, badge_map_philippines, badge_map_portugal, badge_map_south_america, badge_map_south_korea, badge_map_spain, badge_map_switzerland, badge_map_uae, badge_map_uk_area, badge_map_uk_postal, badge_map_united_kingdom

Notable overrides unique to maps:

• color_theme / use_custom_gradient_colors / num_colors -- Choropleth theming
• balanced_distribution / auto_zoom / hide_no_data_items -- Map behavior
• show_diverging / diverging_range_count / midpoint_value_type -- Diverging color scale
• range_1_text / range_1_min / range_1_max -- Manual range definitions
• show_cities -- City markers overlay
• hover_always_on_map -- Persistent hover tooltips
• symbol_color / symbol_size / symbol_transparency -- Lat/long point styling
• map_bkg_color / bkg_area_fill_color / ocean_fill_color -- Map background (latlong)
• routes -- Route path config (latlong_route)
• region_stroke_color -- Border styling (latlong)

5.11 Specialty (12 types)

Treemap, funnel, waffle, word cloud, stream, slope, bump, pareto, and heatmap.

Notable overrides unique to specialty charts:

• text_position / label_text -- Treemap label placement
• default_color_theme / force_max_value -- Treemap color value settings
• series_height / legacy_funnel -- Funnel sizing
• fnl_display_in_legend / fnl_legend_pct -- Funnel legend with percentages
• larger_rank_higher -- Bump chart rank direction
• rank_scale / label_scale -- Bump chart dedicated scales
• left_scale_(y) / right_scale_(y) -- Slope chart dual Y scales
• total_row_col -- Heatmap totals row/column

5.12 Gantt / Calendar (4 types)

Project timeline, dependency, percent complete, and calendar heatmap.

Notable overrides unique to Gantt/calendar:

• x_time_scale_show_weekends -- Show/hide weekends on time axis
• gantt_time_scale_show_labels -- Time axis labels
• x_time_scale_pos -- Time axis position
• height_percentage -- Gantt bar height
• hover_date_output_format -- Date format in tooltips
• duration_type / hours_in_day / weekends_included_in_duration -- Duration config (gantt_dep only)
• ranges / color_theme -- Calendar heatmap color ranges

5.13 Data Science (6 types)

Forecasting, outlier detection, predictive modeling, SPC control charts, and correlation/confusion matrices.

Notable overrides unique to data science charts:

• spc_symbol_type -- SPC chart data point symbol
• control_chart_rules -- SPC out-of-control rules (spc_rule_beyond_limits, spc_beyond_limits_fill_color)
• limit_lines -- SPC control limits (spc_avg_line_color, spc_ul_line_color, spc_avg_line_style)
• spc_ooc_fill_color -- Out-of-control point color
• spc_legend_show -- SPC-specific legend toggle
• Data science charts use both value_scale_y and value_scale_x (XY-style axes)

5.14 Period over Period (13 types)

Trend lines, bar+line combos, gauges, multi-value, and tables with period comparison.

Notable overrides unique to period-over-period:

• _var suffix types have dual value scales for variance display
• previous_period category -- hide_target_label, target_label, target_line_color (pop_filledgauge)
• range_by_val_or_pct -- Range definition method (pop_shapegauge)
• PoP types mirror their base chart types but with period comparison built in
• line_width (instead of line_thickness) in some PoP line types

5.15 Histogram (2 types)

Frequency distribution charts.

Notable overrides unique to histograms:

• histogram_bins -- Number of bins/buckets
• symbol_color -- Bar color (in bar_settings, not in a colors category)
• bottom_scale / cat_scale_manual_rotate -- Axis label rotation
• No legend, data_label_settings, or number_format categories (minimal config)

5.16 Box Plot (2 types)

Statistical distribution visualization with quartiles, median, and outliers.

Notable overrides unique to box plots:

• Standard axis/grid/label overrides only -- no legend, colors, or gradient categories
• No trellis/tiered date settings
• No regression line or projection capabilities

5.17 Waterfall (2 types)

Running total visualizations showing incremental positive and negative contributions.

Notable overrides unique to waterfall charts:

• sum_initial_group / initial_group_text -- Initial value bar config
• show_summary_bars -- Summary/subtotal bars
• summary_datalabel_text / summary_hover_text -- Summary bar labels
• bar_colors category (unique to waterfall):

- start_bar_color_from_value -- Color bars by positive/negative - start_bar_fill_color / end_bar_fill_color -- Start/end bar colors - Positive, negative, and subtotal bar colors

5.18 Scatter / Bubble (2 types)

XY scatter plots and bubble charts with size dimension.

Notable overrides unique to scatter/bubble:

• no_auto_sort -- Disable automatic data sorting (xy_line)
• regression category -- show_regression_lines, regression_line_style, regression_line_thickness
• quadrant_lines -- x_scale_value, y_scale_value reference lines creating 4 quadrants
• Both value_scale_y and value_scale_x (XY axes, not category + value)
• legend_position -- Full position control (not just top/bottom)

5.19 Selectors / Controls (6 types)

Interactive filter controls for dashboard interactivity.

Notable overrides unique to selectors:

• view_search -- Enable search within selector (checkbox, radio, slicer)
• show_hover_label -- Hover label visibility
• starting_view / selected_fill_color -- Date selector appearance
• calendar_view -- highlight_today, view, dates_from (date_selector)
• presets_view -- presets_only, presets_style, hide_day_presets (date_selector)
• allow_multi_select -- Multi-select toggle (dropdown_selector)
• dropdown_label_text / dropdown_label_pos -- Dropdown label config
• selector_fill_color / use_integers_only -- Range selector config

Selector Card Subscription Requirements

CRITICAL: Selector cards MUST have a non-empty big_number.columns array. An empty columns array causes 400 {"message":"big_number subscription missing select columns"}.

For dropdown/checkbox/radio/slicer selectors, use COUNT aggregation on the filtering column:

"big_number": {
    "name": "big_number",
    "columns": [{"column": "PlantName", "aggregation": "COUNT",
                 "alias": "PlantName",
                 "format": {"type": "abbreviated", "format": "#A"}}],
    "filters": [],
}

For date selectors, use MAX aggregation on the date column:

"big_number": {
    "name": "big_number",
    "columns": [{"column": "OrderDate", "aggregation": "MAX",
                 "alias": "OrderDate",
                 "format": {"type": "abbreviated", "format": "#A"}}],
    "filters": [],
}

The main subscription provides the values for the selector:

• Dropdown/checkbox/radio: columns: [{"column": "PlantName", "mapping": "ITEM"}] with groupBy: [{"column": "PlantName"}]
• Date selector: columns: [{"column": "OrderDate", "mapping": "ITEM"}] with groupBy: [] (empty)

App Studio Filter Card Best Practices

When used as page-level filters in App Studio, filter cards MUST be extremely low-profile — transparent background, no borders, minimal height. They are controls, not content, and should blend into the page without competing visually with heroes or charts.

Use standard template height of 6 (not 10) for minimal vertical footprint.

Global Card Styling (MANDATORY)

All cards in App Studio MUST follow the zero-chrome reference configuration. Apply via theme update:

These are applied globally to all card styles (ca1–ca8) via the theme cards array. See app-studio skill § "Card Styles" for the full implementation.

5.20 Text / Display (2 types)

Static and dynamic text content cards.

Notable overrides unique to text/display:

• text -- The actual text content (supports rich text)
• gauge_sizing -- Auto or fixed sizing
• abbrev_values -- Abbreviate inline values (dynamic_textbox)
• apply_chg_val_to_first / apply_chg_val_to_last / apply_chg_val_to_min -- Change value application (dynamic_textbox)

5.21 Marimekko (2 types)

Proportional area charts showing both category share and segment composition.

Notable overrides unique to marimekko:

• Standard axis/grid/label overrides (similar to bar charts)
• No bar_settings category (bar widths are proportional to data)
• No trellis, regression, or projection capabilities

5.22 Faceted Bar (2 types)

Small multiples bar charts with separate panels per category.

Notable overrides unique to faceted bar:

• facet_bar_space_percent -- Space between faceted panels
• label_scale -- Dedicated scale for facet labels (hide_labels, label_scale_position)
• value_scale (generic, not _y or _x) on vertical variant

Common Override Categories

Most chart types share a standard set of override categories. Here is what each controls:

Override Value Types

All override values are strings, even booleans and numbers.

6. Conditional Formats

Conditional formats allow color-coding values based on rules. The structure must be an object, not an array.

Required Structure

"conditionalFormats": {
  "card": [],
  "datasource": []
}

Conditional Format Rule Structure

{
  "card": [
    {
      "type": "COLOR",
      "column": "Revenue",
      "rules": [
        {
          "min": 0,
          "max": 50000,
          "color": "#FF0000",
          "label": "Below Target"
        },
        {
          "min": 50000,
          "max": 100000,
          "color": "#FFAA00",
          "label": "Near Target"
        },
        {
          "min": 100000,
          "color": "#00AA00",
          "label": "Above Target"
        }
      ]
    }
  ],
  "datasource": []
}

Common Mistakes

• Passing conditionalFormats as an array [] instead of object {card:[], datasource:[]} -- causes HTTP 400
• The Domo UI returns the format as an array when reading cards -- you must convert it to the object format before sending it back in an update

7. Code Examples

Python: Create a Card

import json
import urllib.request

INSTANCE = "domo.domo.com"
API_KEY = "your-developer-token"
PAGE_ID = "1227718422"
DATASET_ID = "d118d4fb-474a-487d-9e88-2b721a1b8a7f"

body = {
    "definition": {
        "subscriptions": {
            "big_number": {
                "name": "big_number",
                "columns": [{
                    "column": "Revenue",
                    "aggregation": "SUM",
                    "alias": "Revenue",
                    "format": {"type": "abbreviated", "format": "#A"}
                }],
                "filters": []
            },
            "main": {
                "name": "main",
                "columns": [
                    {"column": "Team", "mapping": "ITEM"},
                    {"column": "Revenue", "mapping": "VALUE", "aggregation": "SUM"}
                ],
                "filters": [],
                "orderBy": [],
                "groupBy": [{"column": "Team"}],
                "fiscal": False,
                "projection": False,
                "distinct": False
            }
        },
        "formulas": {"dsUpdated": [], "dsDeleted": [], "card": []},
        "annotations": {"new": [], "modified": [], "deleted": []},
        "conditionalFormats": {"card": [], "datasource": []},
        "controls": [],
        "segments": {"active": [], "create": [], "update": [], "delete": []},
        "charts": {
            "main": {
                "component": "main",
                "chartType": "badge_vert_bar",
                "overrides": {
                    "font_size": "Larger",
                    "use_gradient_colors": "true",
                    "gradient_start_fill_color": "#99CCEEFF"
                },
                "goal": None
            }
        },
        "dynamicTitle": {"text": [{"text": "Revenue by Team", "type": "TEXT"}]},
        "dynamicDescription": {"text": [], "displayOnCardDetails": True},
        "chartVersion": "12",
        "inputTable": False,
        "noDateRange": False,
        "title": "Revenue by Team",
        "description": ""
    },
    "dataProvider": {"dataSourceId": DATASET_ID},
    "variables": True,
    "columns": False
}

url = f"https://{INSTANCE}/api/content/v3/cards/kpi?pageId={PAGE_ID}"
headers = {
    "X-DOMO-Developer-Token": API_KEY,
    "Content-Type": "application/json"
}
data = json.dumps(body).encode()
req = urllib.request.Request(url, data=data, method="PUT", headers=headers)

with urllib.request.urlopen(req) as resp:
    result = json.loads(resp.read())
    print(f"Created card: {result['id']}")

Python: Read a Card

url = f"https://{INSTANCE}/api/content/v3/cards/kpi/definition"
body = {"dynamicText": True, "variables": True, "urn": "CARD_ID"}
data = json.dumps(body).encode()
req = urllib.request.Request(url, data=data, method="PUT", headers=headers)

with urllib.request.urlopen(req) as resp:
    result = json.loads(resp.read())
    chart_type = result["definition"]["charts"]["main"]["chartType"]
    title = result["definition"]["dynamicTitle"]["text"][0]["text"]
    print(f"Card: {title} ({chart_type})")

Python: Update a Card

# Same body structure as CREATE, but endpoint includes cardId
url = f"https://{INSTANCE}/api/content/v3/cards/kpi/{CARD_ID}"
body["definition"]["title"] = "Updated Title"
body["definition"]["dynamicTitle"]["text"][0]["text"] = "Updated Title"
body["definition"]["charts"]["main"]["chartType"] = "badge_pie"

data = json.dumps(body).encode()
req = urllib.request.Request(url, data=data, method="PUT", headers=headers)

with urllib.request.urlopen(req) as resp:
    result = json.loads(resp.read())
    print(f"Updated card: {result['id']}")

Python: Copy a Card

url = f"https://{INSTANCE}/api/content/v1/cards/{CARD_ID}/copy"
data = json.dumps({}).encode()
req = urllib.request.Request(url, data=data, method="POST", headers=headers)

with urllib.request.urlopen(req) as resp:
    result = json.loads(resp.read())
    print(f"Copied to new card: {result['id']}")

Python: Delete a Card

url = f"https://{INSTANCE}/api/content/v1/cards/{CARD_ID}"
req = urllib.request.Request(url, method="DELETE", headers=headers)

with urllib.request.urlopen(req) as resp:
    print(f"Deleted card {CARD_ID}")

curl: Create a Card

curl -X PUT "https://domo.domo.com/api/content/v3/cards/kpi?pageId=1227718422" \
  -H "X-DOMO-Developer-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "definition": {
      "subscriptions": {
        "big_number": {
          "name": "big_number",
          "columns": [{"column":"Revenue","aggregation":"SUM","alias":"Revenue","format":{"type":"abbreviated","format":"#A"}}],
          "filters": []
        },
        "main": {
          "name": "main",
          "columns": [
            {"column":"Team","mapping":"ITEM"},
            {"column":"Revenue","mapping":"VALUE","aggregation":"SUM"}
          ],
          "filters": [], "orderBy": [], "groupBy": [{"column":"Team"}],
          "fiscal": false, "projection": false, "distinct": false
        }
      },
      "formulas": {"dsUpdated":[],"dsDeleted":[],"card":[]},
      "annotations": {"new":[],"modified":[],"deleted":[]},
      "conditionalFormats": {"card":[],"datasource":[]},
      "controls": [],
      "segments": {"active":[],"create":[],"update":[],"delete":[]},
      "charts": {"main":{"component":"main","chartType":"badge_vert_bar","overrides":{},"goal":null}},
      "dynamicTitle": {"text":[{"text":"Revenue by Team","type":"TEXT"}]},
      "dynamicDescription": {"text":[],"displayOnCardDetails":true},
      "chartVersion": "12", "inputTable": false, "noDateRange": false,
      "title": "Revenue by Team", "description": ""
    },
    "dataProvider": {"dataSourceId": "YOUR_DATASET_UUID"},
    "variables": true,
    "columns": false
  }'

curl: Read a Card

curl -X PUT "https://domo.domo.com/api/content/v3/cards/kpi/definition" \
  -H "X-DOMO-Developer-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"dynamicText":true,"variables":true,"urn":"CARD_ID"}'

curl: Copy a Card

curl -X POST "https://domo.domo.com/api/content/v1/cards/CARD_ID/copy" \
  -H "X-DOMO-Developer-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

curl: Delete a Card

curl -X DELETE "https://domo.domo.com/api/content/v1/cards/CARD_ID" \
  -H "X-DOMO-Developer-Token: YOUR_TOKEN"

8. Gotchas

Critical -- Will Cause Failures

Important -- Affects Behavior

Workspace API (Related)

Workspace entity types: card, page, dataset, data_app, dataflow, workflow_model.

Appendix: Quick Reference Card

CREATE:  PUT  /content/v3/cards/kpi?pageId=PAGE_ID        (full body)
READ:    PUT  /content/v3/cards/kpi/definition             ({"dynamicText":true,"variables":true,"urn":"ID"})
UPDATE:  PUT  /content/v3/cards/kpi/CARD_ID                (full body)
COPY:    POST /content/v1/cards/CARD_ID/copy               ({})
DELETE:  DELETE /content/v1/cards/CARD_ID                   (no body)

Auth:    X-DOMO-Developer-Token: YOUR_TOKEN
Base:    https://{instance}.domo.com/api

Required root fields: variables=true, columns=false
Required data field:  dataProvider.dataSourceId (NOT dsId)
Required subscriptions: big_number AND main (big_number.columns=[] for badge_singlevalue)
conditionalFormats:   {card:[], datasource:[]}  (OBJECT, not array)
segments:             {active:[], create:[], update:[], delete:[]}  (OBJECT, not array)

Line charts:          badge_two_trendline (NOT badge_line)
Documented chart types: 207 total (206 work via API, badge_line fails)