RFC-10: Confluence Whiteboards

RFCs are a way for Atlassian to share what we’re working on with our valued developer community.

It’s a document for building shared understanding of a topic. It expresses a technical solution, but can also communicate how it should be built or even document standards. The most important aspect of an RFC is that a written specification facilitates feedback and drives consensus. It is not a tool for approving or committing to ideas, but more so a collaborative practice to shape an idea and to find serious flaws early.

Please respect our community guidelines : keep it welcoming and safe by commenting on the idea not the people (especially the author); keep it tidy by keeping on topic; empower the community by keeping comments constructive. Thanks!

Hello Team!

Summary of Project

We are planning to launch Confluence whiteboards to our customers. Currently a closed set of EAP customers (~300 customers) are testing the whiteboards and are getting incremental updates regularly. In one of the upcoming updates, we’ll be integrating whiteboards as a new content type within existing creation and navigation structures, including the page tree. This update would impact API responses for some of our existing APIs, and we’re mindful of the potential effects on your apps. We deeply value our partnership with you and would like to invite you to validate these changes in a staging environment to assess any impact on your apps. Your collaboration and feedback are essential to us as we work together to deliver a seamless experience to our mutual customers.

  • Publish: Apr 28 2023
  • Discuss: ~Jun 22 2023
  • Resolve: ~Jun 29 2023


Whiteboards are coming to Confluence!

We are excited to announce that we are introducing whiteboards as a new content type in Confluence, alongside pages and blogs. This new addition aims to enhance collaboration and foster better brainstorming sessions within your Confluence spaces. Check out the community announcement here: Introducing Confluence whiteboards! :tada:

Currently, whiteboards are available to a closed group of EAP customers (~300 customers) and we are shipping new features and updates to these customers through regular releases. We are hoping to go for wider Beta release in July. It would be an opt-in program, where site-admins can choose to enable whiteboards on their tenants.

Proposed Solution

In this post, we will provide important details about this upcoming change and what you need to know as an ecosystem developer.

What is changing in upcoming release?

In one of the upcoming releases, whiteboards would be added to Confluence’s current navigation structure. Here are the most relevant changes:

  • Whiteboards in the Content Tree (currently known as Page Tree)

    • The current Pages section would be renamed to Content
    • Whiteboards would co-exist in the page tree with other pages and can be added as either a parent or a child to the tree.
    • Whiteboards can be a parent node for both pages and other whiteboards.
    • Whiteboards can be added as a child to pages.
  • Content Actions (in the content tree) available for whiteboards

    • Several content actions such as Move, Delete, Copy, and Archive would be available in the upcoming and future releases.
    • Content Actions would work similarly as they currently work for Pages (including both Parent and Child nodes).
  • Whiteboard Creation

    • Whiteboards can be created similarly to pages’ creation mechanism
    • Whiteboards can be created both through the top navigation ‘Create’ button, and
      Global Create
    • through the “+” button next to Content in the space sidebar.
  • Whiteboard Permissions

    • The whiteboard permissions model would be similar to the pages model i.e.

    • Whiteboards would also inherit permissions from the parent in the content tree, if applicable.

When will this change take place?

As previously mentioned, these updates are being rolled out incrementally to the whiteboard EAP participants. We would like to provide you with more details on the timeline and availability.

  • EAP Release Timeline:
    • The above changes will be released to our EAP customers in the upcoming weeks, specifically at the end of May or early June.
  • Whiteboards Beta Release:
    • Once the whiteboards Beta becomes available for all customers (exact timeline TBD but tentatively July onwards), Confluence site administrators will have the option to opt-in and enable whiteboards for their users.
    • Along with the whiteboards, the associated changes in the navigation structure and content tree will also become available to those who opt-in.
    • It’s important to note that customers who choose not to opt-in for the whiteboards Beta will not see the above changes until whiteboards are officially released in General Availability (GA) later this year.


How it may affect you?

With the upcoming changes, some of our APIs would be updated now and in-future to include whiteboard-related information in the response. Examples of such APIs are:

  1. Rest APIs
    1. Endpoints that return children/descendants and ancestors for a Content that support the following expand parameters will be affected. E.g.
      i. ancestors :warning: - will now return whiteboards and pages in the response.
      ii. childTypes.all - this will not be impacted immediately but will include whiteboards in the future (when we GA)
    2. Endpoints under Content - children and descendants will not be impacted immediately but we will include whiteboards in the response when we GA.
    3. Content body expand will be empty for whiteboards /wiki/rest/api/content/{id}/expand=body.storage
  2. GraphQL APIs
    1. ConfluencePage.ancestor

Our current focus for EAP/Beta is to ensure that there is continuity with your apps with any introduced changes in the existing APIs. We are building fallback options in case of an adverse impact.

PS: We are currently not planning to support any whiteboards-specific APIs immediately and will include/announce them for GA.

How can you help?

As we prepare to go live with the upcoming changes for our Early Access Program (EAP) customers, we would like to seek your collaboration in validating and mitigating any potential impact that these changes may have on your applications.

  • To facilitate this process, we will provide you with all required changes in your Developer Canary Program. This will allow you to thoroughly test your applications and report back any impact or issues that you may encounter.
  • The timing for providing access is currently being finalized. We anticipate that it will be available in the second week of May. I would update the post with additional details as we have the staging environment ready for testing.

