---
title: "Append one authored figure (no LLM turn, no canvas round trip)"
method: POST
path: "/dashboards/{dashboard_id}/figures"
tags: ["Dashboard v3"]
---

# Append one authored figure (no LLM turn, no canvas round trip)

`POST /dashboards/{dashboard_id}/figures`

## Request

- Base URL: `https://app.mammoth.io/api/v2`
- URL: `https://app.mammoth.io/api/v2/dashboards/{dashboard_id}/figures`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-KEY` and API key in header `X-API-SECRET` and API key in header `X-WORKSPACE-ID`

Lands one figure built outside the board — an explore card — on a content page: an existing page by id, a new page by title, or (page omitted) the board's first content page, else a new 'From Explore' page. The figure is validated against the board's source and profile BEFORE anything is written, then appended against the CURRENT head with a server-side retry, so a concurrent editor save never fails it. Kicks the async bake, like the canvas save. 403 not an editor; 409 4DASH023 another source; 404 4DASH022 no such page; 400 4GENR001 an invalid figure / page; 409 4DASH005 when the head kept moving through every retry.

## Path parameters

- `dashboard_id` integer, required

## Request body

- AppendFigureSpec: Append-one-figure parameters
  - `params` AppendFigureParams, required
    - `dataview_id` integer, required: The figure's source; must be the board's own dataview
    - `figure` object, required: An AddedFigure without its id (the server mints it)
    - `banded` object, nullable: Optional BandedDimension without its id: the server mints the id (or reuses an identical entry) and points figure.dim at it
    - `page` FigurePageTarget
      - `id` string, nullable: An existing content page id
      - `new_title` string, nullable: Create a page with this title
    - `base_sequence` integer, nullable: Informative only: the head the client last saw. The add always composes onto the current head and never 409s on a moved one.
    - `on_duplicate` 'add' | 'refuse' | 'replace': When the board already draws the same data (measure, agg, dimension, date bucket, filters): add another (default), refuse with 409 4DASH024 naming it, or replace it in place

## Response `202`

Figure appended; bake running asynchronously

- AppendFigureResponse
  - `sequence` integer, required: The new draft head sequence
  - `bake_job_id` integer, required: Job id of the async bake
  - `page_id` string, required: The page the figure landed on
  - `figure_id` string, required: The minted tile id (t-…)
  - `layout_key` string, required: The tile's layout key, add:<figure_id>
  - `page_title` string, nullable: The landed page's title (None for an untitled page)

## Other responses

- `400`: Bad request syntax or unsupported method
- `403`: Request forbidden -- authorization will not help

---

[API](https://skmtc.dev/mammoth/apis/mammoth-analytics.md) · [All operations](https://skmtc.dev/mammoth/apis/mammoth-analytics/llms.txt) · [OpenAPI document](https://skmtc.dev/mammoth/apis/mammoth-analytics/revisions/fe078afe239b?raw)