---
title: "Delete an element."
method: DELETE
path: "/v1/dashboards/{id}/pages/{pageId}/elements/{elementId}"
tags: ["dashboards"]
---

# Delete an element.

`DELETE /v1/dashboards/{id}/pages/{pageId}/elements/{elementId}`

## Request

- Base URL: `http://localhost:8080`
- URL: `http://localhost:8080/v1/dashboards/{id}/pages/{pageId}/elements/{elementId}`
- Auth: one of:
  - API key in cookie `dvt_session`
  - HTTP bearer

Soft-deletes the element and removes it from the page's layout (versioning the
page). The element's revision history is retained; its slug becomes reusable.
The element's current version travels via the `version` query parameter or
`If-Match` header. Refused on legacy dashboards (409 legacy-dashboard).
Editor or above.

Provenance (DVT-1792): pass a required `reason` query parameter (or the
`X-Dvt-Change-Reason` header) explaining why the element is being removed — it is
propagated into the dashboard revision's change summary so the Versions tab shows why.

## Query parameters

- `version` integer
- `reason` string, required

## Response `204`

Deleted.

## Other responses

- `400`: Malformed request.
- `401`: Missing, invalid, or expired session.
- `403`: The caller's role does not permit this action.
- `404`: Resource does not exist.
- `409`: Stale version, legacy dashboard, an htmlSlots page (panels are positioned via `<dvt-slot ref>` in the layout HTML, not the coordinate grid), or the element is still referenced by a container tab or a filter-bar.

---

[API](https://skmtc.dev/dvt/apis/dvt-rest-api.md) · [All operations](https://skmtc.dev/dvt/apis/dvt-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/dvt/apis/dvt-rest-api/revisions/00016f504165?raw)