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

# Create a saved view

`POST /vaults/{id}/views`

## Request

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

Create a saved view in a vault. The view is shared with the whole vault the moment it exists: anyone who can read the vault can open it, and anyone with the Manage Views permission can change or delete 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.

View names are unique within a vault once trimmed, and the comparison is case sensitive, so `Renewals` and `renewals` can both exist. A name already taken returns `409`.

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

## Request body

- VaultViewCreateRequest
  - `name` string, required: View name. Trimmed before it is stored, and unique within the vault.
  - `view_state` VaultViewStateInput: Layout, sort, and filters for the view. Omit it for a view that shows every column in the vault default order, unsorted and unfiltered.
    - `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 `201`

The created 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 not found 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)