Card Creation

Domo Card CRUD Reference

CLI vs raw API: All card operations use the community-domo-cli. No raw curl/fetch needed. The CLI wraps the Domo Product API endpoints and handles auth automatically.

Complete reference for programmatic KPI card management. 207 chart types documented with override data. 206/207 confirmed working (only badge_line fails).

1. CRUD Operations

Create a Card

community-domo-cli --output json -y cards create \
  --body-file card.json --page-id $PAGE_ID > card_response.json

CARD_ID=$(python3 -c "import json; print(json.load(open('card_response.json'))['id'])")

--page-id is required for creation.

Read a Card Definition

community-domo-cli --output json cards definition $CARD_ID > card_def.json

Returns definition, dataSourceWrite, drillpath, columns. See Gotchas for read/write format mismatches.

Update a Card

community-domo-cli --output json -y cards update $CARD_ID \
  --body-file card_updated.json

Full body replacement — include ALL fields, not just changed ones. Always read first, modify, write back.

Copy a Card (raw API — no CLI command)

curl -X POST "https://$INSTANCE/api/content/v1/cards/$CARD_ID/copy" \
  -H "x-domo-developer-token: $TOKEN" -H "Content-Type: application/json" -d '{}'

Delete a Card (raw API — no CLI command)

curl -X DELETE "https://$INSTANCE/api/content/v1/cards/$CARD_ID" \
  -H "x-domo-developer-token: $TOKEN"

Permanent, cannot be undone.

Supporting Operations

# Discover dataset columns before creating cards
community-domo-cli --output json datasets schema $DATASET_ID > schema.json

# List cards on a page
community-domo-cli --output json pages list-cards $PAGE_ID

# Add an existing card to another page (goes to appendix)
community-domo-cli -y pages add-card $PAGE_ID $CARD_ID

# Create a beast mode / variable
community-domo-cli --output json -y beast-modes create --body-file beastmode.json

2. Complete Body Schema

This is the exact structure required for CREATE and UPDATE operations.

{
  "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 Reference

Root Level

definition.subscriptions.big_number

Controls the summary number at the top of the card. Always required, but columns should be empty for badge_singlevalue (the card itself displays the number).

definition.subscriptions.main

Filter object structure:

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

definition.formulas

definition.charts.main

definition.conditionalFormats — MUST be object

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

definition.segments — MUST be object

{"active": [], "create": [], "update": [], "delete": []}

definition.dynamicTitle / dynamicDescription

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

dynamicDescription also has "displayOnCardDetails": true.

Other definition fields

3. Column Mapping

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

Build groupBy from all 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

Card-Level vs Dataset-Level

Creating a Beast Mode (Dataset-Level)

community-domo-cli --output json -y beast-modes create \
  --body-file beastmode.json > bm_response.json

Body:

{
  "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 (UUID) and legacyId — use legacyId as formulaId in card columns.

dataType Options

5. Chart Type Index

207 chart types across 22 groups. Pick a badge_* type string from the index below, then read the corresponding reference file for override details.

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

Common Override Categories

Most chart types share these standard override categories:

Override Value Types

All override values are strings, even booleans and numbers.

6. Conditional Formats

The structure must be an object, not an array.

"conditionalFormats": {
  "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": []
}

Passing conditionalFormats as an array [] instead of {card:[], datasource:[]} causes HTTP 400. The Domo UI returns it as an array when reading — convert to object before writing.

7. Gotchas

Critical — Will Cause Failures

Important — Affects Behavior

Quick Reference

CREATE:  cards create --body-file card.json --page-id PAGE_ID
READ:    cards definition CARD_ID
UPDATE:  cards update CARD_ID --body-file card.json
COPY:    POST /content/v1/cards/CARD_ID/copy  (raw API)
DELETE:  DELETE /content/v1/cards/CARD_ID      (raw API)

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

Line charts: badge_two_trendline (NOT badge_line)
Total types: 207 (206 work, badge_line fails)