> For the complete documentation index, see [llms.txt](https://docs.groundcover.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/dashboards-api.md).

# Dashboards API

Create, query, update, archive, and manage native groundcover dashboards over HTTP.

Manage native groundcover dashboards, including catalog installations, revision history and batch actions. For the dashboard definition itself, see [Dashboard schema](https://docs.groundcover.com/investigate/dashboards-and-alerts/dashboard-schema.md).

## Authentication

Use an [API key](https://docs.groundcover.com/administer/api-keys.md) with the permissions described below. Include `Authorization: Bearer <YOUR_API_KEY>` and `X-Backend-Id: <YOUR_BACKEND_ID>` on every request; JSON bodies also require `Content-Type: application/json`. Self-hosted deployments use their own API URL.

The examples use these shell variables:

```bash
export GC_BASE_URL='https://api.groundcover.com'
export GC_API_KEY='<YOUR_API_KEY>'
export GC_BACKEND_ID='<YOUR_BACKEND_ID>'
```

Viewer permissions allow reads. Dashboard mutations require Editor permissions or higher by default; deployments can explicitly allow Viewers to edit dashboards.

## Create a dashboard

**POST** `/api/dashboards`

| Field           | Required | Description                                                                                                            |
| --------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- |
| `name`          | Yes      | Dashboard name.                                                                                                        |
| `preset`        | Yes      | Dashboard definition encoded as a **JSON string**, not an object.                                                      |
| `description`   | No       | Description.                                                                                                           |
| `team`          | No       | Team metadata.                                                                                                         |
| `tags`          | No       | Up to 20 tags after trimming whitespace and removing empty strings and exact duplicates. Case is preserved.            |
| `isProvisioned` | No       | Marks a dashboard as managed by Terraform/IaC. Defaults to `false`. This does not make it a managed catalog dashboard. |

This creates an empty dashboard that can be populated using the dashboard schema. `schemaVersion` describes the preset format; it is independent of the HTTP endpoint path:

```bash
curl --fail-with-body -sS -X POST "$GC_BASE_URL/api/dashboards" \
  -H "Authorization: Bearer $GC_API_KEY" \
  -H "X-Backend-Id: $GC_BACKEND_ID" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Service overview","description":"Production services","preset":"{\"schemaVersion\":7,\"widgets\":[],\"layout\":[],\"variables\":[]}","tags":["production"]}'
```

Returns **201 Created** with the dashboard object. Save its `uuid` and `revisionNumber`. Responses also include `name`, `viewType` (`explore`), `preset`, `status`, owner/timestamp metadata and optional description, team and tags.

## List and retrieve dashboards

**GET** `/api/dashboards` returns an array of dashboards with member-specific metadata. Optional query parameters:

* `status`: for example, `active` or `archived`.
* `source`: `regular`, `terraform` or `gc-catalog`.
* `query`: a gcQL **filter expression**, without pipes. Supported keys include `name`, `description`, `owner`, `tags`, `team`, `source`, `status` and `favorites`. Unkeyed terms search name, description, owner and tags. Top-level filters and `query` are combined with AND.

```bash
curl --fail-with-body -sS -G "$GC_BASE_URL/api/dashboards" \
  -H "Authorization: Bearer $GC_API_KEY" \
  -H "X-Backend-Id: $GC_BACKEND_ID" \
  --data-urlencode 'status=active' \
  --data-urlencode 'query=tags:production'
```

**POST** `/api/dashboards/list` provides paginated summaries. `name` and `description` are case-insensitive substring filters; `limit` defaults to 1000, `skip` defaults to 0, and `sort` is `name` (default) or `description`.

```bash
curl --fail-with-body -sS -X POST "$GC_BASE_URL/api/dashboards/list" \
  -H "Authorization: Bearer $GC_API_KEY" \
  -H "X-Backend-Id: $GC_BACKEND_ID" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Service","limit":50,"skip":0,"sort":"name"}'
```

The response is `{"dashboards":[...],"done":true}`. Increase `skip` by `limit` until `done` is true. Summary records do not contain the full preset.

**GET** `/api/dashboards/{id}` retrieves the full object; `?excludePreset=true` omits the preset.

```bash
export DASHBOARD_ID='<DASHBOARD_UUID>'
curl --fail-with-body -sS "$GC_BASE_URL/api/dashboards/$DASHBOARD_ID" \
  -H "Authorization: Bearer $GC_API_KEY" \
  -H "X-Backend-Id: $GC_BACKEND_ID" > dashboard.json
```

## Update safely

**PUT** `/api/dashboards/{id}` accepts the create fields plus `currentRevision` and `override`. Send the complete desired dashboard and the `revisionNumber` from the latest read as `currentRevision`. The following uses `jq` to retain the preset and optional fields:

```bash
jq '{name:"Updated service overview",description,preset,team,tags,isProvisioned,currentRevision:.revisionNumber}' dashboard.json > dashboard-update.json
curl --fail-with-body -sS -X PUT "$GC_BASE_URL/api/dashboards/$DASHBOARD_ID" \
  -H "Authorization: Bearer $GC_API_KEY" \
  -H "X-Backend-Id: $GC_BACKEND_ID" \
  -H 'Content-Type: application/json' \
  --data-binary @dashboard-update.json
```

Returns **202 Accepted** with the updated object. A stale revision returns **409 Conflict** with code `VIEW_REVISION_CONFLICT`; fetch the current object and reconcile edits before retrying. `override:true` bypasses this check and requires omitting `currentRevision`; reserve it for intentional replacement.

## Archive, restore and delete

* **POST** `/api/dashboards/{id}/archive?currentRevision={revision}` archives a dashboard.
* **POST** `/api/dashboards/{id}/restore?currentRevision={revision}` restores an archived dashboard.
* **DELETE** `/api/dashboards/{id}` permanently deletes the dashboard.

Read the latest revision before each archive or restore. Both return **202** with the updated object; deletion returns **200** with no body.

```bash
export DASHBOARD_REVISION='<CURRENT_REVISION_NUMBER>'
curl --fail-with-body -sS -X POST "$GC_BASE_URL/api/dashboards/$DASHBOARD_ID/archive?currentRevision=$DASHBOARD_REVISION" \
  -H "Authorization: Bearer $GC_API_KEY" \
  -H "X-Backend-Id: $GC_BACKEND_ID"
```

## Revision history

**POST** `/api/dashboards/{id}/revisions` takes a positive `limit` and optional `skip`:

```bash
curl --fail-with-body -sS -X POST "$GC_BASE_URL/api/dashboards/$DASHBOARD_ID/revisions" \
  -H "Authorization: Bearer $GC_API_KEY" \
  -H "X-Backend-Id: $GC_BACKEND_ID" \
  -H 'Content-Type: application/json' \
  -d '{"limit":20,"skip":0}'
```

Returns `{"revisions":[...],"hasNextPage":false}`. To recover an older definition, use that revision's preset in a PUT with the **current** revision number. The `/restore` action restores an archived dashboard, not a historical definition.

## Dashboard catalog

* **GET** `/api/dashboards/catalog` returns `packs` and `templates`, including `added` and, for installed templates, `installedDashboardId`. Optional `filter` accepts a gcQL filter expression.
* **GET** `/api/dashboards/catalog/{catalogId}` returns template metadata and its JSON-encoded `preset`.
* **POST** `/api/dashboards/catalog/{catalogId}` installs a managed dashboard. The body is optional; `name`, `description` and `team` can override installation metadata.

```bash
export CATALOG_ID='<CATALOG_ID_FROM_CATALOG_LIST>'
curl --fail-with-body -sS -X POST "$GC_BASE_URL/api/dashboards/catalog/$CATALOG_ID" \
  -H "Authorization: Bearer $GC_API_KEY" \
  -H "X-Backend-Id: $GC_BACKEND_ID" \
  -H 'Content-Type: application/json' \
  -d '{}'
```

Returns **201**. A duplicate installation returns **409**. Managed dashboards have `originType:"Catalog"` and `originId`; their preset follows the catalog. Editing, tagging or archiving them is rejected. Delete the installation to remove it. To customize one, read its resolved preset and create a separate regular dashboard. If a catalog template is no longer available, retrieving its resolved dashboard can return **410 Gone**.

## Batch operations

Each batch accepts 1–200 UUIDs in `dashboardUuids`:

* **POST** `/api/dashboards/batch/tags`: add/remove tags with `tagsToAdd` and `tagsToRemove`. At least one must be nonempty, and the two lists must not overlap.
* **POST** `/api/dashboards/batch/archive`: archive regular dashboards.
* **POST** `/api/dashboards/batch/delete`: delete archived dashboards; managed catalog installations may be deleted directly.

```bash
curl --fail-with-body -sS -X POST "$GC_BASE_URL/api/dashboards/batch/tags" \
  -H "Authorization: Bearer $GC_API_KEY" \
  -H "X-Backend-Id: $GC_BACKEND_ID" \
  -H 'Content-Type: application/json' \
  -d '{"dashboardUuids":["11111111-1111-4111-8111-111111111111"],"tagsToAdd":["production"],"tagsToRemove":["staging"]}'
```

Replace the illustrative UUID. A **200** response can contain partial failures: inspect `updatedCount`, `failedCount` and every entry in `errors` (`id`, `reason` and optional `code`).

## Discover filter values

**POST** `/api/dashboards/filters` accepts optional `query` and `required` (`owner`, `tags`, `source`, `favorites`). It returns a map of facet names to value/count arrays. Include `status:active` in `query` to restrict the set to active dashboards; the deprecated top-level `source` field is ignored.

```bash
curl --fail-with-body -sS -X POST "$GC_BASE_URL/api/dashboards/filters" \
  -H "Authorization: Bearer $GC_API_KEY" \
  -H "X-Backend-Id: $GC_BACKEND_ID" \
  -H 'Content-Type: application/json' \
  -d '{"query":"status:active","required":["tags","owner"]}'
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/dashboards-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
