@@ -0,0 +1,22 @@
+---
+"@trigger.dev/sdk": patch
+"@trigger.dev/core": patch
+"trigger.dev": patch
+---
+
+Manage custom metric dashboards from code. `query.dashboards` lists, creates, updates and deletes custom dashboards and their widgets, and every widget query is checked when it is saved. The MCP server adds `create_dashboard` and `set_dashboard_widgets`, so your AI assistant can build a dashboard for you.
+
+```ts
+import { query } from "@trigger.dev/sdk";
+
+await query.dashboards.create({
+  title: "Email tasks",
+  widgets: [
+    {
+      title: "Total runs",
+      query: "SELECT count() AS total FROM runs",
+      display: { type: "bignumber", column: "total", aggregation: "sum" },
+    },
+  ],
+});
+```
@@ -2,12 +2,19 @@ import { DocumentDuplicateIcon, PencilSquareIcon, TrashIcon } from "@heroicons/r
 import { ClipboardIcon } from "@heroicons/react/24/outline";
 import { ChartBarIcon } from "@heroicons/react/24/solid";
 import { type OutputColumnMetadata } from "@internal/tsql";
+import {
+  DashboardWidgetDisplay,
+  type DashboardBigNumberAggregation,
+  type DashboardBigNumberConfig,
+  type DashboardChartAggregation,
+  type DashboardChartConfig,
+  type DashboardSortDirection,
+} from "@trigger.dev/core/v3/schemas";
 import { DialogClose } from "@radix-ui/react-dialog";
 import { IconBraces, IconChartHistogram, IconFileTypeCsv } from "@tabler/icons-react";
 import { assertNever } from "assert-never";
 import { Maximize2 } from "lucide-react";
 import { useCallback, useRef, useState, type ReactNode } from "react";
-import { z } from "zod";
 import { Card } from "~/components/primitives/charts/Card";
 import { ShortcutKey } from "~/components/primitives/ShortcutKey";
 import { SimpleTooltip } from "~/components/primitives/Tooltip";
@@ -31,88 +38,13 @@ import {
   PopoverVerticalEllipseTrigger,
 } from "../primitives/Popover";
 
