> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metabind.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Saved Searches Overview

> Store and reuse common search criteria for content and assets

Saved Searches allow projects to maintain a collection of common search criteria for content and assets. These searches are globally available within the project, *and* users can mark their frequently used searches as favorites.

## Permission Requirements

Saved searches inherit permissions from `content` and `assets`. Users need read permissions on either resource type to view and execute searches, *and* update permissions to create or modify searches.

## The SavedSearch Object

<ParamField body="id" type="string">
  Unique identifier (UUID)
</ParamField>

<ParamField body="name" type="string">
  Display name of the saved search
</ParamField>

<ParamField body="description" type="string">
  Optional description
</ParamField>

<ParamField body="type" type="string">
  Search type: `content` or `asset`. Determines what resources this search queries.
</ParamField>

<ParamField body="folderId" type="string">
  Parent folder ID (null for root). If set, the folder's type must match this search's type.
</ParamField>

<ParamField body="filter" type="object">
  Search filter criteria using standard filter operators
</ParamField>

<ParamField body="sort" type="object[]">
  Sort criteria array
</ParamField>

<ParamField body="favorites" type="string[]">
  User IDs who have favorited this search
</ParamField>

<ParamField body="metadata" type="object">
  Additional metadata including `lastUsed` timestamp and `useCount`
</ParamField>

<ParamField body="createdAt" type="string">
  Creation timestamp (ISO 8601 format)
</ParamField>

<ParamField body="updatedAt" type="string">
  Last update timestamp (ISO 8601 format)
</ParamField>

### Example Object

```json theme={null}
{
  "id": "ss123",
  "name": "Draft Articles",
  "description": "All draft articles in the system",
  "type": "content",
  "folderId": "folder789",
  "filter": {
    "type": {
      "eq": "article"
    },
    "status": {
      "eq": "draft"
    }
  },
  "sort": [
    { "field": "updatedAt", "order": "desc" }
  ],
  "favorites": ["user123", "user456"],
  "metadata": {
    "lastUsed": "2024-03-21T15:30:00Z",
    "useCount": 42
  },
  "createdAt": "2024-03-20T10:00:00Z",
  "updatedAt": "2024-03-21T15:30:00Z"
}
```

## Relationship with Direct Search

Saved searches use the same filter structure as the direct search capabilities in the Content and Assets endpoints. The key differences are that saved searches:

1. Store the search criteria for reuse
2. Can be shared across users within a project
3. Track usage statistics
4. Allow favoriting for quick access

The search filter syntax and operators are identical to those used in direct Content and Assets search endpoints:

```javascript theme={null}
// Direct Content Search:
POST /app/v1/organizations/:orgId/projects/:projectId/content
{
  "filter": { "status": { "eq": "published" } }
}

// Equivalent Saved Search:
// 1. Create saved search
POST /app/v1/organizations/:orgId/projects/:projectId/saved-searches
{
  "name": "Published Content",
  "type": "content",
  "filter": { "status": { "eq": "published" } }
}

// 2. Execute saved search
POST /app/v1/organizations/:orgId/projects/:projectId/saved-searches/ss123/execute
```

## Filter Operators

Saved searches support all standard filter operators:

| Operator   | Description           | Example                                     |
| ---------- | --------------------- | ------------------------------------------- |
| `eq`       | Equals                | `{ "status": { "eq": "draft" } }`           |
| `neq`      | Not equals            | `{ "status": { "neq": "deleted" } }`        |
| `in`       | In array              | `{ "type": { "in": ["article", "page"] } }` |
| `contains` | String contains       | `{ "name": { "contains": "intro" } }`       |
| `gte`      | Greater than or equal | `{ "createdAt": { "gte": "2024-01-01" } }`  |
| `lte`      | Less than or equal    | `{ "createdAt": { "lte": "2024-12-31" } }`  |

## Sort Options

Sort criteria specify how results are ordered:

```json theme={null}
{
  "sort": [
    { "field": "updatedAt", "order": "desc" },
    { "field": "name", "order": "asc" }
  ]
}
```

Supported fields vary by search type:

* **Content**: `name`, `createdAt`, `updatedAt`, `status`
* **Asset**: `name`, `createdAt`, `updatedAt`, `type`, `size`