--- title: "Slack Canvas to Confluence Migration: APIs, Limits & Mapping" slug: slack-canvas-to-confluence-migration-apis-limits-mapping date: 2026-10-01 author: Abdul Aleem categories: [Slack Canvas, Confluence, Migration Guide] excerpt: "Slack Canvas stores no hierarchy, folders, or ordering. Migrating to Confluence means manufacturing structure, converting markdown to XHTML, and handling every gap Canvas never filled." tldr: "Slack Canvas has no page tree, no version import path, and no export wizard. Migration to Confluence requires building structure from channel relationships and converting markdown to storage format XHTML." canonical: https://clonepartner.com/blog/slack-canvas-to-confluence-migration-apis-limits-mapping --- # Slack Canvas to Confluence Migration: APIs, Limits & Mapping # Slack Canvas to Confluence Migration: APIs, Limits & Mapping Migrating from Slack Canvas to Confluence is not a data migration — it is a data manufacturing job. Canvas stores almost no structural metadata: no parent-child relationships, no folder paths, no sibling ordering. The hierarchy you want in Confluence has to be designed by your team, not extracted from the source. Just as with [migrating from Confluence to Slack Canvas](https://clonepartner.com/blog/blog/confluence-to-slack-canvas-migration-the-technical-guide), there is no export wizard, no Atlassian importer, and no third-party connector. You read canvases through the Slack API, convert markdown to Confluence's XHTML-based storage format, and push pages through the Confluence REST API — handling every structural and formatting gap along the way. This guide covers the full technical path: inventory, structure derivation, format conversion, comment handling, version history limits, and attachment re-upload. ## How Do You List All Slack Canvases? **There is no `canvases.list` endpoint.** Whether you are moving to Confluence or [migrating Slack Canvas to Notion](https://clonepartner.com/blog/blog/slack-canvas-to-notion-migration-api-limits-data-mapping), the only programmatic way to enumerate canvases across a Slack workspace is the [`files.list`](https://docs.slack.dev/reference/methods/files.list/) method filtered to the `canvas` type. ```bash curl -s "https://slack.com/api/files.list?types=canvas&count=100" \ -H "Authorization: Bearer $SLACK_TOKEN" ``` `files.list` is a **Tier 3 endpoint**. Slack's Tier 3 rate limit is defined as 1 call per second per app per workspace, with burst tolerance — not a flat 50 requests per minute. In practice, sustained crawls at 50 requests per minute stay within Tier 3 headroom, but the actual throttle is per-app-per-workspace and will vary under concurrent load. Results are paginated at a default of 100 items per page. Each result is a file object with `id`, `title`, `created`, `updated`, and the channels it was shared into — but no parent reference, no folder path, and no sort order. > [!WARNING] > **Scope matters.** A bot token with `files:read` only sees canvases in channels the bot has been added to. A user token sees canvases the user can access. For a complete inventory, use an admin-level user token (Enterprise Grid supports Org-Level User Tokens with admin privileges) or programmatically add the migration bot to all channels before running the crawl. Canvases in private channels or DMs the token cannot reach will silently be missing from results. To read the actual content of a canvas, you need the `canvases:read` scope. Use `files.info` to get the download URL, or `canvases.sections.lookup` to query specific sections. The content comes back as markdown — not HTML, not JSON blocks. Slack caps canvas content at **1 MiB per `document_content` object**. ([docs.slack.dev](https://docs.slack.dev/surfaces/canvases/)) If you are working from **Slack exports** instead of live API calls, the export format gives you a second inventory surface: `canvases.json`. That file contains each canvas's metadata, a `url_private_download` value for retrieving the content, and a `shares` array showing where the canvas was shared. Comments on canvases are exported separately and must be correlated through `file_conversations.json` and the matching `FC:` folder. ([slack.com](https://slack.com/help/articles/220556107-How-to-read-Slack-data-exports)) ### What metadata does a canvas carry? | Field | What it tells you | What it does not tell you | |---|---|---| | `id` | Unique file ID (starts with `F`) | — | | `title` | Canvas title | No guaranteed uniqueness | | `channels` | Channel IDs where canvas was shared | No hierarchy or ordering | | `created` / `updated` | Timestamps | No version count | | `user` | Creator's Slack user ID | No "owner" vs "editor" distinction | | `is_channel_space` / `linked_channel_id` | Whether this is a channel-native canvas | — | There is no `parent_id`, no `folder`, no `position`, and no `space` equivalent. A canvas is a flat object floating in Slack's file system. Every bit of hierarchy you need in Confluence must be derived or decided. > [!NOTE] > **Canvas format change:** Slack began converting channel and DM canvases to canvases in tabs on April 9, 2025. Depending on when you migrate, expect a mixed estate: converted channel-linked canvases from the older model plus standalone canvases shared into channel tabs. The share relationship is still the best structural signal you get from the source. ([slack.com](https://slack.com/help/articles/21290478840979-Feature-change-notice--Channel-canvases)) ## Channel Canvases vs. Standalone Canvases **A channel canvas is the single built-in canvas attached to a Slack channel.** Every channel and DM gets exactly one. It is created via `conversations.canvases.create`, and calling that method a second time on the same channel returns a `channel_canvas_already_exists` error. Access is tied to channel membership — no separate sharing needed. **A standalone canvas is a free-floating document** created via `canvases.create`. It belongs to the user who created it and is invisible to everyone else until explicitly shared to channels or users via `canvases.access.set`. Standalone canvases require a paid Slack plan. For migration inventory, this distinction matters because: - Each channel contributes **at most one channel canvas** plus **zero or more standalone canvases** that were shared into it. - The `channels` array on a file object tells you which channels a standalone canvas was shared into — this share relationship is the closest thing to structure the Slack API gives you. - A standalone canvas shared into multiple channels appears in `files.list` once but has multiple channel IDs, so you need to decide which Confluence parent page it belongs under. - The `is_channel_space` and `linked_channel_id` fields let you programmatically separate channel canvases from standalone canvases shared into conversations. ([docs.slack.dev](https://docs.slack.dev/reference/objects/file-object/)) ## The Confluence Page Tree Is a Decision, Not Data You Migrate Slack Canvas has no concept of a page tree. [Confluence is built around a strict space → page → child page hierarchy](https://clonepartner.com/blog/blog/slack-canvas-vs-confluence-architecture-limits-and-migration). Your migration team must **design** the Confluence structure based on signals from the source. Budget time for information architecture decisions before writing migration code. The page tree will not match any existing structure in Slack because that structure never existed. ### Four hierarchy-derivation strategies | Strategy | How it works | When to use it | Main risk | |---|---|---|---| | **Channel-per-space mapping** | Each Slack channel becomes a Confluence space (or top-level page). Channel canvas → space home page. Standalone canvases shared into that channel → child pages. | Clean channel taxonomy with minimal cross-sharing | Standalone canvases shared to many channels become ambiguous | | **Index canvas parsing** | Identify a "master" or "index" canvas with links to other canvases. Parse markdown links to derive ordering and grouping. | Workspaces with a known index document | Assumes index exists and is current; requires validation | | **Naming convention extraction** | Regex-parse titles like `[Project] - Design Spec` or `Q3 OKRs - Engineering` into a two-level hierarchy. | Workspaces with consistent naming discipline | Fragile — audit coverage before automating | | **Flat import + post-migration restructuring** | Import all canvases as siblings under a single parent. Let content owners organize in Confluence afterward. | Large volumes with unclear ownership | Pushes organizational work to content owners at a busy moment | If a standalone canvas is shared across multiple channels, you must decide whether to duplicate it in Confluence (creating maintenance overhead) or assign it to a single primary space. Assign based on the channel where it was first shared — use the earliest timestamp in the `shares` object — and generate Confluence cross-links for the other spaces. Slack sharing rules are not a clean fit for Confluence permissions. A canvas shared in a public channel becomes visible to everyone in the workspace or Enterprise org. Audit sharing intent manually rather than copying share relationships blindly into Confluence restrictions. ([slack.com](https://slack.com/help/articles/15678967614611-Manage-access-permissions-for-canvases-and-lists)) ## How to Convert Canvas Markdown to Confluence Storage Format **Confluence storage format** is Confluence's persisted XHTML-based body representation — XML with custom `ac:` and `ri:` namespace elements for macros, resource identifiers, and layouts. Canvas content is markdown. The conversion is the core technical work of this migration. The Slack Canvas API represents content as a `document_content` object with `type: "markdown"`. Do not write a markdown parser from scratch. Use an existing library (`markdown-it` for JavaScript, Python's `markdown` module) to produce HTML, then post-process the HTML into valid Confluence storage format. The post-processing layer handles Confluence-specific elements: `ac:structured-macro` for code blocks, `ac:link` for internal links, `ri:attachment` for inline images. ### Canvas element → Confluence storage format mapping | Canvas element | Confluence storage format | Edge case / constraint | |---|---|---| | `# H1` | `

` | Canvas max is H3; Confluence supports H1–H6 | | `## H2` | `

` | H4–H6 must be authored post-migration | | `### H3` | `

` | Deepest canvas heading level | | `**bold**` | `` | Straightforward | | `*italic*` | `` | Straightforward | | `~~strikethrough~~` | `` | Straightforward | | `- item` / `1. item` | `