Currently, the Confluence REST API v2 (specifically the PUT /wiki/api/v2/pages/

endpoint) presents several limitations that prevent third-party applications and AI tools (like Kiro) from reliably updating page content without data loss or excessive complexity.

Key Issues:
Lack of HTML/Storage Format Support: Unlike API v1, API v2 only accepts Markdown or Atlassian Document Format (ADF). Many external tools generate content in HTML, which cannot be sent directly to v2, forcing a conversion that often fails or loses data.

Low Fidelity in Markdown Conversion: When sending Markdown to the v2 endpoint, the server-side conversion to ADF frequently strips out rich formatting. Specifically, complex elements like nested lists, panels, line breaks, and bullet points inside table cells are often flattened or removed.

ADF Complexity for Dynamic Content: While ADF is the native format, its extreme verbosity (e.g., a small table can result in hundreds of lines of JSON) makes it impractical for AI models or lightweight integrations to generate reliably without errors.

Version Bloat for Property Updates: Updating non-content properties (like the page owner) via the v2 endpoint currently requires sending the entire body and results in a new page version, which is inconsistent with UI behavior.

Proposed Improvements:
Support Storage Format in v2: Allow the body parameter in API v2 to accept storage (XHTML) format, similar to API v1.

Improve Markdown Parser: Enhance the server-side Markdown-to-ADF converter to support nested structures and rich formatting within tables.

Partial Updates: Allow updating page metadata (owner, title, etc.) without requiring the full content body or triggering a new version.