RFC-10: Confluence Whiteboards

Hi @MartinKistnerDecadis - thanks for sharing the context and your questions! We’re glad to hear that your team is considering how to move forward with our APIs. To answer your questions:

Why are the whiteboards currently included as children but not at the root level in the existing v1 endpoint (“/wiki/rest/api/space/{spaceKey}/content”)?

Whiteboards were included as children but not at the root level due to technical limitations with introducing whiteboards into the content tree (f.k.a. page tree). We are planning on making minimal updates to the v1 endpoints, as our focus moving forward will on building on top of our new v2 API.

A quick question for you: Why & how does having whiteboards returned as children from other endpoints, but not returned from this endpoint severely affect your app? Looking for your feedback here to help inform our v2 API development.

Will there be any v2 entry points specifically for whiteboards or will they be combined with the existing page’s rest endpoint?

Yes, we will have whiteboard specific endpoints, that will be separate from page ones, and part of the v2 API.

When is the official rollout of this functionality planned?

When will we be informed about it as an app vendor?

Will there be more guidance provided in terms of an API v1 to v2 Migration guide in general?

We don’t yet have the answers for these questions; getting whiteboards fully supported in our APIs is still a work in progress. We want to keep you informed and provide accurate information, so we will update you as soon as we gather more data and have specific details to share.


:star: Overall for all of our partners here, to handle any breaking change with this latest release, we currently recommend:

  1. To minimize API usage specific to whiteboards (ex. whiteboards specific expands) as much as possible; the existing APIs exposing them are prone to further changes and we are not yet ready to support apps integrating with whiteboards via our API just yet.
  2. If possible, update the app(s) to handle errors related to whiteboards gracefully.
    • For example: previously, apps might have assumed certain requests only returned content of type Page, but this assumption will no longer hold true with whiteboards. A couple of places where we can see this are content ancestors and children.
    • Note: Functionality tied to archiving or copying whiteboards or subtrees containing whiteboards are not supported at this time - and will be available in an upcoming release.
  3. Reach out to us if both 1. and 2. are not sufficient for handling the breaking changes – the team will work with you to resolve this.



Thanks, @KaiMunechika for your time and the information provided.

I would love to reach out to you and therefore created a more specific question here:

Yes, we will have whiteboard-specific endpoints, that will be separate from page ones, and part of the v2 API.

