Context-aware Agent

Overview

AI agents are more effective when they can access each user’s specific documents and knowledge bases. Keeping these documents updated is challenging, but the StackOne Documents API makes it easy to access and sync user files for your agent.

API Reference: See available operations in the documents/api-reference/.Every API endpoint can be provided as a tool within an agent through StackOne’s AI Library (nodejs, python)

This use case demonstrates how to:

Enable users to select relevant documents from their connected storage (SharePoint, Google Drive, Notion, etc.)
Index and process selected documents for AI agent context
Implement real-time document synchronization with webhooks
Build low-latency search and retrieval for agent responses
Combine RAG’d document data with real-time tool calling

Step-by-Step Guide

Prerequisites

Before implementing this use case, ensure you have:

Enabled document integrations in your StackOne project for the providers you want to support (SharePoint, Google Drive, Confluence, etc.)
Reviewed the integration setup guides for provider-specific configuration requirements

Some document providers require additional OAuth application setup beyond the standard StackOne integration configuration. This may include creating custom OAuth apps with specific providers to enable full functionality and avoid rate limits. See the integration guides overview for detailed provider-specific requirements.

Set Up Webhook Endpoints Configure webhooks in your StackOne dashboard to receive account.created and documents_files.updated events. API Reference: Webhooks Guide

Webhook Integration Details

Webhook Integration

StackOne provides webhook events to keep your AI agent’s knowledge base synchronized with changes in connected providers:

Key Webhook Events

account.created - Triggered when users successfully authenticate new document accounts
documents_files.updated - Fired when files are modified, moved, or have metadata changes
documents_files.deleted - Notifies when files are removed or access is revoked

Setting Up Webhooks

Configure webhooks in your StackOne dashboard to receive real-time notifications about document changes. See the Webhooks Guide for detailed setup instructions.

Content Refresh Strategies

Strategy	When to Use	Implementation
Scheduled Sync	Batch processing, tolerance for delays	Cron jobs that re-index files periodically (hourly/daily)
Webhook-Driven	Real-time requirements, immediate updates	React to `documents_files.updated` events
Manual Sync	User-controlled updates, debugging	Admin dashboard triggers for specific accounts/files

Generate Connect Session Token Use the Create Connect Session API with multiple: true for per-user account linking. Additional API: List Accounts to retrieve connected document provider accounts
Embed Integration Hub Install and configure StackOne React Hub for OAuth flows. API Reference: Embedding StackOne Hub
Implement File Picker Deploy StackOne File Picker for folder/file selection. API Reference: File Picker Guide

Picker Implementation Details

File Picker Integration

The StackOne File Picker provides a unified interface for document selection across providers. Based on the StackOne File Picker repository, here are the available callback events and configuration options:

File Picker Configuration Options

const filePicker = new FilePicker({
  sessionToken: 'your-session-token', // Required
  containerId: 'file-picker-container', // Optional: DOM container ID
  baseUrl: 'https://app.stackone.com', // Optional: API instance
  fields: ['name', 'path', 'driveId'], // Optional: which file fields to return
  showBranding: false, // Optional: show StackOne footer (default: true)
  folderSelectionEnabled: true, // Optional: allow folder selection (default: false)
  driveSelectionEnabled: true, // Optional: allow drive selection (default: false)

  // Callback Events
  onFilesPicked: (files) => {
    console.log('Selected files:', files);
    // Process selected files for indexing
  },
  onOpen: () => {
    console.log('File picker opened');
  },
  onClose: () => {
    console.log('File picker closed');
  },
  onCancel: () => {
    console.log('File selection canceled');
  },
  onError: (error) => {
    console.log('File picker error:', error);
  }
});

File Selection Response Format

When users complete their selection, the onFilesPicked callback receives different response formats depending on what was selected:

// Example response when only files are selected
{
  "files": [
    {
      "id": "c28xIQaWQ6ODA5MzcyMg", // Unified file ID
      "name": "Project Proposal.pdf", // File name
      "path": "/Projects/2024/Project Proposal.pdf", // File path
      "driveId": "7733268" // Drive identifier
    },
    {
      "id": "d39yJRbXR7PEB6NzY3Ng",
      "name": "Budget Analysis.xlsx",
      "path": "/Projects/2024/Budget Analysis.xlsx",
      "driveId": "7733268"
    }
  ]
}