If your application is impacted by the changes, we are looking forward to working together with you to resolve any issues before releasing the whiteboards Beta to our shared customers.


Will there be any updates to the new Confluence v2 API for whiteboards?


I’m assuming whiteboards will show up in search results via /content/search - if we need to filter them out, will whiteboard as a type be available in CQL or will we have to filter the result itself?

TBH for my app, it will be easier to filter them via CQL not from the result, so I hope this is the case.

Please let us read and write the content of whiteboards programatically. Is it ADF format? A usecase is if a plugin’s job is to find-and-replace a keyword with another, on all pages/blogs/whiteboards of a space.

1 Like

Hi @AbhinavSingh ,
If I’m not mistaken, the whiteboard API uses deprecated v1 API endpoints.
When can we expect v2 endpoints?

1 Like

Hi @AbhinavSingh ,

Thanks for the RFC. I have some questions:

  1. Can whiteboards have direct children of the “attachment” or “comment” content types?

  2. Are webhooks available for actions taken with whiteboards? If so, which ones and what is their expected payload?

  3. Can you please describe the API responses in more detail for whiteboards in the (deprecated) V1 REST API? What should we expect to see if the app tries to fetch a whiteboard?

  4. Even in the absence of rolling out an immediate REST API V2 equivalent, can you clarify how whiteboards will be represented in the existing V2 API calls that handle different types of content? For example, with whiteboards being integrated into the page tree, a page could now have a whiteboard as a parent. The V2 endpoint currently returns a “parentId” for an existing page. How do we know if that parent is a whiteboard or a page?



Hi @bobbergman1 - All v2 APIs would continue to return payloads as is. Whiteboards related content is not expected to be added in the APIs for our EAP customers or Beta customers. The APIs with whiteboard content (additive changes) will be supported before GA.

1 Like

Hi @marc : Changes (additive) to v2 endpoints are not supported for Beta and will be made available before GA (timeline: TBD). We will give sufficient time to test as introduce whiteboards are introduced in v2 APIs.

1 Like

H @AbhinavSingh ,
Thanks for the v2 API information.

We’ve got 2 followup question related to whiteboards:

  1. Will whiteboards get content properties?

  2. Will static and dynamic content macros work in whiteboards?


Hi @AbhinavSingh,

are you thinking about a way to let apps access / export the content of whiteboards? It would be nice if there was an endpoint to e.g. get the whiteboard as a PNG.



As far as I understood, one of the main goals of the V2 REST API was to split up the “Content” type and have separate endpoints for everything.

Now, adding Whiteboards into the mix, how is that going to pan out for endpoints such as the pages one? Will there be an endpoint to get children / descendants of all types, or will apps have to call multiple children endpoints and stitch together the actual page tree as it is in Confluence of their own?

Maybe @TylerBrown can shed some light on how the API team plans to deal with this?


Hi @SvenSchatter - currently for EAP/Beta, exports are not supported for whiteboards. However, the team would be working to expose whiteboard content in future (potentially around GA)

1 Like

:mega: Added Context:
Hi All,
Totally appreciate your comments and asks for getting whiteboards data through v2 APIs. Love the excitement to add them in your apps today :slight_smile:

Currently, our product team is concentrating on launching the whiteboard beta version for customers while ensuring that our partners’ existing apps remain unaffected (through any intentional/unintentional changes). We are not actively working on updating/adding APIs to expose whiteboard content before Beta.

Post-Beta and before GA, we’ll strive to have the appropriate APIs in place to provide access to whiteboard content and properties for your apps.

We would greatly appreciate your help in testing for any potential impacts before Beta, especially as whiteboards become available in your environments soon.

Hi @marc,

  1. Currently, whiteboards will have some content properties, but no editor properties (full-width, content-state, emoji-title, etc.). The existing content properties are not user changeable.
  2. There will not be any macros in whiteboards for EAP.

Hi @james.dellow,

Whiteboards will appear in search, and they will be available through CQL.


Hi @aragot - Whiteboards are not defined using an ADF format. We have yet to define a format which ecosystem partners can use (Will not be supported for public Beta though), but will let you know when we kick that process off, including updating the content of whiteboards via API. Let us know if you have any other use cases, we’d love to know of them!

Hi @scott.dudley - Answering your questions

  1. No, whiteboards won’t have comment/attachments as children for Whiteboards Beta
  2. We are not planning to provide webhooks for whiteboards beta.
  3. Whiteboards will still be returned in the Content API model, with all of the same fields and expands. The values of those may be different, ex: body will be null as of release. I can update this again closer to the us releasing whiteboards in your ecosystem environment.

Hi @marc - answering your questions here -

  1. No typical editor properties, but users will be able to set and retrieve their own content properties, like they can with pages.
  2. Macros are not supported in whiteboards beta.

Hi @SvenSchatter - we have not made a specific decision on whether additional expands would be added to existing APIs or new APIs dedicated to each content type would be added. Will keep you all posted as we decide and build them for GA.


(post deleted by author)