> ## 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.

# Filesystem

> client.fs — browse and read from the virtual filesystem

```typescript theme={null}
const files = await airstore.fs.list('ws_abc123', { path: '/' })
const content = await airstore.fs.read('ws_abc123', { path: files[0].path })
```

The filesystem resource provides read-only access to the workspace's virtual filesystem. Connected integrations and source views surface their data as files and directories you can list, read, and inspect.

***

## list()

List entries in a directory.

```typescript theme={null}
const entries = await airstore.fs.list('ws_abc123', { path: '/sources/gmail/' })

for (const entry of entries) {
  console.log(`${entry.is_folder ? '📁' : '📄'} ${entry.name}`)
}
```

**Parameters**

| Parameter     | Type     | Required | Default | Description            |
| ------------- | -------- | -------- | ------- | ---------------------- |
| `workspaceId` | `string` | Yes      | --      | Workspace external ID  |
| `path`        | `string` | No       | `/`     | Directory path to list |

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

| Field         | Type                                   | Description                           |
| ------------- | -------------------------------------- | ------------------------------------- |
| `id`          | `string`                               | Unique file identifier                |
| `name`        | `string`                               | File or directory name                |
| `path`        | `string`                               | Full path                             |
| `type`        | `string`                               | MIME type                             |
| `is_folder`   | `boolean`                              | Whether this is a directory           |
| `size`        | `number`                               | File size in bytes                    |
| `modified_at` | `string \| undefined`                  | ISO 8601 last modified timestamp      |
| `child_count` | `number \| undefined`                  | Number of children (directories only) |
| `metadata`    | `Record<string, unknown> \| undefined` | Provider-specific metadata            |

***

## read()

Read file contents as a string.

```typescript theme={null}
const content = await airstore.fs.read('ws_abc123', {
  path: '/sources/gmail/Unread Emails/meeting-notes.eml',
})
```

For large files, use byte-range reads:

```typescript theme={null}
const preview = await airstore.fs.read('ws_abc123', {
  path: '/sources/gmail/large-file.eml',
  offset: 0,
  length: 1024,
})
```

**Parameters**

| Parameter     | Type     | Required | Description                       |
| ------------- | -------- | -------- | --------------------------------- |
| `workspaceId` | `string` | Yes      | Workspace external ID             |
| `path`        | `string` | Yes      | File path                         |
| `offset`      | `number` | No       | Byte offset to start reading from |
| `length`      | `number` | No       | Number of bytes to read           |

**Returns** `Promise<string>` -- the file contents.

***

## tree()

Get a recursive directory tree. Supports pagination for large directories.

```typescript theme={null}
const tree = await airstore.fs.tree('ws_abc123', { path: '/' })

for (const entry of tree.entries) {
  console.log(entry.path)
}

if (tree.truncated) {
  // Fetch the next page
  const next = await airstore.fs.tree('ws_abc123', {
    path: '/',
    continuationToken: tree.continuation_token,
  })
}
```

**Parameters**

| Parameter           | Type     | Required | Default | Description                              |
| ------------------- | -------- | -------- | ------- | ---------------------------------------- |
| `workspaceId`       | `string` | Yes      | --      | Workspace external ID                    |
| `path`              | `string` | No       | `/`     | Root path for the tree                   |
| `maxKeys`           | `number` | No       | --      | Maximum entries to return                |
| `continuationToken` | `string` | No       | --      | Token from a previous truncated response |

**Returns** `Promise<TreeListing>`

| Field                | Type                  | Description                        |
| -------------------- | --------------------- | ---------------------------------- |
| `path`               | `string`              | Root path of the tree              |
| `entries`            | `VirtualFile[]`       | Files and directories              |
| `truncated`          | `boolean`             | Whether more entries are available |
| `continuation_token` | `string \| undefined` | Token for the next page            |

***

## stat()

Get metadata for a single file or directory without reading its contents.

```typescript theme={null}
const info = await airstore.fs.stat('ws_abc123', '/sources/gmail/Unread Emails/invoice.pdf')

console.log(info.name)        // "invoice.pdf"
console.log(info.size)        // 48230
console.log(info.type)        // "application/pdf"
console.log(info.modified_at) // "2025-01-15T10:30:00Z"
```

**Parameters**

| Parameter     | Type     | Required | Description            |
| ------------- | -------- | -------- | ---------------------- |
| `workspaceId` | `string` | Yes      | Workspace external ID  |
| `path`        | `string` | Yes      | File or directory path |

**Returns** `Promise<VirtualFile>`