---
title: "Compile a dashboard YAML file"
method: POST
path: "/api/v1/compiler/dashboard"
tags: ["compiler"]
---

# Compile a dashboard YAML file

`POST /api/v1/compiler/dashboard`

Compile a dashboard YAML file into fully resolved widget data.

Reads a dashboard YAML from the client repo, resolves all data slots,
executes queries, applies filters, and returns renderable widget data.

RLS: Filtered to current client (ClientRLSDB).

## Query parameters

- `source` string, nullable

## Headers

- `X-Kater-CLI-ID` string, nullable

## Request body

- DashboardCompileRequest — Request to compile a dashboard YAML file.
  - `connection_id` string, uuid, required — Connection to compile against
  - `dashboard_path` string, required — Relative path within the connection (e.g. 'dashboards/compliance_overview')
  - `filters` object, nullable — Optional filter overrides from UI
  - `tenant_key` string, required — Tenant key for multi-tenant execution. Use 'kater_global_tenant' for no-tenancy clients.

## Response `200`

Successful Response

- DashboardCompileResponse — Response from dashboard compilation — fully resolved dashboard.
  - `context` DashboardContextResponse, required — Dashboard context passed to every widget for narrative generation.
    - `filters` object, nullable — Active filter values: {name: {value, label}}
    - `timeframe` object, nullable — Active timeframe: {label, start, end}
    - `topic` object, nullable — Dashboard topic: {label, time_dimension}
  - `dashboard` DashboardMetadataResponse, required — Dashboard metadata.
    - `description` string, nullable — Dashboard description
    - `kater_id` string, nullable — Dashboard kater_id
    - `label` string, nullable — Dashboard display label
    - `name` string, required — Dashboard name
    - `topic` string, nullable — Dashboard topic reference
  - `errors` CompilerErrorItem[] — Dashboard-level compilation errors
    - `code` string, required — Machine-readable error code
    - `column` integer, nullable — Column number in the source file
    - `file` string, nullable — Source file path where the error occurred
    - `line` integer, nullable — Line number in the source file
    - `message` string, required — Human-readable error description
    - `ref` string, nullable — Reference to the source element (e.g. view or query name)
    - `remediation` string, nullable — Suggested fix for this error
  - `filters` ResolvedFilterResponse[] — Resolved filter definitions with current values
    - `allow_null` boolean — Whether null (All) is allowed
    - `auto_apply` boolean — Whether filter auto-applies to queries
    - `current_value` union — Current filter value
      - string
      - string[]
    - `default` object, nullable — Default value specification
    - `field` string, nullable — Field reference for data-driven filters
    - `filter_type` string, required — Filter type: date_range, multi_select, select
    - `name` string, required — Filter name
    - `null_label` string, nullable — Label for null/All option
    - `presets` object[], nullable — Available presets
  - `widgets` ResolvedWidgetResponse[] — Fully resolved widgets with data + config
    - `column_map` union, required — Column metadata (single or multi-query)
      - ColumnMapEntryResponse[]
        - `aggregation` string, nullable — Aggregation type for measures: sum, count, min, max, avg, unknown. None for non-measures.
        - `field_type` string, required — Field type: dimension, measure, or calculation
        - `kater_id` string, required — UUID string used as SQL column alias
        - `label` string, nullable — Display label
        - `name` string, required — Human-readable column name
      - array[]
        - ColumnMapEntryResponse[]
          - `aggregation` string, nullable — Aggregation type for measures: sum, count, min, max, avg, unknown. None for non-measures.
          - `field_type` string, required — Field type: dimension, measure, or calculation
          - `kater_id` string, required — UUID string used as SQL column alias
          - `label` string, nullable — Display label
          - `name` string, required — Human-readable column name
    - `config` object, required — Fully resolved WidgetConfig
    - `data` union, required — Query result data (single or multi-query)
      - object[]
      - array[]
        - object[]
    - `display_mode` string, nullable — Display mode for multi-query: 'tabs' or 'grid'
    - `errors` CompilerErrorItem[] — Per-widget compilation errors
      - `code` string, required — Machine-readable error code
      - `column` integer, nullable — Column number in the source file
      - `file` string, nullable — Source file path where the error occurred
      - `line` integer, nullable — Line number in the source file
      - `message` string, required — Human-readable error description
      - `ref` string, nullable — Reference to the source element (e.g. view or query name)
      - `remediation` string, nullable — Suggested fix for this error
    - `grid` GridPositionResponse, required — Grid position for a widget.
      - `h` integer
      - `w` integer
      - `x` integer
      - `y` integer
    - `kater_id` string, required — Widget unique identifier
    - `name` string, required — Widget name
    - `slot_configs` object[], nullable — Per-slot configs for multi-query containers
    - `widget_type` string, nullable — Resolved widget type

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `422` — Validation Error
- `500` — Internal Server Error

## Changes

- **2026-03-05** `6a140b82e07c` — 2 breaking
  - the request property `tenant_key` became required
  - request property `tenant_key` list-of-types was narrowed by removing types `null` from media type `application/json`
- **2026-02-26** `bef1f3e205dd` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/kater-ai/apis/kater-api/changes/api/v1/compiler/dashboard/post.md)

---

[API](https://skmtc.dev/kater-ai/apis/kater-api.md) · [All operations](https://skmtc.dev/kater-ai/apis/kater-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/kater-ai/kater-api/revisions/6a140b82e07c/schema)