Folder Selection Handling: When folderSelectionEnabled: true is set, users can select entire folders. The response will include folder IDs in the selection. To retrieve all files within selected folders (including nested subfolders), use the List Files API with the folder_id parameter and nested_files: true option to automatically fetch all nested content.

Note: Only onFilesPicked is typically required for document management use cases. Other callbacks (onOpen, onClose, onCancel, onError) are optional and depend on specific user actions or error conditions.

Key Providers Supported

OAuth Application Setup Required: Some providers may require creating OAuth applications and configuring credentials. See the Documents Integration Guides for provider-specific setup instructions, including Google Drive, SharePoint, and OneDrive OAuth configurations.

Provider	Picker Type	Navigation	Multi-Select	File Types
SharePoint	Native	Site → Drive → Folder → File	✅	All documents
OneDrive	Native	Drive → Folder → File	✅	All documents
Google Drive	Native	Drive → Folder → File	✅	All documents
Confluence	Custom	Space → Page	✅	Pages/Documents
Notion	Custom	Workspace → Page	✅	Pages/Blocks

For other providers, you can check support in the StackOne’s integration page or your Dashboard’s field coverage page or request a new integration via our in-app, slack or email support.

Picker Output Format

When users complete their selection, the picker returns different formats based on what was selected and configured:

{
  "files": [
    {
      "id": "c28xIQaWQ6ODA5MzcyMg",
      "name": "Project Proposal.pdf",
      "path": "/Projects/2024/Project Proposal.pdf",
      "driveId": "7733268",
      "mimeType": "application/pdf",
      "size": 2048000,
      "lastModified": "2024-01-15T10:30:00Z"
    }
  ]
}

Index Selected Content Use Download File and Get File to retrieve file content and metadata. Store content in your data store (vector database, search index, etc.). Additional APIs: List Files, List Folders, List Drives

Maintain Content Freshness Implement one or more strategies to keep your agent’s knowledge base current. These approaches are not mutually exclusive and can be combined:

Strategy	When to Use	Implementation
Scheduled Sync	Batch processing, tolerance for delays	Cron jobs that re-index files periodically using stored file/folder IDs
Webhook-Driven	Real-time requirements, immediate updates	React to `documents_files.updated` events for instant synchronization
Manual Sync	User-controlled updates, debugging	Admin dashboard triggers for specific accounts/files

API Endpoints: Use Get File and Download File when documents_files.updated webhooks are received Optional: Upload File for agent-generated content

API Operations & Dataflow

Using StackOne SDKs

StackOne provides official SDKs for multiple programming languages to simplify API integration. You can find the complete SDK documentation at StackOne API SDKs.

Additional Use Cases You Can Build with this API

Just-in-time file attachment to an AI chatbot: Add the ability for your users to attach files from SharePoint, Google Drive and more to a conversation, ChatGPT style
One-click attachments to CRM/tickets/training
Policy/compliance sync across approved sources
Unified knowledge base across SharePoint, Confluence, Notion, etc.

Troubleshooting

Common Issues

Issue	Symptoms	Solution
Authentication Errors	401 Unauthorized responses	Refresh OAuth tokens through StackOne Connect
File Access Denied	403 Forbidden when accessing files	Verify user permissions in source provider
Slow File Listings	Timeout errors when listing large folders	Implement pagination and chunked requests
Upload Failures	Files not appearing after upload	Check provider-specific upload limits and file type restrictions

Support Resources

For persistent issues or advanced integration support:

Review the StackOne Error Codes Guide
Contact StackOne support through the dashboard
Consult provider-specific documentation for detailed error codes

Getting Started

Use Cases

Common Guides

API Reference

Context-aware Agent

Overview

Step-by-Step Guide

Prerequisites

Webhook Integration

Key Webhook Events

Setting Up Webhooks

Content Refresh Strategies

File Picker Integration

File Picker Configuration Options

File Selection Response Format

Key Providers Supported

Picker Output Format

API Operations & Dataflow

Using StackOne SDKs

Additional Use Cases You Can Build with this API

Troubleshooting

Common Issues

Support Resources

Getting Started

Use Cases

Common Guides

API Reference

​Overview

​Step-by-Step Guide

​Prerequisites

​API Operations & Dataflow

​Using StackOne SDKs

​Additional Use Cases You Can Build with this API

​Troubleshooting

​Common Issues

​Support Resources

Overview

Step-by-Step Guide

Prerequisites

API Operations & Dataflow

Using StackOne SDKs

Additional Use Cases You Can Build with this API

Troubleshooting

Common Issues

Support Resources