Chart Blocks

Use a chart block when the template slide contains a bar or column chart region and your request needs to provide chart data. The template supplies placement and default styling. The payload supplies categories, series, chart type, and optional formatting overrides.

Basic Shape

Inside slide_data.content.blocks, a chart block looks like this:

{
  "type": "chart",
  "chart": {
    "chart_type": "stacked_column",
    "categories": ["Q2", "Q3", "Q4"],
    "series": [
      { "name": "Committed", "values": [18.2, 21.4, 24.1] },
      { "name": "Upside", "values": [4.5, 3.9, 5.2] }
    ]
  }
}

Each series must have one value per category.

Supported Chart Types

Chart blocks support bar and column charts only.

Type	Use when
`clustered_column`	Compare series side by side with vertical columns
`stacked_column`	Show stacked contribution by category with vertical columns
`percent_stacked_column`	Show each category as 100% with vertical columns
`clustered_bar`	Compare series side by side with horizontal bars
`stacked_bar`	Show stacked contribution by category with horizontal bars
`percent_stacked_bar`	Show each category as 100% with horizontal bars

If you omit chart_type, generation preserves the template chart type where supported. Pie, line, area, scatter, combo, and other arbitrary PowerPoint chart types are not part of the supported chart block API.

Categories and Series

categories defines the labels along the category axis. For column charts, categories appear on the X-axis. For bar charts, categories appear on the Y-axis. series defines the plotted values. Each series has a name, a values array, and an optional color.

{
  "categories": ["Q2", "Q3", "Q4"],
  "series": [
    { "name": "Committed", "values": [18.2, 21.4, 24.1], "color": "#0F766E" },
    { "name": "Upside", "values": [4.5, 3.9, 5.2], "color": "#2563EB" },
    { "name": "At risk", "values": [2.1, 3.4, 2.8], "color": "#DC2626" }
  ]
}

If a series color is omitted, the renderer uses the template or default chart colors.

Titles, Legends, and Axes

Chart blocks can specify the chart title, legend, value axis, and category axis.

{
  "title": "Renewal Outlook by Cohort",
  "title_format": {
    "font_size": 14,
    "bold": true,
    "color": "#111827"
  },
  "legend": {
    "show": true,
    "position": "bottom",
    "text_format": { "font_size": 8 }
  },
  "value_axis": {
    "title": "ARR",
    "number_format": "#,##0",
    "label_format": { "font_size": 8 }
  },
  "value_axis_unit": "$M",
  "category_axis": {
    "title": "Fiscal quarter",
    "label_rotation": -45,
    "label_format": { "font_size": 8 }
  }
}

Legend positions are bottom, left, right, top, and top_right. Axis fields include visible, title, title_format, label_format, label_rotation, wrap_labels, wrap_max_chars, number_format, min_value, and max_value. Both axes accept a title; the wrap fields apply to the category axis only.

Wrapped Category Labels

Set wrap_labels: true on category_axis to break long category labels across lines at word boundaries instead of rotating them.

{
  "category_axis": { "wrap_labels": true }
}

The line width comes from the category slot width for column charts, or from a capped label band left of the plot for bar charts. If a column-chart label cannot fit the automatic line budget, generation falls back to rotated labels. wrap_max_chars caps the characters per line explicitly. It implies wrap_labels and is always honored, with no rotation fallback:

{
  "category_axis": { "wrap_max_chars": 10 }
}

Breaks fall at word boundaries; a single word longer than the limit stays whole. Labels that already contain \n keep their breaks as written. Neither option can be combined with a non-zero label_rotation — wrapped labels stay horizontal.

Bar Labels

Set show_bar_labels: true to add auto-calculated labels to stacked bars or columns. Labels are calculated from the chart series values; bar_label_mode controls what they show.

{
  "chart_type": "stacked_column",
  "show_bar_labels": true,
  "bar_label_mode": "percent",
  "bar_label_decimals": 0
}

bar_label_mode: "total" (default) labels each bar with the sum of its series values.
bar_label_mode: "percent" labels each bar with that sum as a share of the grand total across all bars: bars totaling 50/30/20 are labeled 50%, 30%, 20%. Percent mode expects raw counts — values already normalized per bar (every bar summing to 100) give every bar the same share.
bar_label_decimals (0–4) fixes the decimal places in either mode. If unset, whole values are shown as integers and fractional values with one decimal.

Bar labels apply to stacked_column, stacked_bar, percent_stacked_column, and percent_stacked_bar.

