Confluence to Slab Migration: The CTO's Technical Guide

Slab has a native Confluence importer — one of the few wiki-to-wiki migration paths that actually exists as a built-in feature. You upload a Confluence XML space backup, Slab processes it server-side, and you get a confirmation email 1–3 days later. The catch: macros, page-level permissions, and embedded content without a Slab equivalent are silently dropped. For small, mostly-text Confluence spaces, the native importer works. For anything with complex macros, deep page trees, or hundreds of attachments, you need either a custom API pipeline or a managed migration service. (help.slab.com)

This guide covers the data model differences between Confluence and Slab, the real constraints of each migration approach, the API rate limits on both sides, and the edge cases that break most DIY attempts.

Why Engineering Teams Move from Confluence to Slab

Teams don't leave Confluence because they hate wikis. They leave because Confluence got too heavy for how they actually work. The triggers we see most often:

• Confluence's macro debt. Years of third-party macros, Jira macros, and custom templates create pages that are more macro scaffold than content. When half your pages depend on plugins to render, the editing experience degrades. Slab's clean editor is the antidote.
• Cost consolidation. Confluence Cloud pricing scales per user, and once you add Atlassian Guard (formerly Access) for SSO and security controls, costs compound. Slab's per-user pricing is typically lower for teams that only need a knowledge base — not the full Atlassian suite.
• Simplicity over configurability. Slab is intentionally opinionated: a clean editor, fast unified search, and a flat learning curve. For teams that don't need Confluence's deep Jira integration, the complexity is overhead.
• Search quality. Slab's unified search indexes content across integrated tools (Slack, GitHub, Google Drive). Confluence's built-in search has been a persistent complaint in the Atlassian community, particularly for large instances.

Real adoption patterns confirm this. Vevo moved away from Confluence citing SSO friction and a bloated UI. Render emphasized Slab's responsiveness and fast integrated search. Asana moved internal knowledge bases into Slab to reduce clicks and improve discoverability. (slab.com)

The technical risk in any wiki migration is losing document structure, internal links, macros, and formatting. Confluence and Slab have fundamentally different content models — and that mismatch is where most migrations silently fail.

Data Model Mapping: Confluence Objects vs. Slab Equivalents

Before choosing a migration method, you need to understand what maps and what doesn't.

Confluence's content model is built around Spaces (isolated containers with their own page tree, permissions, and settings), Pages (strict parent-child hierarchy within a single space), Blog Posts, Comments, Attachments, and Labels. Content is stored in Confluence Storage Format — an XHTML-based markup with embedded macro definitions. (confluence.atlassian.com)

Slab's content model is built on Topics (flexible groupings that can be hierarchical) and Posts (individual documents). Slab is built on Quill, the open-source rich text editor that Slab itself develops and maintains. Internally, content is stored using Quill's Delta format — a JSON-based rich text specification. Posts can belong to multiple Topics, which makes Slab more flexible than a pure folder tree, but it is not a macro engine or a custom-content platform.

Migrate by immutable source IDs, not page titles. Record a source_page_id → target_post_url mapping from the start.

For a deeper look at Confluence export limitations across all formats, see our guide on how to export all data from Confluence. For the reverse-direction Slab API nuances, our Slab to Confluence migration guide is the closest companion read.

Migration Approaches: Native Import vs. API Pipeline vs. Managed Service

There are four viable paths. Each has a different cost, complexity, and fidelity profile.

Method 1: Slab's Native Confluence Importer

How it works: Export your Confluence space as an XML backup. Upload the ZIP file to Slab via Team Settings → Import & Export → Confluence → Import. Slab processes it server-side and sends a confirmation email when complete. (help.slab.com)

Step-by-step:

1. In Confluence, go to Space Settings → Export Space → XML → Full Export
2. Download the generated ZIP file
3. In Slab, navigate to Team Settings → Import & Export
4. Click Import on the Confluence option
5. Upload the ZIP file
6. Wait 1–3 days for processing
7. Receive confirmation email and verify results

When to use it: Small to mid-size spaces (under ~500 pages) that are primarily text content with simple formatting. Minimal macro usage. No hard deadline.

Method 2: File-Based Import (HTML or Markdown ZIP)

How it works: Export or transform Confluence content into HTML or Markdown files, zip them, and import via Slab's file importer. Folders in the ZIP become topics. (help.slab.com)

When to use it: You want selective migration or need to pre-clean content before loading. Useful when the native Confluence importer drops too much formatting and you want to control the transformation step yourself without building a full API pipeline.

Method 3: Custom API Pipeline (Confluence REST → Slab GraphQL)