What would be the advantage of splitting the endpoints instead of using query parameters?
We would need this for our App we currently use the v1 endpoint described in my post above.
Will there be an endpoint to show the tree of how the content (whiteboards, pages are related to each other in a space like ancestors/children?

Thanks in advance!

I found an issue with the child endpoint that is affecting our app. Say we have the following content tree, with a whiteboard that has two children: a regular page and another whiteboard.

  • Whiteboard A
    • Page A
    • Whiteboard B

I assumed that the following request (for the children of Whiteboard A) would return Page A because I only expand the page type, but the request returns an empty array: /wiki/rest/api/content/{whiteboard-a}/child?expand=page. When I expand whiteboard instead of page, the request returns Page A and Whiteboard B.

If a page contains both regular pages and whiteboards, it’s the other way around. Take this content tree, for example:

  • Page A
    • Whiteboard A
    • Page B

Requesting the child pages of Page A (expand=child) returns Whiteboard A and Page B, whereas requesting child whiteboards (expand=whiteboard) returns an empty array.

Am I misunderstanding something here or is that a bug?


Hey @MartinKistnerDecadis ,

What would be the advantage of splitting the endpoints instead of using query parameters?

In the REST API V2, endpoints are specialized and return more specific data types to provide a number of benefits, including better latency and ease-of-understanding. You can read more about the benefits in this blog. As a result, because whiteboards and pages are different data types, we will release separate endpoints for them.

Will there be an endpoint to show the tree of how the content (whiteboards, pages are related to each other in a space like ancestors/children?

Yes, we intend to release an endpoint at some point to return the content hierarchy.

1 Like

Hi @klaussner :wave:

Yes, this is a bug! Thank you for flagging this, the team and I are working on a fix for it now. Once our fix is in and deployed, the behavior will be:

  • Calling /wiki/rest/api/content/{whiteboard}/child?expand={whiteboard OR page} will return an empty array; in other words, the child expand for whiteboards will always return an empty array.
  • Calling /wiki/rest/api/content/{page}/child?expand=page will only return pages; we’ll filter out whiteboards here.
  • Calling /wiki/rest/api/content/{page}/child?expand=whiteboard will continue to return an empty array

Thanks again for raising this, I’ll share another update letting you know once the fix is deployed to prod.


Hey @LucasPan, thanks for the quick response and the explanations :slight_smile: .

Yes, we intend to release an endpoint at some point to return the content hierarchy.

→ That’s pretty nice to hear :slight_smile: Do you have any information if this will happen before or after V1 deprecation?

Hi @MartinKistnerDecadis , unfortunately at this time we do not have any estimated timeline for this endpoint.

1 Like

Hi @AbhinavSingh,

We’re testing whiteboards currently, think it’s a great idea to have this functionality within confluence.

A couple of issues I have ran into for feeback:

  • Tool bar does not display properly when on my Macbook. It is half cut off meaning I cannot see the tool icons properly (screenshot added). Responsive display seems to be working as zooming out does not fix it.

  • Sticky notes appear to have a larger minimum size than shapes, meaning they can’t be scaled down to match effectively. I found this out after having created a framework which would now all need enlarged to fit more than one or two notes around a shape.


1 Like

Hi @KaiMunechika ,
Are there any plans to add a filter for type to just return pages on this rest API ? Since this API now also sends back whiteboards which causes troubles in expanding? Cause currently it breaks our app whenever someone opt-in to this feature.

REST API i am talking about:


Hi @ChrisMurray ,

Re: first point, thanks for flagging this UI bug! The team is looking into fixing this, but if you’d like to have a temporary fix, then clicking the “dismiss” button in that blue banner should shift the whiteboard view back up and fill the screen.

Re: second point, I’ve shared this with the Whiteboards team and having them take a look. Thank you for the valuable context and feedback!


Hi @MartinKistnerDecadis ,

Have you tried the following REST API:

It looks like this one would solve the problem; it returns all content in the specified space (like the one you linked), but only those having the specified type (which would be page in your case).

I’ve verified with some testing that whiteboards are not leaked through this API when using the page type in the request, but let me know if that’s not holding true for you. Cheers!

1 Like

hey @KaiMunechika ,
thank you very much for the quick response :).
Can you confirm that the type filter is also applied if we expand the following endpoint by ancestors and children? Meaning they are also both only of type page? Because for us the whiteboards came can the expanded options also be filtered?


Thank you very much in advance.

Hi @klaussner

Our fix for this has been deployed to prod. The behavior is slightly different from what I described here and is as follows:

  • Calling /wiki/rest/api/content/{whiteboard}/child?expand=page returns an empty array
  • Calling /wiki/rest/api/content/{whiteboard}/child?expand=whiteboard returns only whiteboards
  • Calling /wiki/rest/api/content/{page}/child?expand=page returns only pages
  • Calling /wiki/rest/api/content/{page}/child?expand=whiteboard returns an empty array

Please let us know if you’re still seeing issues with this endpoint (or any other endpoint) in your app - cheers!

1 Like

Hi @MartinKistnerDecadis

Happy to help! And yes, you’re right. For a space with whiteboards throughout the content tree (as root level node, as child node, etc.), in our latest prod release, I’m seeing that in /wiki/rest/api/space/{spaceKey}/content/page?expand=space,ancestors,children.page. :

  • whiteboards are returned as ancestors, not being filtered out
  • whiteboards are not returned otherwise in the response

We have a mitigation where we can filter out whiteboards from the ancestors response from specified Ecosystem apps. If you share your apps’ AppAccountId with us (whether it be here in the thread, through a message, through email - you can reach me at kmunechika@atlassian.com, etc.), I’ll be happy to apply it for you!

1 Like

Hi all!

Copy is now available for whiteboards :tada:

What is updated?
Copy is now supported for a single whiteboard, a content tree containing whiteboards (both as parent and child), and Whiteboards as copy destinations.

This functionality is available through the copy page hierarchy REST endpoint:

Copy functionality will be enabled for Whiteboards user by the end of this week. If your apps use Copy, please check that these changes work as expected, and let us know if you have questions or issues.



We have a connect app which renders a web panel "location": "atl.page.metadata.banner" on pages. Will the same connect module locations be exist for whiteboards as they are on pages?

Thank you!

@JeromeParramoredev thank you for the question. The alt.page.metadata.banner mount point is in the header on Pages and Blog Posts. Whiteboards have a different header and as such do not have that mount point. You could consider using alt.general if you want a mount point available to Whiteboards also.

On behalf of the team, we thank the community for your valuable feedback on this Confluence Whiteboards RFC. Your input has influenced our approach to the Whiteboards feature and enabled us to successfully launch it to beta.

The intermediary whiteboard API changes mentioned in this post have been communicated through the Confluence Cloud Changelog. In the future, as we build support for Whiteboard v2 APIs we will keep you updated.

If you have any further questions or concerns, please do not hesitate to reach out. Thank you again for your help!

1 Like