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

# Views

> client.views — create and manage source views

```typescript theme={null}
const view = await airstore.views.create('ws_abc123', {
  integration: 'gmail',
  name: 'Unread Emails',
  guidance: 'unread emails from the inbox',
})
```

Source views are materialized queries over connected data sources. In **smart** mode the query is LLM-inferred from a guidance string; in **query** mode the query is built from a structured per-integration filter. Results sync in the background and can be refreshed on demand.

***

## create()

Create a new source view.

If `filter` is provided, the view is created in query mode. Otherwise, it uses smart mode with LLM inference from `guidance`.

```typescript theme={null}
// Smart mode
const view = await airstore.views.create('ws_abc123', {
  integration: 'gmail',
  name: 'Investor Emails',
  guidance: 'emails from investors in the last 30 days',
  outputFormat: 'folder',
})

// Query mode
const view2 = await airstore.views.create('ws_abc123', {
  integration: 'github',
  name: 'Open PRs',
  filter: {
    repo: 'acme/api',
    type: 'prs',
    state: 'open',
    content_type: 'diff',
  },
})
```

**Parameters**

| Parameter      | Type                 | Required | Default  | Description                                                                                                                                             |
| -------------- | -------------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `workspaceId`  | `string`             | Yes      | --       | Workspace external ID                                                                                                                                   |
| `integration`  | `string`             | Yes      | --       | Integration source (`gmail`, `github`, `gdrive`, `notion`, `slack`, `linear`, `posthog`, `web`)                                                         |
| `name`         | `string`             | Yes      | --       | Display name                                                                                                                                            |
| `guidance`     | `string`             | No       | --       | Natural language query for LLM inference (smart mode)                                                                                                   |
| `filter`       | `object`             | No       | --       | Structured filter object (query mode). Shape depends on the integration — see [per-integration filters](/concepts/source-views#per-integration-filters) |
| `outputFormat` | `'folder' \| 'file'` | No       | `folder` | `folder` = one file per result; `file` = single aggregated file                                                                                         |
| `fileExt`      | `string`             | No       | --       | File extension for `file` output (e.g., `.md`)                                                                                                          |

**Returns** `Promise<SourceView>`

***

## list()

List all source views in a workspace.

```typescript theme={null}
const views = await airstore.views.list('ws_abc123')
```

**Parameters**

| Parameter     | Type     | Required | Description           |
| ------------- | -------- | -------- | --------------------- |
| `workspaceId` | `string` | Yes      | Workspace external ID |

**Returns** `Promise<SourceView[]>`

***

## retrieve()

Get a source view by its virtual filesystem path.

```typescript theme={null}
const view = await airstore.views.retrieve('ws_abc123', '/sources/gmail/Unread Emails')
```

**Parameters**

| Parameter     | Type     | Required | Description                         |
| ------------- | -------- | -------- | ----------------------------------- |
| `workspaceId` | `string` | Yes      | Workspace external ID               |
| `viewPath`    | `string` | Yes      | Virtual filesystem path of the view |

**Returns** `Promise<SourceView>`

***

## update()

Update an existing source view's name, guidance, or filter.

```typescript theme={null}
const updated = await airstore.views.update('ws_abc123', 'view_abc', {
  guidance: 'unread emails from the last 7 days only',
})
```

Updating the guidance or filter triggers a re-sync with the new query.

**Parameters**

| Parameter     | Type     | Required | Description                        |
| ------------- | -------- | -------- | ---------------------------------- |
| `workspaceId` | `string` | Yes      | Workspace external ID              |
| `viewId`      | `string` | Yes      | View external ID                   |
| `name`        | `string` | No       | New display name                   |
| `guidance`    | `string` | No       | New LLM guidance (smart mode)      |
| `filter`      | `object` | No       | New structured filter (query mode) |

**Returns** `Promise<SourceView>`

***

## del()

Delete a source view.

```typescript theme={null}
await airstore.views.del('ws_abc123', 'view_abc')
```

**Parameters**

| Parameter     | Type     | Required | Description           |
| ------------- | -------- | -------- | --------------------- |
| `workspaceId` | `string` | Yes      | Workspace external ID |
| `viewId`      | `string` | Yes      | View external ID      |

**Returns** `Promise<void>`

***

## sync()

Sync a source view — re-execute its query against the live source and refresh cached files.

```typescript theme={null}
const result = await airstore.views.sync('ws_abc123', 'view_abc')
console.log(`${result.results_count} total, ${result.new_results} new`)
```

Idempotent and safe to call repeatedly. Use this when you need fresh data before a read, or as part of a scheduled backend job.

**Parameters**

| Parameter     | Type     | Required | Description           |
| ------------- | -------- | -------- | --------------------- |
| `workspaceId` | `string` | Yes      | Workspace external ID |
| `viewId`      | `string` | Yes      | View external ID      |

**Returns** `Promise<SyncResult>`

| Field            | Type     | Description              |
| ---------------- | -------- | ------------------------ |
| `external_id`    | `string` | View external ID         |
| `integration`    | `string` | Integration source       |
| `path`           | `string` | Virtual filesystem path  |
| `mode`           | `string` | `smart` or `query`       |
| `last_synced_at` | `string` | ISO 8601 timestamp       |
| `results_count`  | `number` | Total results after sync |
| `new_results`    | `number` | Newly discovered results |

***

## SourceView object

All view methods return (or accept) a `SourceView` with these fields:

| Field           | Type     | Description                    |
| --------------- | -------- | ------------------------------ |
| `external_id`   | `string` | Unique identifier              |
| `integration`   | `string` | Integration source             |
| `path`          | `string` | Virtual filesystem path        |
| `name`          | `string` | Display name                   |
| `mode`          | `string` | `smart` or `query`             |
| `guidance`      | `string` | LLM guidance text (smart mode) |
| `filter`        | `object` | Structured filter (query mode) |
| `output_format` | `string` | Output format                  |
| `created_at`    | `string` | ISO 8601 creation timestamp    |
| `updated_at`    | `string` | ISO 8601 last update timestamp |