How it works: Extract content from Confluence using its REST API (v1 or v2), transform the content from Confluence Storage Format to Markdown or Quill Delta, then push it into Slab via the GraphQL API. (developer.atlassian.com)

When to use it: Complex migrations where you need control over content transformation, macro handling, link rewriting, or incremental sync. Requires dedicated engineering time — budget 2–4 weeks for a senior engineer including testing and validation.

Method 4: Managed Migration Service

How it works: A migration partner (like ClonePartner) connects to both platforms via API, handles the extraction, transformation, and loading — including edge cases like macro content extraction, link rewriting, and attachment re-hosting.

When to use it: Large Confluence instances, tight timelines, teams without spare engineering bandwidth, or migrations where data fidelity is non-negotiable.

Comparison Summary

Which Approach for Your Scenario

• Small team, < 200 pages, minimal macros: Native importer. Accept the 1–3 day wait and plan for manual cleanup.
• Selective migration with pre-cleaning: File-based import. Transform to Markdown first, then upload.
• Enterprise, 1,000+ pages, macro-heavy: Managed service or custom API pipeline. The engineering cost of building and debugging a one-off migration script often exceeds the service fee.
• Engineering team with bandwidth, moderate complexity: Custom API pipeline. Budget 2–4 weeks including a full pilot and UAT cycle.
• Ongoing sync (running both platforms in parallel): API pipeline or managed service with delta sync. Neither the native importer nor file-based import supports incremental updates.

Navigating API Limits: Confluence REST vs. Slab GraphQL

If you're building a custom pipeline or evaluating a migration partner's approach, understanding the API constraints on both sides is non-negotiable.

Confluence Cloud REST API

Atlassian enforces rate limits that vary by authentication method. This distinction matters for migration scripts:

For Forge, Connect, and OAuth 2.0 apps: As of March 2, 2026, Atlassian enforces point-based quota rate limits. Each API call consumes points based on the computational work it performs — not a simple request count. Default Global Pool quota is 65,000 points per hour, resetting at the top of each UTC hour. Once exhausted, all requests return HTTP 429 until the next reset window. (developer.atlassian.com)

For API token traffic (basic auth): API token-based requests are not subject to the new point-based quotas. They continue under existing burst rate limits, evaluated over short time windows (seconds), independent of hourly quotas. (support.atlassian.com)

API token expiry: Atlassian API tokens now expire by default after one year. Tokens created before the December 15, 2024 policy change expired between March 14 and May 12, 2026. Verify your migration credentials before cutover week.

The N+1 problem: The v2 API separates nested properties into distinct endpoints. Fetching a page, its attachments, and its labels requires at minimum three sequential API calls per page. For a 1,000-page space, that's 3,000+ requests before you start downloading attachment binaries. (developer.atlassian.com)

# Fetching a page's content (v2)
GET /wiki/api/v2/pages/{page_id}?body-format=storage

# Fetching its attachments (separate call)
GET /wiki/api/v2/pages/{page_id}/attachments

# Fetching its labels (another separate call)
GET /wiki/api/v2/pages/{page_id}/labels

Rate limit response headers to parse:

HTTP/1.1 429 Too Many Requests
Retry-After: 1847
X-RateLimit-Limit: 40000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 2026-05-19T15:00:00Z

Use exponential backoff with jitter. Start with a 1-second base delay and double after each retry. Cap at 4 retries (5 total attempts). Distribute requests evenly across the hour rather than bursting.

Slab's GraphQL API

Slab exposes a GraphQL API at https://api.slab.com/v1/graphql. Key constraints:

• Plan gating: Only available on Business or Enterprise plans. Free and Startup plans cannot use the API. (help.slab.com)
• Authentication: Bearer token generated in Team Settings → Developer Tools. All requests execute as the Slab Bot user — content visibility is limited to what Slab Bot can access.
• Rate limiting: Complexity-based with a 1,000 complexity points per minute ceiling, enforced via a token bucket algorithm. Scalar fields cost 0 points, objects cost 1, and many-to-many relations cost 2 — with costs multiplying for nested relations. A simple query for post titles might cost 5–10 points. A deep query fetching content with topic metadata and user details can cost 50–100+ points.
• No bulk import endpoint. You create posts one at a time via mutations.
• Content format: Posts are stored internally in Quill Delta format (JSON). The API can return content as Markdown via the content field.

For a detailed breakdown of Slab's GraphQL complexity scoring model, see our Slab to Notion migration guide.

Handling Edge Cases: Macros, Attachments, Internal Links, and Permissions

This is where most Confluence migrations — to any platform — silently lose data.

Confluence Macros

Slab has no macro system. Every Confluence macro needs an explicit decision:

The same macro simplification problem shows up in other Confluence migrations. Our Confluence to SharePoint migration guide covers additional translation patterns that apply here too.

