---
title: "Update a saved view"
method: PATCH
path: "/vaults/{id}/views/{viewId}"
tags: ["Contract Intelligence"]
---

# Update a saved view

`PATCH /vaults/{id}/views/{viewId}`

## Request

- Base URL: `https://app.gc.ai/api/external/v1`
- URL: `https://app.gc.ai/api/external/v1/vaults/{id}/views/{viewId}`
- Auth: API key in header `Authorization`
- TypeScript: <https://skmtc.dev/gc-ai/apis/gc-ai-external-api/docs/vaults/:id/views/:viewId/patch.ts> (a function with typed inputs; its response is checked against the schema)

Rename a saved view, replace its layout, or both. Send at least one of `name` and `view_state`.

`view_state` is a full replacement of all four of `hidden_field_keys`, `field_order`, `sort`, and `filters`. A field you leave out of the object is cleared, not kept, so read the view with `GET /vaults/{id}/views` first when you mean to change one part of it.

Column visibility is stored as a hide list. `hidden_field_keys` names the columns a view hides, so an empty list means the view shows every column the vault has. A column added to the vault later appears in the view until you hide it.

Every field key has to exist in the vault. Keys in `hidden_field_keys` and `field_order` can also name a system column (`actions`, `fileName`, `relationships`, `extractedAt`, `sourceName`). `sort.field` takes a vault column or one of `fileName`, `extractedAt`, `sourceName`, because those are the only system columns the table can sort by. A filter `field_key` takes a vault column or `__notes__`, the any-column notes filter. Anything else returns `400` naming the keys it could not place, rather than being dropped on the way in and leaving you with a view that ignores half of what you sent.

The view has to belong to the vault in the path. A view ID from another vault returns `404`, even when the caller can reach both vaults.

A change here is visible to every member of the vault, because views are shared rather than per-person.

Requires the `editor` or `owner` role in the vault, the organization-level permission to manage vaults, and the organization-level Manage Views permission. A caller who holds the vault role but not both permissions gets `403`.

Requires a user-scoped API key (`u:gcai_...`). A vault is shared with named people, so an organization-scoped key has no identity to resolve vault access with.

## Path parameters

- `id` string, uuid, required: The vault ID
- `viewId` string, uuid, required: View ID from `GET /vaults/{id}/views`.

## Request body

- VaultViewUpdateRequest
  - `name` string: New view name.
  - `view_state` object: Replacement layout, sort, and filters. This is a full replacement of all four fields, so send the whole object.
    - `hidden_field_keys` string[], required: Column keys this view hides. This is a hide list, not a show list, so an empty array means the view shows every column in the vault. A column added to the vault after the view was saved is visible in the view until you add its key here.
    - `field_order` string[], required: Column keys in the order this view shows them, left to right. An empty array means the view uses the vault default order. Keys you leave out keep their default position relative to one another.
    - `sort` VaultViewSort, nullable, required: Sort this view applies, or `null` for the vault default order.
      - `field` string, required: Column to sort by: a vault column key, or one of `fileName`, `extractedAt`, `sourceName`.
      - `direction` 'asc' | 'desc', required: Sort direction.
    - `filters` VaultViewFilter[], required: Filter rules this view applies. Rules combine with AND. An empty array means the view shows every document in the vault.
      - `field_key` string, required: Column the rule applies to. Use a vault column key, or `__notes__` for the any-column notes filter.
      - `operator` 'contains' | 'equals' | 'date_range' | 'in' | 'boolean' | 'number_range' | 'party_contains' | 'list_length' | 'equals_only' | 'not_contains' | 'not_equals' | 'is_empty' | 'is_not_empty' | 'is_before' | 'is_after' | 'has_notes' | 'has_no_notes', required: Comparison to apply. Operators are typed to column kinds, so an operator the column cannot carry has no effect on the rows the view returns.
      - `value` unknown

## Response `200`

The updated view

- VaultViewResponse
  - `id` string, uuid, required: Unique view identifier
  - `vault_id` string, uuid, required: Vault this view belongs to
  - `name` string, required: View name, as shown on its tab in the app
  - `position` integer, required: Zero-based slot this view occupies in the vault view order. Read-only over the API: reordering views is not available here yet.
  - `created_by_user_id` integer, nullable, required: GC AI user ID of whoever created the view, or null when that person has since been removed. Provenance only: a view is shared with the whole vault and is not owned by its creator.
  - `view_state` VaultViewState, required
    - `hidden_field_keys` string[], required: Column keys this view hides. This is a hide list, not a show list, so an empty array means the view shows every column in the vault. A column added to the vault after the view was saved is visible in the view until you add its key here.
    - `field_order` string[], required: Column keys in the order this view shows them, left to right. An empty array means the view uses the vault default order. Keys you leave out keep their default position relative to one another.
    - `sort` VaultViewSort, nullable, required: Sort this view applies, or `null` for the vault default order.
      - `field` string, required: Column to sort by: a vault column key, or one of `fileName`, `extractedAt`, `sourceName`.
      - `direction` 'asc' | 'desc', required: Sort direction.
    - `filters` VaultViewFilter[], required: Filter rules this view applies. Rules combine with AND. An empty array means the view shows every document in the vault.
      - `field_key` string, required: Column the rule applies to. Use a vault column key, or `__notes__` for the any-column notes filter.
      - `operator` 'contains' | 'equals' | 'date_range' | 'in' | 'boolean' | 'number_range' | 'party_contains' | 'list_length' | 'equals_only' | 'not_contains' | 'not_equals' | 'is_empty' | 'is_not_empty' | 'is_before' | 'is_after' | 'has_notes' | 'has_no_notes', required: Comparison to apply. Operators are typed to column kinds, so an operator the column cannot carry has no effect on the rows the view returns.
      - `value` unknown
  - `created_at` string, required: ISO 8601 creation timestamp
  - `updated_at` string, required: ISO 8601 last-update timestamp

## Other responses

- `400`: Invalid request body, or a field key the vault does not have
- `401`: Missing or malformed API key
- `403`: Contract Intelligence is not enabled for this account. Contact support to request access., or the caller cannot manage views in this vault
- `404`: Vault or view not found, the view belongs to another vault, or access denied
- `409`: The vault is archived, or another view in it already has that name
- `422`: Vault access is per-user and requires a user-scoped API key (u:gcai_...).
- `429`: Rate limit exceeded. See [Rate Limits](https://docs.gc.ai/api-reference/concepts/rate-limits) for the tiers, limits, and how to back off.
- `500`: Internal server error
- `503`: Service temporarily unavailable

---

[API](https://skmtc.dev/gc-ai/apis/gc-ai-external-api.md) - [All operations](https://skmtc.dev/gc-ai/apis/gc-ai-external-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gc-ai/apis/gc-ai-external-api/revisions/2bbdfddf7107?raw)