> 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/saved-views-api.md).

# Saved Views API

Manage saved views and the calling identity’s favorites, defaults and pins.

[Saved views](https://docs.groundcover.com/investigate/saved-views.md) preserve page configuration. Use the dedicated [Dashboards API](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/dashboards-api.md) for dashboards. The view API also provides the current identity's favorites, defaults and pinned resources.

## 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>'
```

Saved views are shared within the workspace. Viewer permissions or higher let you read and use views created by others, and add them to your own favorites, defaults, and pins. Creating, updating, archiving, restoring, and deleting views requires Editor permissions or higher. Updating a view's definition additionally requires the calling identity to be its creator.

Preferences are scoped to the authenticated identity; a service-account API key does not change a human user's favorites or defaults.

## Get and list views

* **GET** `/api/views/{id}` returns one view. Set `excludePreset=true` to omit its preset.
* **GET** `/api/views?type={viewType}&status=active` lists views of a page type. `status` is optional.
* **POST** `/api/views/member` returns views with member-specific preference metadata. Required `type` selects the view type; optional fields are `filter`, `favoritesOnly` and `selfOwnedOnly`. Leave `selfOwnedOnly` unset or set it to `false` to include views created by others.

Start with a view saved in the UI and retrieve it by UUID:

```bash
export VIEW_ID='<SAVED_VIEW_UUID>'
curl --fail-with-body -sS "$GC_BASE_URL/api/views/$VIEW_ID" \
  -H "Authorization: Bearer $GC_API_KEY" \
  -H "X-Backend-Id: $GC_BACKEND_ID" > view.json
```

A **200** response contains `uuid`, `name`, `viewType`, `preset`, `status`, `revisionNumber`, owner/timestamp metadata and optional description, team and tags. `preset` is a JSON-encoded **string** containing the page-specific configuration. Preserve its structure and `viewType` when copying a view.

For a member-specific list, use the `viewType` returned by that read. This example uses `jq`:

```bash
jq '{type:.viewType,favoritesOnly:false,selfOwnedOnly:true}' view.json > view-list.json
curl --fail-with-body -sS -X POST "$GC_BASE_URL/api/views/member" \
  -H "Authorization: Bearer $GC_API_KEY" \
  -H "X-Backend-Id: $GC_BACKEND_ID" \
  -H 'Content-Type: application/json' \
  --data-binary @view-list.json
```

Returns an array of matching member views.

## Create a view

**POST** `/api/views`

| Field         | Required | Description                                        |
| ------------- | -------- | -------------------------------------------------- |
| `name`        | Yes      | Display name.                                      |
| `viewType`    | Yes      | Page type associated with the saved configuration. |
| `preset`      | Yes      | Valid JSON encoded as a string.                    |
| `description` | No       | Description.                                       |
| `team`        | No       | Team metadata.                                     |
| `tags`        | No       | Up to 20 normalized tags.                          |

To duplicate the saved view retrieved above:

```bash
jq '{name:"My saved view copy",description,viewType,preset,team,tags}' view.json > view-create.json
curl --fail-with-body -sS -X POST "$GC_BASE_URL/api/views" \
  -H "Authorization: Bearer $GC_API_KEY" \
  -H "X-Backend-Id: $GC_BACKEND_ID" \
  -H 'Content-Type: application/json' \
  --data-binary @view-create.json
```

Returns **201 Created** with a new UUID, owner and revision number.

## Update a view

**PUT** `/api/views/{id}` takes the same fields as create, plus `currentRevision` from the latest `revisionNumber`. It replaces the definition, so retain fields you want to keep.

Only the creator can update a saved view through this endpoint; Admin permissions do not bypass this ownership check. To customize someone else's view, create your own copy first and update its new UUID.

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

Returns **202 Accepted** with the updated object. A stale revision returns **409** with code `VIEW_REVISION_CONFLICT`. Read again and reconcile changes. Setting `override:true` and omitting `currentRevision` intentionally bypasses the revision check; it does not bypass ownership checks.

## Archive, restore and delete

* **POST** `/api/views/{id}/archive?currentRevision={revision}` archives a view.
* **POST** `/api/views/{id}/restore?currentRevision={revision}` restores an archived view.
* **DELETE** `/api/views/{id}` permanently deletes it.

These operations require Editor permissions or higher and can affect views created by other identities; they do not require creator ownership.

Fetch the current revision before archive/restore; both return **202** and the resulting view. Deletion returns **200** with no response body.

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

## Favorites and default views

* **POST** `/api/views/{id}/favorite` adds a favorite; **DELETE** at the same path removes it.
* **POST** `/api/views/{id}/default` selects the default for that view type; **DELETE** removes that preference.
* **GET** `/api/views/member/defaults` returns the calling identity's default views.

Preference mutations need no body and return **202** with no body:

```bash
curl --fail-with-body -sS -X POST "$GC_BASE_URL/api/views/$VIEW_ID/favorite" \
  -H "Authorization: Bearer $GC_API_KEY" \
  -H "X-Backend-Id: $GC_BACKEND_ID"
```

## Pins

**POST** `/api/views/{id}/pin` requires `order`, an integer of at least 1. Only active views can be pinned. **DELETE** at the same path unpins the view; both return **202** with no body.

```bash
curl --fail-with-body -sS -X POST "$GC_BASE_URL/api/views/$VIEW_ID/pin" \
  -H "Authorization: Bearer $GC_API_KEY" \
  -H "X-Backend-Id: $GC_BACKEND_ID" \
  -H 'Content-Type: application/json' \
  -d '{"order":1}'
```

**GET** `/api/views/member/pins` returns an array ordered by highest `pinOrder` first. Entries contain `resourceType`, `resourceUuid`, `name` and `pinOrder`; archived/deleted resources are omitted.

**PUT** `/api/views/member/pins/order` takes `{"ids":["<UUID>","<UUID>"]}` in the desired first-to-last display order. Send the complete current pin list with no duplicate UUIDs. It reorders existing pins rather than pinning new resources and returns **202**.

Invalid UUIDs or malformed bodies return **400**, nonexistent views **404**, and an update by a different owner **403**. Managed catalog dashboards retain their mutation restrictions even when addressed through view endpoints.


---

# 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/saved-views-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.
