​
StackOne File Picker Integration: Confluence

StackOne integrates with Atlassian Confluence to support document selection and navigation through Confluence spaces and pages. Unlike traditional file systems, Confluence is a knowledge base platform, and its structure reflects that—where “pages” can act as both files and folders depending on how they are used. This document explains how StackOne models Confluence content, how we use the API, and how the custom file picker behaves.

​
Confluence Structure vs StackOne Model

Confluence ConceptStackOne EquivalentNotes
SpacedriveTop-level container for content within a site
Page with childrenfolder/fileA page can act as both a folder and a file
  • Duality of Pages: Confluence pages can behave as both folders and files. StackOne surfaces this by:
    • Including all pages in both the listFolders and listFiles endpoints
    • Adding metadata flags to indicate whether a page has content, children, or both

​
File Download

Confluence offers two endpoints for downloading files:
  • GET exportword?pageId={.id}
  • GET /wiki/rest/api/content/{id}?expand=body.export_view
These allow the download of files in either:
  • Word
  • HTML
StackOne uses the second endpoint to download files natively and allow the export of files as .doc.

​
File Picker Flow

The Confluence File Picker is custom-built by StackOne to present a consistent folder-like interface.
  1. Site Selection Users first select a site (Confluence instance), if multiple are connected.
  2. Space Listing StackOne loads all spaces (mapped to drives) within the site.
  3. Top-Level Pages Once a space is selected, users see a tree of pages. Each page is:
    • Clickable as a file (if it has content)
    • Expandable as a folder (if it has children)
  4. Nested Pages Pages can be expanded recursively to reveal their nested children.
  5. Selection Options Users can:
    • Select a page as a file (if it contains content)
    • Navigate through it as a folder (if it contains child pages)

​
StackOne Modeling Approach

StackOne Model ObjectHow It Maps to Confluence
driveA Confluence space
folderA page with child pages
fileA page with content or an attached document
metadataIndicates if an item has hasContent, hasChildren, or both
pathVirtualized to reflect the nested hierarchy of pages within a space

​
API Usage

StackOne uses the CQL (Confluence Query Language) API to efficiently retrieve content and metadata.
OperationAPI UsedNotes
List sitesConfigured in StackOne per connected accountNo Confluence API call; configuration-level
List spaces in siteGET /wiki/rest/api/spaceLists all available spaces
List pages in a spaceGET /wiki/rest/api/content/search?cql=...Filters top-level or nested pages using CQL
Upload attachment to pagePOST /api/v2/pagesUsed for file uploads
Download attachmentGET rest/api/content/{id}?expand=body.export_viewDirect file download endpoint
  • Search Strategy:
    • StackOne uses CQL queries to list content scoped to a space and parent page
    • This allows accurate retrieval of both files and folders under any point in the hierarchy
  • Handling Dual-Use Pages:
    • A page may appear as both a file and a folder
    • StackOne reflects this with flags and exposes both capabilities in the picker

​
File Semantics

TypeDisplayed AsCondition
Page with bodyFile (can be selected)body.storage.value present
Page with childrenFolder (can be expanded)ancestors.length > 0
  • Pages without content or children are still shown but cannot be selected
  • Pages with both content and children can be both selected and expanded

​
Permissions & Auth

  • API Token with optional scopes
    • Maximum 1-year expiry
  • Full set of integration scopes:
    • write:confluence-content
    • read:confluence-space.summary
    • read:confluence-props
    • write:confluence-props
    • read:confluence-content.all
    • read:confluence-content.summary
    • search:confluence
    • readonly:content.attachment:confluence

​
Summary

AreaConfluence
Picker UXCustom-built hierarchical UI
Root ModelSite → Space → Page (acts as file/folder)
File APICQL-based search of pages and attachments
Folder BehaviorPages act as folders if they contain child pages
File BehaviorPages act as files if they have content or attachments
Selection LogicPages can be both selectable and expandable simultaneously
StackOne NormalizationAll content mapped to unified file / folder objects
Let me know if you’d like this exported to Markdown or included in a broader API reference. I can also generate sample API responses or SDK snippets if needed.