-const ChartType = z.union([z.literal("bar"), z.literal("line")]);
-type ChartType = z.infer<typeof ChartType>;
-
-const SortDirection = z.union([z.literal("asc"), z.literal("desc")]);
-export type SortDirection = z.infer<typeof SortDirection>;
-
-const AggregationType = z.union([
-  z.literal("sum"),
-  z.literal("avg"),
-  z.literal("count"),
-  z.literal("min"),
-  z.literal("max"),
-]);
-export type AggregationType = z.infer<typeof AggregationType>;
-
-const chartConfigOptions = {
-  chartType: ChartType,
-  xAxisColumn: z.string().nullable(),
-  yAxisColumns: z.string().array(),
-  groupByColumn: z.string().nullable(),
-  stacked: z.boolean(),
-  sortByColumn: z.string().nullable(),
-  sortDirection: SortDirection,
-  aggregation: AggregationType,
-  seriesColors: z.record(z.string(), z.string()).optional(),
-};
-
-const ChartConfiguration = z.object({ ...chartConfigOptions });
-export type ChartConfiguration = z.infer<typeof ChartConfiguration>;
-
-const BigNumberAggregationType = z.union([
-  z.literal("sum"),
-  z.literal("avg"),
-  z.literal("count"),
-  z.literal("min"),
-  z.literal("max"),
-  z.literal("first"),
-  z.literal("last"),
-]);
-export type BigNumberAggregationType = z.infer<typeof BigNumberAggregationType>;
-
-const BigNumberSortDirection = z.union([z.literal("asc"), z.literal("desc")]);
-
-const bigNumberConfigOptions = {
-  column: z.string(),
-  aggregation: BigNumberAggregationType,
-  sortDirection: BigNumberSortDirection.optional(),
-  abbreviate: z.boolean().default(false),
-  prefix: z.string().optional(),
-  suffix: z.string().optional(),
-};
-
-const BigNumberConfiguration = z.object({ ...bigNumberConfigOptions });
-export type BigNumberConfiguration = z.infer<typeof BigNumberConfiguration>;
-
-export const QueryWidgetConfig = z.discriminatedUnion("type", [
-  z.object({
-    type: z.literal("table"),
-    prettyFormatting: z.boolean().default(true),
-    sorting: z
-      .array(
-        z.object({
-          desc: z.boolean(),
-          id: z.string(),
-        })
-      )
-      .default([]),
-  }),
-  z.object({
-    type: z.literal("chart"),
-    ...chartConfigOptions,
-  }),
-  z.object({
-    type: z.literal("bignumber"),
-    ...bigNumberConfigOptions,
-  }),
-  z.object({
-    type: z.literal("title"),
-  }),
-]);
-
-export type QueryWidgetConfig = z.infer<typeof QueryWidgetConfig>;
+export const QueryWidgetConfig = DashboardWidgetDisplay;
+export type QueryWidgetConfig = DashboardWidgetDisplay;
+export type SortDirection = DashboardSortDirection;
+export type AggregationType = DashboardChartAggregation;
+export type ChartConfiguration = DashboardChartConfig;
+export type BigNumberAggregationType = DashboardBigNumberAggregation;
+export type BigNumberConfiguration = DashboardBigNumberConfig;
 
 /** Result data containing rows and column metadata */
 export type QueryWidgetData = {
 
@@ -1,42 +1,21 @@
 import { BasePresenter } from "./basePresenter.server";
 import { getLimit } from "~/services/platform.v3.server";
-import { z } from "zod";
 import { fromZodError } from "zod-validation-error";
 import { builtInDashboard } from "./BuiltInDashboards.server";
-import { QueryWidgetConfig } from "~/components/metrics/QueryWidget";
+import {
+  DashboardDefinition,
+  DashboardLayoutItem,
+  DashboardStoredWidget,
+} from "@trigger.dev/core/v3/schemas";
 
-export const LayoutItem = z.object({
-  i: z.string(),
-  x: z.number(),
-  y: z.number(),
-  w: z.number(),
-  h: z.number(),
-  minH: z.number().optional(),
-  maxH: z.number().optional(),
-});
+export const LayoutItem = DashboardLayoutItem;
+export type LayoutItem = DashboardLayoutItem;
 
-export type LayoutItem = z.infer<typeof LayoutItem>;
+export const Widget = DashboardStoredWidget;
+export type Widget = DashboardStoredWidget;
 
-export const Widget = z.object({
-  title: z.string(),
-  query: z.string().default(""),
-  display: QueryWidgetConfig,
-  // Opt into server-side gap fill (carry-forward for gauges, zero-fill for counters).
-  // Top-level rather than in `display` because display config is client-only and never reaches the query POST.
-  fillGaps: z.boolean().optional(),
-});
-
-export type Widget = z.infer<typeof Widget>;
-
-export const DashboardLayout = z.discriminatedUnion("version", [
-  z.object({
-    version: z.literal("1"),
-    layout: z.array(LayoutItem),
-    widgets: z.record(z.string(), Widget),
-  }),
-]);
-
-export type DashboardLayout = z.infer<typeof DashboardLayout>;
+export const DashboardLayout = DashboardDefinition;
+export type DashboardLayout = DashboardDefinition;
 
 export type CustomDashboard = {
   friendlyId: string;
 
@@ -36,7 +36,6 @@ import { Sheet, SheetContent } from "~/components/primitives/SheetV3";
 import { useToast } from "~/components/primitives/Toast";
 import { SimpleTooltip } from "~/components/primitives/Tooltip";
 import { QueryEditor, type QueryEditorSaveData } from "~/components/query/QueryEditor";
-import { prisma } from "~/db.server";
 import { env } from "~/env.server";
 import { useDashboardEditor } from "~/hooks/useDashboardEditor";
 import { useEnvironment } from "~/hooks/useEnvironment";
@@ -49,6 +48,9 @@ import { getTaskIdentifiers } from "~/models/task.server";
 import { MetricDashboardPresenter } from "~/presenters/v3/MetricDashboardPresenter.server";
 import { QueryPresenter } from "~/presenters/v3/QueryPresenter.server";
 import { removeFavoritesByUrlSubstring } from "~/services/dashboardPreferences.server";
+import { ServiceValidationError } from "~/v3/services/common.server";
+import { MetricDashboardService } from "~/v3/services/metricDashboard.server";
+import { tryCatch } from "@trigger.dev/core/utils";
 import { hasAdminDisplayAccess, requireUser } from "~/services/session.server";
 import {
   EnvironmentParamSchema,
@@ -132,26 +134,23 @@ export const action = async ({ request, params }: ActionFunctionArgs) => {
     throw new Response("Project not found", { status: 404 });
   }
 
-  // Load the dashboard
-  const dashboard = await prisma.metricsDashboard.findFirst({
-    where: {
-      friendlyId: dashboardId,
-      organizationId: project.organizationId,
-    },
-  });
+  const service = new MetricDashboardService();
+  const ref = { organizationId: project.organizationId, friendlyId: dashboardId };
 
-  if (!dashboard) {
-    throw new Response("Dashboard not found", { status: 404 });
+  const [lookupError, dashboard] = await tryCatch(service.get(ref));
+  if (lookupError) {
+    if (lookupError instanceof ServiceValidationError) {
+      throw new Response(lookupError.message, { status: lookupError.status ?? 400 });
+    }
+    throw lookupError;
   }
 
   const formData = await request.formData();
   const action = formData.get("action");
 
   switch (action) {
     case "delete": {
-      await prisma.metricsDashboard.delete({
-        where: { id: dashboard.id },
-      });
+      await service.delete(ref);
 
       // Drop any favorites pointing at this dashboard so the side menu doesn't keep a dead link
       await removeFavoritesByUrlSubstring({
@@ -176,10 +175,7 @@ export const action = async ({ request, params }: ActionFunctionArgs) => {
         throw new Response("Title is required", { status: 400 });
       }
 
-      await prisma.metricsDashboard.update({
-        where: { id: dashboard.id },
-        data: { title: newTitle.trim() },
-      });
+      await service.update({ ...ref, title: newTitle.trim() });
 
       return typedjson({ success: true });
     }
 
@@ -0,0 +1,124 @@
+import { json } from "@remix-run/server-runtime";
+import { tryCatch } from "@trigger.dev/core/utils";
+import {
+  ReplaceDashboardRequestBody,
+  UpdateDashboardRequestBody,
+} from "@trigger.dev/core/v3/schemas";
+import { z } from "zod";
+import {
+  createLoaderApiRoute,
+  createMultiMethodApiRoute,
+} from "~/services/routeBuilders/apiBuilder.server";
+import {
+  assertValidWidgetQueries,
+  dashboardApiErrorResponse,
+  MetricDashboardService,
+  toDashboardObject,
+} from "~/v3/services/metricDashboard.server";
+
+const ParamsSchema = z.object({
+  dashboardId: z.string(),
+});
+
+export const loader = createLoaderApiRoute(
+  {
+    params: ParamsSchema,
+    allowJWT: true,
+    corsStrategy: "all",
+    findResource: async () => 1,
+    authorization: {
+      action: "read",
+      resource: () => ({ type: "query", id: "dashboards" }),
+    },
+  },
+  async ({ params, authentication }) => {
+    const [error, dashboard] = await tryCatch(
+      new MetricDashboardService().get({
+        organizationId: authentication.environment.organizationId,
+        friendlyId: params.dashboardId,
+      })
+    );
+
+    if (error) {
+      return dashboardApiErrorResponse(error);
+    }
+
+    return json(toDashboardObject(dashboard));
+  }
+);
+
+const { action } = createMultiMethodApiRoute({
+  params: ParamsSchema,
+  allowJWT: true,
+  authorization: {
+    action: "write",
+    resource: () => ({ type: "query", id: "dashboards" }),
+  },
+  methods: {
+    PATCH: {
+      body: UpdateDashboardRequestBody,
+      handler: async ({ params, body, authentication }) => {
+        const input = body as z.infer<typeof UpdateDashboardRequestBody>;
+        const [error, dashboard] = await tryCatch(
+          new MetricDashboardService().update({
+            organizationId: authentication.environment.organizationId,
+            friendlyId: params.dashboardId,
+            title: input.title,
+            description: input.description,
+            revision: input.revision,
+          })
+        );
+
+        if (error) {
+          return dashboardApiErrorResponse(error);
+        }
+
+        return json(toDashboardObject(dashboard));
+      },
+    },
+    PUT: {
+      body: ReplaceDashboardRequestBody,
+      handler: async ({ params, body, authentication }) => {
+        const input = body as z.infer<typeof ReplaceDashboardRequestBody>;
+        const [error, dashboard] = await tryCatch(
+          (async () => {
+            assertValidWidgetQueries(input.widgets);
+
+            return new MetricDashboardService().replace({
+              organizationId: authentication.environment.organizationId,
+              friendlyId: params.dashboardId,
+              title: input.title,
+              description: input.description,
+              widgets: input.widgets,
+              revision: input.revision,
+            });
+          })()
+        );
+
+        if (error) {
+          return dashboardApiErrorResponse(error);
+        }
+
+        return json(toDashboardObject(dashboard));
+      },
+    },
+    DELETE: {
+      handler: async ({ params, authentication }) => {
+        const [error, dashboard] = await tryCatch(
+          new MetricDashboardService().delete({
+            organizationId: authentication.environment.organizationId,
+            friendlyId: params.dashboardId,
+          })
+        );
+
+        if (error) {
+          return dashboardApiErrorResponse(error);
+        }
+
+        return json({ id: dashboard.friendlyId });
+      },
+    },
+  },
+});
+
+export { action };