Confluence Cloud REST API v1 and v2: choosing one version when pagination and body formats differ

Question

Integration boundaryWe are building a sync service that reads and occasionally updates pages on a Confluence Cloud site. Both supported API families are available: v1 (/rest/api/...) and v2 (/api/v2/...). They are not drop-in interchangeable, and we must pick a strategy before writing the client layer.Where we are uncertainFrom the documentation, v1 list endpoints use offset/limit pagination with a _links.next reference, while v2 uses opaque cursor-based pagination. Content bodies also differ: v1 returns body.storage or body.view via the expand parameter, whereas v2 restructures body handling and supports formats such as atlas_doc_format. Some v1 expansions appear to have no direct v2 equivalent, and we are unsure whether v2 currently covers every read/write operation our sync needs.Authentication is not the issue—API token basic auth or OAuth 2.0 works for both—so the decision is purely about payload and pagination semantics, plus long-term maintenance given that Atlassian directs new development toward v2.QuestionsFor a new Cloud integration, is it safer to standardize on v2 and accept coverage gaps, or mix v1 calls where v2 lacks equivalents?Can v1-style storage format still be written through v2 endpoints, or must content be converted to atlas_doc_format?Are v2 cursors safe to treat as short-lived only, i.e., never persisted between sync runs?

Tasadduq Burney · Answer

RecommendationStandardize on the v2 API and use v1 only for operations that have no v2 equivalent.
Confirmed facts
v1 list endpoints use offset/limit pagination with _links.next.
v2 list endpoints return an opaque cursor token in the response metadata.
v1 returns page content via expand=body.storage or body.view.
v2 returns content in atlas_doc_format by default and supports format=storage|view via a format query parameter.
Atlassian’s public roadmap states new feature development targets v2; v1 is maintained for backward compatibility.
v2 cursor tokens are documented as short‑lived and should not be persisted between request cycles.

Likely explanationMixing versions adds client complexity and can cause divergent error‑handling paths. If a required read or write relies on storage‑only constructs (certain macros, layout data, or raw storage) that cannot be expressed in atlas_doc_format, you will need to call v1 for those specific operations. Otherwise, v2 covers the full sync workload.
Steps to implement
Inventory every read/write operation your sync needs.
Map each operation to the corresponding v2 endpoint (list, get, create, update, delete).
Mark any operation that lacks a v2 equivalent or requires a v1‑only expansion.
For the gaps, create thin wrappers that call the v1 endpoint; keep error handling and logging separate from the v2 path.
Abstract pagination: use offset/limit for v1 wrappers and cursor tokens for v2 calls; never store a v2 cursor beyond the current request cycle.
Implement a body conversion layer: when writing via v2, transform storage format to atlas_doc_format (or use the format=storage parameter if your client can send raw storage and let v2 store it). When reading via v2, convert atlas_doc_format to storage/view if downstream expects v1‑style bodies.
Validate the conversion round‑trip in a test environment.

Missing diagnostic detailDo any of your sync operations require storage‑only features (e.g., specific macros, layout data, or raw storage) that cannot be represented in atlas_doc_format? If the answer is yes, you must retain v1 calls for those operations; if no, a pure v2 implementation is sufficient.

Confluence Cloud REST API v1 and v2: choosing one version when pagination and body formats differ

Integration boundary

Where we are uncertain

Questions

1 answer

Recommendation

Confirmed facts

Likely explanation

Steps to implement

Missing diagnostic detail

Your perspective belongs here.

0 question comments