create_dashboard

Create or update a saved dashboard for a Bridge Town model. Two modes, selected by source_kind (default ‘model_run_output’): source_kind=‘model_run_output’ (default): generates chart HTML from a completed model run output, stores it in S3, and persists a Dashboard record. Requires chart_type, model_run_id, and output_key. output_key selects a key from the run’s outputs dict — the same dict your model writes to /outputs/.

Parameters

Name	Type	Required	Default	Description
model_name	Annotated[str, Field(description='Name of the Bridge Town model.')]	Yes	—
dashboard_name	Annotated[str, Field(description='Unique name for this dashboard within the model.')]	Yes	—
chart_type	Annotated[str, Field(description="Type of chart to render — see this tool's description, or the bridge-town://dashboards/chart-types resource, for all available types and their required data schemas. Required when source_kind='model_run_output'; ignored otherwise.")]	No	''
model_run_id	Annotated[str, Field(description="UUID of the successful model run whose output to render. Required when source_kind='model_run_output'; ignored otherwise.")]	No	''
output_key	Annotated[str, Field(description="Key in the model run's outputs dict to visualize (e.g. 'revenue_forecast'). Required when source_kind='model_run_output'; ignored otherwise.")]	No	''
description	`Annotated[str	None, Field(description=‘Optional description displayed below the dashboard title.’)]`	No	None
subtitle	Annotated[str, Field(description='Optional subtitle displayed below the dashboard title.')]	No	''
currency	Annotated[str, Field(description="Optional ISO 4217 currency code for formatting values (e.g. 'USD', 'EUR'). For data_grid dashboards, applies to columns explicitly typed as 'currency'; plain 'number' columns are not currency-formatted.")]	No	'USD'
source_kind	Annotated[Literal['model_run_output', 'repo_file'], Field(description="'model_run_output' (default) renders chart_type/model_run_id/output_key. 'repo_file' registers a repo-authored standalone HTML dashboard (path) as a new versioned package revision.")]	No	'model_run_output'
path	`Annotated[str	None, Field(description=“source_kind=‘repo_file’ only: repo path to the HTML entrypoint (e.g. ‘dashboards/gross-margin/index.html’).”)]`	No	None
branch	`Annotated[str	None, Field(description=“source_kind=‘repo_file’ only: branch to read path/manifest_path/data_paths from. Defaults to the model’s default branch when omitted or null.”)]`	No	None
manifest_path	`Annotated[str	None, Field(description=“source_kind=‘repo_file’ only: optional repo path to a JSON manifest merged into the stored package manifest (source_refs and design_skill_id are always tool-controlled and override any value in this file).”)]`	No	None
data_paths	`Annotated[list[str]	None, Field(description=“source_kind=‘repo_file’ only: optional repo paths to related data-snapshot files, recorded as provenance and embedded in the stored data-snapshot (parsed as JSON when possible, otherwise embedded as raw text).”)]`	No	None
design_skill_id	`Annotated[str	None, Field(description=“source_kind=‘repo_file’ only: UUID of a Skill containing dashboard design standards to honor. Must be public or owned by the caller. Its body is snapshotted into the manifest as design_guidance for reproducibility.”)]`	No	None
publish	Annotated[bool, Field(description="source_kind='repo_file' only: publish this revision immediately (default false saves it as an unpublished draft revision). Cannot be combined with dry_run=true.")]	No	False
dry_run	Annotated[bool, Field(description="source_kind='repo_file' only: preflight the same validation pipeline as publish with no writes (see tool description for the sandbox policy). Unlike publish, a blocking finding is returned as validation_status='failed' rather than raised. Not supported for source_kind='model_run_output'.")]	No	False
workspace_id	`Annotated[str	None, Field(description=WORKSPACE_ID_FIELD_DESCRIPTION)]`	No	None

Returns

Returns a structured object. Top-level fields:

• dashboard_id (string)
• dashboard_name (string)
• model (string)
• chart_type (string)
• model_run_id (string)
• has_html (boolean)
• created (boolean)
• created_at (string)
• updated_at (string)

See the response example below for the full payload shape.

Example

Tool Call

{
  "name": "create_dashboard",
  "arguments": {
    "model_name": "forecasts",
    "dashboard_name": "Q4 Revenue",
    "chart_type": "bar",
    "model_run_id": "66666666-6666-6666-6666-666666666666",
    "output_key": "quarterly_revenue.json",
    "description": "Quarterly revenue breakdown",
    "subtitle": "FY2026",
    "currency": "USD"
  }
}

Response

{
  "dashboard_id": "77777777-7777-7777-7777-777777777777",
  "dashboard_name": "Q4 Revenue",
  "model": "forecasts",
  "chart_type": "bar",
  "model_run_id": "66666666-6666-6666-6666-666666666666",
  "has_html": true,
  "created": true,
  "created_at": "2026-04-28T10:00:00+00:00",
  "updated_at": "2026-04-28T10:00:00+00:00"
}

Notes

• Module: Dashboards
• Requires authentication via API token or Auth0 JWT.