---
title: "Generate a v3 dashboard"
method: POST
path: "/dashboards/v3/generate"
tags: ["Dashboard v3"]
---

# Generate a v3 dashboard

`POST /dashboards/v3/generate`

## Request

- Base URL: `https://app.mammoth.io/api/v2`
- URL: `https://app.mammoth.io/api/v2/dashboards/v3/generate`
- 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`

Create a new engine=v3 dashboard from an intent + one dataview (profile → one controls call → architect → plan/bake → data warm). Returns a job_id; per-stage progress streams on the draft WS channel. Gated on the dashboardsV3 workspace flag (the creation-engine selector — existing dashboards route by their own engine column).

## Query parameters

- `project_id` integer, nullable

## Request body

- GenerateDashboardV3Spec: v3 dashboard generation parameters
  - `params` GenerateDashboardV3Params, required
    - `intent` string: The creator's intent
    - `dataview_id` integer, required: The single dataview a v3 canvas binds (canvas.dataset)
    - `format` 'dashboard' | 'presentation' | 'document' | 'qa' | 'null', nullable: Output format for the seed canvas (canvas.style); absent defaults to 'dashboard'
    - `contexts` string[], nullable: Attached context ids (/v3/contexts) — persisted on the seed canvas (canvas.contexts) and the only contexts grounding this build; absent or empty, the build grounds on no contexts
    - `client_turn_id` string, nullable: The FE's per-turn token — stamped on both persisted messages of the seeded build turn so the client reconciles the create prompt by id, uniform with the edit path
    - `title` string: Name for the board when the caller already has a good one — a create started from a suggestion card passes the card's short authored title, which beats title-casing its intent sentence. Blank falls through to the derived name
    - `structure` string, nullable: The layout the create screen's idea card promised (its structure pill — 'motion', 'pitch_deck'). Pinned on the board when valid for the format; anything else is ignored
    - `design_from` integer, nullable: A board whose LOOK (style, colours, fonts, header, cover treatment) the generated board takes on — never its content. The poor-fit review's 'build one for your data, in this template's design'. Requires read access to that board.

## Response `201`

Document created, URL follows

- ObjectJobSchema
  - `status_code` integer, nullable
  - `job_id` integer, nullable: Created job id
  - `failure_reason` string, nullable: Failure reason if status is failure

## Other responses

- `202`: Successfully Submitted
- `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)