> ## Documentation Index > Fetch the complete documentation index at: https://trigger.dev/docs/llms.txt > Use this file to discover all available pages before exploring further. # Replace dashboard widgets > Replace every widget on a custom dashboard, and optionally its title and description. A widget that already exists keeps its position unless you pass a new one; new widgets without a position are stacked full width below the others, in order. ## OpenAPI ````yaml v3-openapi PUT /api/v1/query/dashboards/{dashboardId} openapi: 3.1.0 info: title: Trigger.dev v3 REST API description: >- The REST API lets you trigger and manage runs on Trigger.dev. You can trigger a run, get the status of a run, and get the results of a run. version: 2024-04 license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html servers: - url: https://api.trigger.dev description: Trigger.dev API security: [] paths: /api/v1/query/dashboards/{dashboardId}: parameters: - name: dashboardId in: path required: true description: The custom dashboard id, starting with `dashboard_` schema: type: string put: tags: - query summary: Replace a dashboard's widgets description: >- Replace every widget on a custom dashboard, and optionally its title and description. A widget that already exists keeps its position unless you pass a new one; new widgets without a position are stacked full width below the others, in order. operationId: replace_dashboard_v1 requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: - widgets properties: title: type: string maxLength: 200 description: type: string maxLength: 2000 widgets: type: array items: $ref: '#/components/schemas/DashboardWidgetInput' revision: $ref: '#/components/schemas/DashboardRevision' responses: '200': description: The updated dashboard content: application/json: schema: $ref: '#/components/schemas/DashboardObject' '400': description: >- Invalid request, for example an invalid widget query or a duplicate widget id '403': description: The widget limit for your plan was reached '404': description: Dashboard not found '409': description: The dashboard changed since `revision` was read security: - secretKey: [] x-codeSamples: - lang: typescript source: |- import { query } from "@trigger.dev/sdk"; const current = await query.dashboards.retrieve("dashboard_1234"); await query.dashboards.replace("dashboard_1234", { widgets: [ { title: "Runs by status", query: "SELECT status, count() AS runs FROM runs GROUP BY status", display: { type: "table" }, }, ], revision: current.revision, }); components: schemas: DashboardWidgetInput: type: object required: - title - display properties: id: type: string description: >- Omit to generate one. Letters, numbers, `_` and `-`, unique within the dashboard. title: type: string maxLength: 200 query: type: string description: A TRQL query. Required unless the display type is `title`. display: $ref: '#/components/schemas/DashboardWidgetDisplay' fillGaps: type: boolean description: >- Fill empty time buckets, carrying gauges forward and zero-filling counters. position: $ref: '#/components/schemas/DashboardWidgetPosition' DashboardRevision: type: string description: >- The `revision` from the dashboard you last read. Send it to reject the write with a 409 if someone else changed the dashboard in the meantime. DashboardObject: type: object properties: id: type: string description: The dashboard id, starting with `dashboard_` title: type: string description: type: string revision: $ref: '#/components/schemas/DashboardRevision' createdAt: type: string format: date-time updatedAt: type: string format: date-time widgets: type: array description: Widgets in grid order, top to bottom then left to right. items: type: object properties: id: type: string title: type: string query: type: string display: $ref: '#/components/schemas/DashboardWidgetDisplay' fillGaps: type: boolean position: $ref: '#/components/schemas/DashboardWidgetPosition' DashboardWidgetDisplay: description: How the widget renders its query results. oneOf: - type: object title: Table required: - type properties: type: type: string enum: - table prettyFormatting: type: boolean default: true sorting: type: array items: type: object properties: id: type: string desc: type: boolean - type: object title: Chart required: - type - chartType - xAxisColumn - yAxisColumns - groupByColumn - stacked - sortByColumn - sortDirection - aggregation properties: type: type: string enum: - chart chartType: type: string enum: - bar - line xAxisColumn: type: string nullable: true yAxisColumns: type: array items: type: string groupByColumn: type: string nullable: true stacked: type: boolean sortByColumn: type: string nullable: true sortDirection: type: string enum: - asc - desc aggregation: type: string enum: - sum - avg - count - min - max seriesColors: type: object additionalProperties: type: string - type: object title: Big number required: - type - column - aggregation properties: type: type: string enum: - bignumber column: type: string aggregation: type: string enum: - sum - avg - count - min - max - first - last sortDirection: type: string enum: - asc - desc abbreviate: type: boolean default: false prefix: type: string suffix: type: string - type: object title: Section title required: - type properties: type: type: string enum: - title DashboardWidgetPosition: type: object description: A position on the dashboard's 12-column grid. required: - x - 'y' - w - h properties: x: type: integer minimum: 0 maximum: 11 'y': type: integer minimum: 0 w: type: integer minimum: 1 maximum: 12 h: type: integer minimum: 1 securitySchemes: secretKey: type: http scheme: bearer description: > Use a named environment API key. It starts with `tr_dev_sk_`, `tr_prod_sk_`, `tr_stg_sk_`, etc. Create a named API key in the API Keys section of your Trigger.dev project dashboard. Choose the narrowest access preset that supports your integration. Our TypeScript SDK will default to using the value of the `TRIGGER_SECRET_KEY` environment variable if it is set. If you are using the SDK in a different environment, you can set the key using the `configure` function. ```typescript import { configure } from "@trigger.dev/sdk"; configure({ accessToken: "tr_dev_sk_1234" }); ``` ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.