Attachments

Confluence stores attachments at the page level. Slab embeds files inline within posts. Your migration needs to:

1. Download each attachment from Confluence (via REST API or XML export)
2. Upload it to Slab (inline in the post body or as a linked file)
3. Update references in the post content to point to the new Slab location

Images referenced by URL in Confluence Storage Format need to be re-hosted — they may point to your Confluence instance, which will be decommissioned post-migration.

Watch for Slab's attachment size limits: 10 MB on Free, 25 MB on Startup, 100 MB on Business, and custom on Enterprise. Run an attachment preflight check if your Confluence spaces contain large PDFs or archives.

Internal Links

Confluence internal links use page IDs or space-key + page-title patterns. After migration, every internal link is broken unless you rewrite them.

The two-pass approach:

1. Pass 1: Migrate all pages. Record a mapping of confluence_page_id → slab_post_url.
2. Pass 2: Walk every migrated post, find links matching Confluence URL patterns, and replace them with Slab post URLs using your mapping table.

With the native importer, Slab attempts to resolve internal links within the imported space. Cross-space links and links to content that wasn't imported will break.

Slab supports links to posts and to specific post headings, but section anchors need testing — permission rules still apply, so validate links with real end-user accounts, not admin sessions. (help.slab.com)

Permissions

Confluence has page-level restrictions. Slab has topic-level permissions: Open, Private, Secret, and Public. You cannot restrict access to individual posts — only to the topic they belong to. (help.slab.com)

Slab's access model is additive — when a post belongs to multiple topics, any user with access to any of those topics can see the post. This is not the same as copying Confluence page restrictions one-for-one. Model target access intentionally, test with real user accounts, and document every compromise you make.

Step-by-Step Migration Process

Pre-Migration Planning

1. Audit your Confluence content.

• Count pages, blog posts, and attachments per space
• Identify pages with complex macros (use CQL: type = page AND macro = "jira")
• Flag pages with unpublished drafts (REST API status=draft filter)
• List cross-space links that will break if you migrate spaces individually
• Document per-page restrictions that need topic-level redesign
• Identify non-page content types (databases, whiteboards) requiring separate handling

2. Define migration scope.

• Decide which spaces to migrate vs. archive vs. abandon. Do not migrate garbage — archive pages untouched in the last 24 months.
• Set macro handling policy: extract content, flag for manual review, or drop
• Design your target Slab topic hierarchy
• Build a conversion matrix for every non-page content type before you start loading data

3. Choose your migration strategy.

• Big bang: Migrate everything at once. Simpler, but requires a maintenance window.
• Phased by space: Migrate one space at a time. Reduces risk, extends timeline.
• Incremental with delta sync: Migrate bulk content, then sync changes until cutover. No downtime. Requires API pipeline.

4. Run a pilot migration. Migrate 2–3 representative spaces (one simple, one complex, one with heavy macros) using your chosen method. Pick the ugliest content for your pilot — pages with nested tables, macros, attachments, internal links, and permission edge cases. Clean pages don't reveal anything useful. Validate formatting, links, attachments, and permissions before committing to a full migration.

5. Back up everything. Export every Confluence space to XML and download the files before starting. This is your rollback safety net.

Migration Architecture: Extract → Transform → Load

For API-based migrations, the data flow follows a standard ETL pattern:

┌──────────────┐     ┌───────────────┐     ┌────────────┐
│  Confluence   │────▶│   Transform   │────▶│    Slab     │
│  REST API v2  │     │   Pipeline    │     │ GraphQL API│
└──────────────┘     └───────────────┘     └────────────┘
       │                     │                     │
   Extract:              Transform:             Load:
   - Pages + content     - Storage → Markdown   - Create topics
   - Attachments         - Macro extraction     - Create posts
   - Labels              - Link mapping table   - Upload attachments
   - Page tree           - Image re-hosting     - Rewrite links

Do not stream directly from Confluence to Slab. Extract into a local database or JSON store first. This prevents API timeouts on either side from breaking the entire pipeline.

import requests
import time
 
# --- Configuration ---
CONFLUENCE_BASE = "https://your-site.atlassian.net/wiki/api/v2"
CONFLUENCE_AUTH = ("email@example.com", "api-token")
SLAB_API = "https://api.slab.com/v1/graphql"
SLAB_TOKEN = "your-slab-token"
 
# --- Step 1: Extract pages from Confluence ---
def extract_confluence_pages(space_id):
    pages = []
    url = f"{CONFLUENCE_BASE}/spaces/{space_id}/pages?limit=50&body-format=storage"
    while url:
        resp = requests.get(url, auth=CONFLUENCE_AUTH)
        if resp.status_code == 429:
            retry_after = int(resp.headers.get("Retry-After", 60))
            time.sleep(retry_after)
            continue
        data = resp.json()
        pages.extend(data.get("results", []))
        url = data.get("_links", {}).get("next")
    return pages
 
