communication api_usage ai_generated true

Confluence API content renders incorrectly or loses formatting when using wrong format type

ID: communication/confluence-storage-vs-editor-format

Also available as: JSON · Markdown
82%Fix Rate
85%Confidence
3Evidence
2023-01-01First Seen

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
any active — — —

Root Cause

Confluence has two content formats: 'storage' (XHTML-based, what the API returns) and 'editor' (what users see). They are NOT interchangeable. Posting editor format to storage API corrupts content. Macros use storage format exclusively.

generic

Workarounds

  1. 92% success Use Confluence REST API's body.view for rendered HTML, body.storage for editing 
    GET /content/123?expand=body.view  # rendered HTML for display; body.storage for programmatic editing
  2. 88% success Use the /contentbody/convert endpoint to transform between formats 
    POST /contentbody/convert/storage {value: '<p>text</p>', representation: 'editor'}  # converts editor -> storage
  3. 82% success Use Atlassian Document Format (ADF) for Confluence Cloud v2 API 
    Confluence Cloud v2 API uses ADF (JSON) instead of XHTML storage format. Check API version before choosing format.

Dead Ends

Common approaches that don't work:

  1. Post HTML directly to Confluence API body.storage.value 85% fail

    Confluence storage format is NOT regular HTML. It uses custom XHTML with ac: and ri: namespaces for macros. Regular HTML tags may work but macros, tables, and mentions require storage format.

  2. Read content from API and display directly as HTML in another app 82% fail

    Storage format contains Confluence-specific XHTML (ac:structured-macro, ri:attachment). Rendering this as HTML in a non-Confluence context shows broken markup.