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

Integration boundary

We 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 uncertain

From 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.

Questions

• For 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?