Skip to main content
const folder = await airstore.smartFolders.create('ws_abc123', {
  integration: 'gmail',
  name: 'Unread Emails',
  guidance: 'unread emails from the inbox',
})
console.log(folder.path) // "/Sources/gmail/Unread Emails"
A smart folder is a natural language query that materializes as a directory in the virtual filesystem. You describe what you want (“unread emails from investors”), and Airstore translates that into API calls to the connected integration, fetching matching data as files.

Create a smart folder

import Airstore from '@airstore/sdk'

const airstore = new Airstore()

const folder = await airstore.smartFolders.create('ws_abc123', {
  integration: 'gmail',
  name: 'Investor Emails',
  guidance: 'emails from investors in the last 30 days',
  outputFormat: 'folder',  // default -- each result is a file
})

console.log(folder.external_id)  // "sq_abc123"
console.log(folder.path)         // "/Sources/gmail/Investor Emails"
The guidance field is where the magic happens. Be specific — “emails from investors in the last 30 days” works better than “investor stuff.”

Output formats

FormatDescription
folderEach result becomes a separate file in the directory (default)
fileAll results are aggregated into a single file
// Single-file output
const report = await airstore.smartFolders.create('ws_abc123', {
  integration: 'linear',
  name: 'Sprint Summary',
  guidance: 'all issues in the current sprint',
  outputFormat: 'file',
  fileExt: '.md',
})

Browse smart folder contents

Once created, use the filesystem methods to browse what’s inside:
const files = await airstore.fs.list('ws_abc123', {
  path: folder.path,
})

for (const file of files) {
  console.log(`${file.name} (${file.size} bytes)`)
}
Smart folders sync in the background. There may be a short delay between creating a folder and its contents appearing. If the folder is empty immediately after creation, wait a few seconds and try again.

List all smart folders

const folders = await airstore.smartFolders.list('ws_abc123')

for (const f of folders) {
  console.log(`${f.name}${f.path} (${f.integration})`)
}

Update a smart folder

Change the name or guidance of an existing smart folder:
const updated = await airstore.smartFolders.update('ws_abc123', 'sq_abc123', {
  guidance: 'unread emails from investors, last 7 days only',
})
Updating the guidance triggers a re-sync with the new query.

Delete a smart folder

await airstore.smartFolders.del('ws_abc123', 'sq_abc123')

Query examples

IntegrationGuidanceWhat you get
Gmail"emails from investors in the last 30 days"Recent investor correspondence
GitHub"open PRs in acme/api with full diffs"PR diffs ready for review
Linear"high priority issues in the current sprint"Urgent work items
Google Drive"PDF contracts from 2024"Last year’s contracts
Notion"meeting notes from January"Recent meeting docs
PostHog"active feature flags"Currently enabled flags

Next steps