---
title: "View Experiences"
source: "https://docs.vertesiahq.com/content/view-experiences"
markdown: "https://docs.vertesiahq.com/llms/content/view-experiences.md"
---

# View Experiences

A **View Experience** is a named, reusable configuration for finding content in a Vertesia project. Instead of
building search UI and writing Elasticsearch queries by hand, you describe *what* users should be able to browse and
search — the content scope, the facets, the search behavior, and the result layouts — and Vertesia renders and
executes it for you.

Persist a View once, then open it through the generic `/view/` route or embed it in an application with the
`ViewExperience` React component.

  View execution uses Elasticsearch. Enable it for the project before opening or embedding a View. See
  [Search Configuration](/content/search).

## Anatomy of a View

Every View Experience is four parts. Most of the documentation is organized around them:

```text
View Experience
├── scope        which content the View covers — content types, locations, collections, a fixed filter
├── navigation   how users narrow down — property facets, hierarchies, ranges, collections, location
├── search       how users search — deterministic (keywords + key terms) or agentic (natural language)
└── results      how matches are shown — list, table, cards, gallery, or board displays, plus sorting
```

A View author configures these four sections; the runtime turns them into a secure Elasticsearch query and a
normalized result set that the reusable UI renders.

## How a View runs, end to end

```text
   AUTHOR                        PERSIST                     EXECUTE                    RENDER
 ┌──────────┐   client.views   ┌───────────────┐  resolve  ┌──────────┐   execute()   ┌──────────┐
 │  Studio  │ ───────────────▶ │ studio-server │ ────────▶ │   Zeno   │ ────────────▶ │   your   │
 │  editor  │   create/update  │   (MongoDB)   │  by id    │   (ES)   │  /view/:id or │   app    │
 │ + Agent  │   or an app's    │   versioned   │           │  secure  │  ViewExperience│   UI     │
 └──────────┘   in-code View   └───────────────┘           └──────────┘               └──────────┘
```

1. **Authoring** happens in the Studio editor (with help from Studio Assistant), or an application ships a View
   **in code**. See [Configuration](/content/view-experiences/configuration).
2. **Persistence** is owned by **studio-server**: project-scoped, separately revisioned View resources under
   `/api/v1/views`. The platform includes read-only `sys:*` Views, and apps can contribute in-code definitions that
   resolve as `app:<app-name>:<view-id>`.
3. **Execution** is owned by **Zeno** at `POST /api/v1/view-executions/:id/execute`. It loads the authoritative configuration,
   composes the query, and returns normalized results.
4. **Rendering** uses the generic `/view/` route or the `ViewExperience` component. See
   [Embedding in applications](/content/view-experiences/embedding).

The client only ever sends **user-controlled state** — the text query, selected facets, chosen display, sort, and
page. It never sends a raw Elasticsearch request.

## Security model

View execution is safe to expose to end users because the server, not the client or the model, owns the dangerous
parts of the query:

- The View's **scope** (content types, locations, collections, fixed filter) and the caller's **content-security**
  and project filters are always composed on the server, *outside* anything a user or an agent supplied.
- Agentic search asks a model to produce a query, but the result is checked against a **validated allowlist** of
  query types and fields before the immutable scope and security filters are added around it.
- Only **head revisions** are searched by default, and callers can only select **authored** sort options — never
  arbitrary Elasticsearch sort clauses.
- Generated Elasticsearch DSL and security filters are **never** placed in the URL. Execution diagnostics may expose
  the validated model-authored query subtree, but never the server-owned scope or content-security filters.

## When to use a View

Use a View Experience when you want a reusable, shareable, permission-aware way to browse and search project content —
an internal document library, an operational worklist, a customer-facing search page, or an agent-authored browsing
surface. Prefer a direct [content search](/content/search) call when you need a one-off query with no reusable UI, and
a [collection](/content/overview) when you only need to group a fixed set of objects without search or navigation.

## In this section

- **[Quickstart](/content/view-experiences/quickstart)** — create your first View in three steps.
- **[Configuration](/content/view-experiences/configuration)** — scope, navigation, search, and result displays in
  depth, with a complete example.
- **[Search & agentic planning](/content/view-experiences/search)** — deterministic versus natural-language search,
  and the typed-indexing prerequisite for numeric and date facets.
- **[Embedding in applications](/content/view-experiences/embedding)** — the route, the `ViewExperience` component,
  deep links, custom renderers, and in-code (app-contributed) Views.
- **[API & validation reference](/content/view-experiences/reference)** — REST endpoints, draft preview, permissions,
  and configuration validation.
- **[Troubleshooting](/content/view-experiences/troubleshooting)** — common problems and how to fix them.