Data Rows

Use data_rows to add a small data table beneath the chart. These values are part of the input payload; the API positions and formats the rows, but it does not derive values like n= or NPS from the chart series.

{
  "data_rows": [
    ["Total ARR", "$24.8M", "$28.7M", "$32.1M"],
    ["At-risk %", "8%", "12%", "9%"]
  ],
  "data_table_header_column": true,
  "data_table_format": {
    "font_name": "Arial",
    "font_size": 8,
    "color": "#333333"
  }
}

Providing data_rows automatically enables the chart data table. If data_table_header_column is true, the first value in each row is treated as a row label.

Complete Example

Chart block request example

{
  "title": "Customer NPS Scores by Company",
  "footnote": "Source: Q4 2024 Customer Satisfaction Survey",
  "content": {
    "blocks": [
      {
        "type": "chart",
        "chart": {
          "chart_type": "percent_stacked_column",
          "categories": [
            "Acme Corp",
            "TechFlow Inc",
            "DataSync Ltd",
            "CloudFirst",
            "Innovate Labs",
            "SecureNet",
            "GrowthMetrics",
            "Nexus Digital"
          ],
          "series": [
            {
              "name": "Promoters (9-10)",
              "values": [
                45,
                38,
                12,
                28,
                52,
                31,
                8,
                42
              ]
            },
            {
              "name": "Passives (7-8)",
              "values": [
                32,
                35,
                25,
                38,
                28,
                42,
                22,
                33
              ]
            },
            {
              "name": "Detractors (0-6)",
              "values": [
                23,
                27,
                63,
                34,
                20,
                27,
                70,
                25
              ]
            }
          ],
          "legend": {
            "position": "top"
          },
          "show_bar_labels": true,
          "data_rows": [
            [
              "n=",
              "156",
              "142",
              "89",
              "178",
              "201",
              "134",
              "67",
              "188"
            ],
            [
              "NPS",
              "+22",
              "+11",
              "-51",
              "-6",
              "+32",
              "+4",
              "-62",
              "+17"
            ]
          ],
          "data_table_header_column": true,
          "data_table_format": {
            "font_name": "Arial",
            "color": "#000000",
            "bold": false,
            "italic": false,
            "underline": false
          }
        }
      },
      {
        "type": "text",
        "text": {
          "text": "Question: What is driving the significant detractor rates at DataSync Ltd and GrowthMetrics?"
        }
      }
    ]
  }
}

The visual example below is generated from the complete payload above. It shows the API-added total labels above each stacked column and the aligned data rows beneath the chart.

Template slide with a placeholder chart before chart data is generated. — Template chart slide

Generated stacked column chart with total labels above each column and data rows aligned beneath the chart. — Generated chart slide

Updating Charts Later

Use chart blocks when you are generating a supported bar or column chart slide from a template. Use Chart Updates when a .pptx already exists and you only need to refresh the chart data. Chart updates are useful when:

New data arrives after the deck was generated
A user manually edited the deck in PowerPoint and you want to preserve those edits
You want to keep chart formatting, colors, legends, axes, bar labels, and data-row positioning while replacing the underlying numbers

For updates, send data fields such as categories, series, data_rows, and data_table_header_column. Omit styling fields such as chart_type, title, legend, and axes when you want the existing chart formatting preserved. Bar labels are recalculated from the new values in the chart’s existing mode — totals stay totals and percent labels stay percentages.

Presentation Generation

Generate one slide or a full deck.

Table Blocks

Author table rows and formatting.

Text Blocks

Author slide text and text sections.

Introduction

Template management

Generation

AI Agents

Security & Operations

Chart Blocks

Chart Blocks

Basic Shape

Supported Chart Types

Categories and Series

Titles, Legends, and Axes

Wrapped Category Labels

Bar Labels

Data Rows

Complete Example

Updating Charts Later

Presentation Generation

Table Blocks

Text Blocks

​Chart Blocks

​Basic Shape

​Supported Chart Types

​Categories and Series

​Titles, Legends, and Axes

​Wrapped Category Labels

​Bar Labels

​Data Rows

​Complete Example

​Updating Charts Later

​Related Guides

Presentation Generation

Table Blocks

Text Blocks

Chart Blocks

Basic Shape

Supported Chart Types

Categories and Series

Titles, Legends, and Axes

Wrapped Category Labels

Bar Labels

Data Rows

Complete Example

Updating Charts Later

Related Guides