# --- Step 2: Transform content ---
def confluence_storage_to_markdown(storage_html):
    """Convert Confluence Storage Format to Markdown.
    Use a library like markdownify or a custom parser.
    Handle macros, tables, and embeds explicitly."""
    # Implementation depends on your macro handling policy
    pass
 
# --- Step 3: Load into Slab ---
def create_slab_post(title, markdown_content, topic_id):
    query = """
    mutation CreatePost($title: String!, $content: String!, $topicId: ID) {
        createPost(title: $title, content: $content, topicId: $topicId) {
            id
            url
        }
    }
    """
    variables = {
        "title": title,
        "content": markdown_content,
        "topicId": topic_id
    }
    headers = {"Authorization": f"Bearer {SLAB_TOKEN}"}
    resp = requests.post(
        SLAB_API,
        json={"query": query, "variables": variables},
        headers=headers
    )
    if resp.status_code == 429:
        time.sleep(60)  # Respect Slab's complexity limit
        return create_slab_post(title, markdown_content, topic_id)
    return resp.json()

Validation and Testing

Migration isn't done when the last post is created. Validation is where you catch the silent failures.

Record-count comparison:

• Pages in Confluence vs. posts in Slab per topic
• Attachments uploaded vs. attachments in source
• Blog posts migrated vs. blog posts in Confluence

Content spot-check:

• Sample 10–15% of posts across all complexity levels
• Verify: headings, code blocks, tables, images render correctly
• Check for macro content that was supposed to be extracted
• Confirm callout/panel formatting survived

Link validation:

• Test every internal link in the sampled posts
• Check for orphaned links pointing to content that wasn't migrated
• Verify cross-topic links resolve correctly

Permission audit:

• Confirm topic permissions match the intended access model
• Test with non-admin users to verify secret topic visibility

Rollback plan:

• Keep Confluence live and read-only during validation
• Set a go/no-go checkpoint with clear criteria
• If rollback is needed, Confluence XML backups are your restore path

Post-Migration Checklist

• Redirect old Confluence URLs to Slab (via DNS, reverse proxy, or browser extension for internal users)
• Decommission Confluence integrations replaced by Slab integrations
• Set up Slab's Jira integration if your team still uses Jira
• Recreate any critical Confluence page templates as reusable Slab posts (manual process)
• Train users on Slab's editor, search, and topic structure
• Monitor Slab for the first 2 weeks — users will discover missing content, broken links, or formatting issues that sampling didn't catch
• Cancel or downgrade your Confluence subscription only after the monitoring period

Best Practices for Confluence to Slab Migration

• Back up before migrating. Export every Confluence space to XML and store the files off-instance.
• Pilot on ugly content. Test with pages that have nested tables, macros, attachments, and internal links. Clean pages don't tell you anything useful.
• Validate incrementally. Check each space's output before moving to the next.
• Automate repetitive transforms. Macro extraction rules, link patterns, and content normalization should be scripted, not manual.
• Don't migrate everything. Audit for stale, outdated, or duplicate pages before migration. Moving garbage to a new platform doesn't make it less garbage.
• Communicate the change. Users need advance notice, a clear timeline, and training on Slab's different organizational model.
• Plan for the macro gap. Document which macros are being dropped, which are being converted, and which require manual recreation. Share this list with content owners before cutover.

For a broader framework on knowledge base migration planning, see our knowledge base migration checklist.

When to Use a Managed Migration Service

DIY makes sense when the migration is small, the content is simple, and your team has engineering capacity to spare. It stops making sense when:

• Your Confluence instance has 1,000+ pages across multiple spaces
• You have heavy macro usage requiring custom extraction logic per macro type
• You're on a tight timeline (weeks, not months)
• Your engineering team is already at capacity on product work
• Data fidelity is non-negotiable — every link, every attachment, every piece of content must survive

The hidden cost of in-house migration is engineer distraction. A senior engineer spending 3–4 weeks on a migration pipeline is 3–4 weeks not shipping product features. We covered this dynamic in detail in our post on how in-house migrations silently kill product velocity.

At ClonePartner, we've built extraction and transformation pipelines for knowledge base migrations across Confluence, Notion, SharePoint, Coda, and Slab. We handle the API rate limit choreography, macro content extraction, link rewriting, and attachment re-hosting — so your engineers stay focused on product work. Our approach is API-first and zero-downtime: your team keeps using Confluence until final cutover, with a delta sync to capture changes made during the migration window.