​
StackOne File Picker

The StackOne File Picker provides a unified interface for browsing and selecting documents from third-party platforms. It abstracts provider-specific differences behind a consistent user experience and developer interface, whether the source is a file storage system (like SharePoint, OneDrive, Google Drive) or a knowledge base (like Confluence or Notion).

​
How It Works

The File Picker allows users to:
  • Navigate a hierarchical file tree (folders, pages, blocks)
  • Select one or more files or documents
  • Return a list of StackOne file objects, which can be used with unified operations such as GET /files/{id} or POST /files/download

​
Picker Types

ProviderPicker TypeNavigation ModelNotes
SharePointNativeSite → Drive → Folder → FileMicrosoft-native picker with StackOne-built site selection UI
OneDriveNativeDrive → Folder → FileStandard OneDrive picker scoped to user’s personal/business drive
Google DriveNativeDrive → Folder → FileUses Google Picker SDK
ConfluenceCustomSpace → PagePages act as both folders and files based on content/children
Notion (Coming Soon)CustomWorkspace → PagePages/blocks behave similarly to Confluence in dual file/folder roles

​
Output Format

When a user completes selection, the picker returns: 
{ 
  "files": [
    {
      "id": "c28xIQaWQ6ODA5MzcyMg",
      "name": "QA text 1",
      "path": "https://exploreconfluence.atlassian.net/wiki/spaces/QS/pages/8093722/QA+text+1",
      "driveId": "7733268"
    }
  ]
}
Each fileId corresponds to a StackOne-normalized file object that can be accessed via API:
  • GET /files/{id} – fetch file metadata
  • POST /files/{id}/download – retrieve file contents (if supported)

​
File Object Structure (for Fetch)

When queried individually, a file returns the following structure: 
{
  "id": "file_123",
  "name": "Report Q1.pdf",
  "path": "/Marketing/Reports/Q1",
  "mimeType": "application/pdf",
  "size": 204800,
  "lastModified": "2024-12-01T10:00:00Z",
  "provider": "sharepoint",
  "downloadUrl": "https://..."
}
  • For knowledge bases like Confluence and Notion:
    • Files may represent pages or blocks
    • Additional metadata like hasContent, hasChildren is provided

​
Provider Feature Table

Feature / CapabilitySharePointOneDriveGoogle DriveConfluenceNotion (coming)
Picker TypeNativeNativeNativeCustomCustom
Tree Navigation✅✅✅✅✅
Multi-file Selection✅✅✅✅✅
Selectable File TypesAny documentAny documentAny documentPagesPages
Folder Navigation✅✅✅✅✅
Dual-role ItemsN/AN/AN/A✅ (pages)✅ (pages/blocks)
Output (on select)List of File objectsList of File objectsList of File objectsList of File objectsList of File objects
Unified Fetch / Download✅✅✅✅✅

​
Developer Integration

  1. Trigger the Picker Use the StackOne SDK, embed directly via the UI component or trigger via the StackOne Dashboard.
  2. Receive Selection The picker will return: 
    { 
  "files": [
    {
      "id": "c28xIQaWQ6ODA5MzcyMg",
      "name": "QA text 1",
      "path": "https://exploreconfluence.atlassian.net/wiki/spaces/QS/pages/8093722/QA+text+1",
      "driveId": "7733268"
    }
  ]
}
  3. Perform Unified Actions
    • Fetch metadata: GET /files/{id}
    • Download file: POST /files/{id}/download

​
Auth & Permissions

  • Each provider uses OAuth2 authentication via StackOne’s integration flow
  • File access scopes are handled per provider during auth
    • SharePoint: Files.Read.All, Sites.Read.All
    • Google: https://www.googleapis.com/auth/drive.readonly
    • Confluence/Notion: Read access to spaces/pages/blocks

​
StackOne File Picker SDK Documentation

The StackOne File Picker SDK enables you to integrate file selection from connected accounts into your application. Below are the installation steps, usage examples, and API details.

​
Installation

Install the SDK using one of the following package managers: 
# Using NPM
npm install --save @stackone/file-picker

# Using Yarn
yarn add @stackone/file-picker

​
Connect Session Token

The File Picker requires creating a separate connect session token with the Account ID and Provider Key of a connected account.

​
Usage

Below you can find the basic usage of the StackOne File Picker SDK using React: 
import React, { useState, useEffect, useCallback } from 'react';
import { FilePicker } from '@stackone/file-picker';
import { StackOne } from "@stackone/stackone-client-ts";

const _stackOne = new StackOne({
  security: {
    password: "",
    username: "",
  },
});

export const FilePickerButton = () => {
  const [filePicker, setFilePicker] = useState(null);

  useEffect(() => {
    const initializePicker = async () => {
      const { sessionToken } = await _stackOne.connectSessions.createConnectSession({
        categories: [ConnectSessionCreateCategories.Documents],
        accountId: '{{Connected Account ID}}',
        provider: '{{Provider Key}}',
        ...
      });
      setFilePicker(new FilePicker({ sessionToken }));
    };

    initializePicker();
  }, []);

  const handleClick = useCallback(() => {
    filePicker?.open();
  }, [filePicker]);

  return (
    <button onClick={handleClick} disabled={!filePicker}>
      Open File Picker
    </button>
  );
};

​
API Reference

​
FilePicker Class

​
Constructor: FilePicker(options)

The options object can include the following parameters:
​
sessionToken
string
required
The session token generated on the server side.
​
baseUrl
string
default:"https://app.stackone.com"
The base URL for the StackOne API.
​
containerId
string
The ID of the container to mount the picker into.
​
onFilesPicked
function
Callback function that is triggered when files are selected. The function will return an array of files with the Unified ID that can be used in the Unified Download Documents API. After receiving the files, the File Picker will close automatically.
​
onOpen
function
Callback function that is triggered when the picker opens.
​
onClose
function
Callback function that is triggered when the picker closes.
​
onCancel
function
Callback function that is triggered when the picker is closed without file selection.

​
Methods

​
open()
method
Opens the file picker interface.
​
close()
method
Closes the file picker interface.

​
Coming Soon: Notion Support

StackOne will soon launch a custom picker for Notion, modeled similarly to Confluence:
  • Block/page navigation
  • Unified selection of document-style pages
  • Multi-select and metadata retrieval