> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Confluence Integration

> How StackOne models Confluence spaces and pages, and how the custom file picker behaves.

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**. Its "pages" can act as both **files** and **folders** depending on how they are used.

This page explains how StackOne models Confluence content, how it uses the API, and how the custom [File Picker](/features/file-picker) behaves.

## Confluence Structure vs StackOne Model

| Confluence Concept | StackOne Equivalent | Notes |
| - | - | - |
| **Space** | `drive` | Top-level container for content within a site |
| **Page with children** | `folder/file` | A 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.

### Navigation Flow

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 Object | How It Maps to Confluence |
| - | - |
| `drive` | A Confluence **space** |
| `folder` | A **page** with child pages |
| `file` | A **page** with content or an attached document |
| `metadata` | Indicates if an item has `hasContent`, `hasChildren`, or both |
| `path` | Virtualized 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.

| Operation | API Used | Notes |
| - | - | - |
| List sites | Configured in StackOne per connected account | No Confluence API call; configuration-level |
| List spaces in site | `GET /wiki/rest/api/space` | Lists all available spaces |
| List pages in a space | `GET /wiki/rest/api/content/search?cql=...` | Filters top-level or nested pages using CQL |
| Upload attachment to page | `POST /api/v2/pages` | Used for file uploads |
| Download attachment | `GET rest/api/content/{id}?expand=body.export_view` | Direct 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

| Type | Displayed As | Condition |
| - | - | - |
| Page with body | File (can be selected) | `body.storage.value` present |
| Page with children | Folder (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 and authentication

* **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

| Area | Confluence |
| - | - |
| Picker UX | Custom-built hierarchical UI |
| Root Model | Site → Space → Page (acts as file/folder) |
| File API | CQL-based search of pages and attachments |
| Folder Behavior | Pages act as folders if they contain child pages |
| File Behavior | Pages act as files if they have content or attachments |
| Selection Logic | Pages can be both selectable and expandable simultaneously |
| StackOne Normalization | All content mapped to unified `file` / `folder` objects |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.