Skip to main content
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 smart folders surface their data as files and directories you can list, read, and inspect.

​
list()

List entries in a directory. 
const entries = await airstore.fs.list('ws_abc123', { path: '/Sources/gmail/' })

for (const entry of entries) {
  console.log(`${entry.is_folder ? '📁' : '📄'} ${entry.name}`)
}
Parameters
ParameterTypeRequiredDefaultDescription
workspaceIdstringYes—Workspace external ID
pathstringNo/Directory path to list
Returns Promise<VirtualFile[]>
FieldTypeDescription
idstringUnique file identifier
namestringFile or directory name
pathstringFull path
typestringMIME type
is_folderbooleanWhether this is a directory
sizenumberFile size in bytes
modified_atstring | undefinedISO 8601 last modified timestamp
child_countnumber | undefinedNumber of children (directories only)
metadataRecord<string, unknown> | undefinedProvider-specific metadata

​
read()

Read file contents as a string. 
const content = await airstore.fs.read('ws_abc123', {
  path: '/Sources/gmail/Unread Emails/meeting-notes.eml',
})
For large files, use byte-range reads: 
const preview = await airstore.fs.read('ws_abc123', {
  path: '/Sources/gmail/large-file.eml',
  offset: 0,
  length: 1024,
})
Parameters
ParameterTypeRequiredDescription
workspaceIdstringYesWorkspace external ID
pathstringYesFile path
offsetnumberNoByte offset to start reading from
lengthnumberNoNumber of bytes to read
Returns Promise<string> — the file contents.

​
tree()

Get a recursive directory tree. Supports pagination for large directories. 
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
ParameterTypeRequiredDefaultDescription
workspaceIdstringYes—Workspace external ID
pathstringNo/Root path for the tree
maxKeysnumberNo—Maximum entries to return
continuationTokenstringNo—Token from a previous truncated response
Returns Promise<TreeListing>
FieldTypeDescription
pathstringRoot path of the tree
entriesVirtualFile[]Files and directories
truncatedbooleanWhether more entries are available
continuation_tokenstring | undefinedToken for the next page

​
stat()

Get metadata for a single file or directory without reading its contents. 
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
ParameterTypeRequiredDescription
workspaceIdstringYesWorkspace external ID
pathstringYesFile or directory path
Returns Promise<VirtualFile>