Deprecating many Confluence v1 APIs that have v2 equivalents

Thanks @TonyGoughAdaptavist for sharing. I guess this apply to UI Kit right, and not CustomUI? As far as I have tested so far CustomUIs are still not supported for the export/print/history view.

@ErikUnemyr This is for Connect macros, I’m not sure how Forge ones are affected.

Hi Team,

Any updates to this query posted a week back is appreciated. Thanks

Hi Team,

Have you just removed xxxIdString fields from v2? If so, is v2 considered stable now? If not, how is the deprecation period for v1 set?

We migrated our code to v2 using those fields. It is broken before we release it and we have to change it to use different fields.

1 Like

Hi @jens - this is not currently planned but if there is enough of an ask for this we will get it prioritized!

Hi @TonyGoughAdaptavist - this is great to hear!

Hi @sunita - I don’t have an answer yet but will work on making sure someone looks at this soon. I can confirm this is present in V1 and not (at least yet) in V2.

Hi @eagle.xiao - I apologize for any confusion! To be transparent - we realized the issue with having non-string ID fields after release and decided to mitigate this issue by first adding equivalent string fields, like you saw. We then decided instead to expose a query param that would change the type of already existing fields, as recently announced in this changelog. This being said, the “idString” etc. fields were in production briefly before removing them and going the above route, which could have been confusing (our mistake here). Now, if you utilize the serialize-ids-as-strings param you should be good to use this to change the return type of the existing ID fields! Please let me know if we can help in any other way.

@SimonKliewer ,
After experimenting with the v2 API, I encounter a problem: returns the content type as a singular, e.g. page.

However the API to get page properties needs the plural in the route:

GET /wiki/api/v2/pages/{page-id}/properties

i.e. pages.

I think the API routes should use the same names as returned by the ID to type conversion. Otherwise all developers need a translation table to look up the right conversion, which makes our code error prone and seemingly a bit ad hoc.

Can that be changed?

And related to that, I think the v2 API should still be in beta until these kind of issues have been sorted out (and e.g. the IDs as strings issue).

The link you provided did not mention anything about the removal of idString fields. That is breaking change. Nobody knows whether it is “briefly” in production. It was IN production.


Big +1! @SimonKliewer Please carefully review what happened here and make sure you grasp the consequences of releasing undocumented breaking changes to a public API so nonchalantly!

We had already started using the idString fields. If that code would have gone live into an app, your breaking changes - that you released just before the easter weekend - would have rendered any app useless.

From a technical perspective I can appreciate a lot of the ideas about the V2 REST API. But seeing how it has been handled process-wise makes me scared for the future.

Please take it slow and be aware of the responsibilities that come with maintaining a public REST API!


Exactly. Our PR was ready before easter. If it were not due to easter holiday, we would have released the change for migration which uses idString fields.

@SimonKliewer , can you please confirm whether V2 API now finalised? I mean truely finalised or locked to a version. We cannot develop against an API that is subject to change, let alone release it to a production environment. Thanks.


Hey there :wave: ,
just wanted to give some feedback in regards to:

For me, it feels a bit wierd that this is passed as a query-parameter. query parameters should not be able to change the schema of the data returned. Have you considered to use a header for this? This would also make live much easier! X-Serialize-Ids-As-Strings: true would work fine. :slight_smile:

1 Like

Content negotiation is the classic REST API solution for returning alternate data representations via standard headers. See the Accept header with a customized media-type (e.g. application/json+<schema-version> as a simple example, though other more formal schemes exist).


I have a lot of questions (~10 of them) relating to V.2 API. What is the preferred method to ask these questions?

Some are feature request related
Some are problems with V.2
And some have to do with the properties that V.2 is missing

Thank you for confirming! Do you suggest creating a DEVHELP to track it? Thanks!

Hi everyone, I am trying to update a scraper that I used to access a table(Table Macro Filter?) on a Confluence page since we are moving to Confluence Cloud.

I have been digging into the Rest API V2 and learned that body content is not being returned and there is also no ability to expand with a call similar to this:

Can anyone point me in the right direction to be able to do this?

According to this blog post:

I might have to make an GraphQL API call? I am not familiar with the language and I don’t think the examples are sufficient to guide me or I also don’t want to go down this rabbit hole if I later discover that graphQL also cannot get me what I am trying to accomplish.

Thanks in advance.


This thread is already overwhelming. I think all of your questions & feedback would be welcome, but it would certainly help if they are separate topics. Please post them in the “Confluence Cloud” category (like this topic). Please use the label #rest-api-v2 for all and any other labels (like #entity-properties) that would help cluster related topics.

A couple caveats where it is better to open a developer support ticket:

  • If it’s clearly a bug and you can reproduce it, dev support will be faster for getting it into the right team’s backlog.
  • If your problem is auth-related, dev support is often better so diagnosis can be done using the very secrets you shouldn’t publish and access to our back-end logs.

For others looking at this thread, I’d also advise new topics for specific questions. Many questions that are related to the v2 APIs are getting lost in this mostly general announcement thread. While I understand every problem with “v2 equivalents” is relevant to whether Atlassian should deprecate v1 APIs, losing the questions, feature requests, and bugs is a bigger problem.

1 Like

Hi Everyone! Thank you for your continued feedback in the V2 APIs.

Hi @marc - Thanks for your feedback here! We understand it might be a bit inconvenient to do a mapping here, since the type name page/pageId etc. is singular and the path is plural /pages/. However, we can assure you these values (type, endpoint path) are stable and will not change.

Hi @eagle.xiao @SvenSchatter - We apologize for removing these undocumented fields. We had never intended to expose them in production, but once they were available and clients began consuming them, we should not have removed them without the appropriate deprecation notice. We will take action to prevent this in the future. Thank you for your feedback here.

Hi @FabianSiegel1 @bobbergman1 - Our team will look into this! It would be nice to also be able to provide a header instead of the query param, thank you for the idea here!

Hi @ParthRewind - Thank you for the feedback! It would be best to start a new topic with all your questions/comments/concerns here with the rest-api-v2 tag and we will do our best to help you there.

Hi @sunita - here is a CONFCLOUD to track the progress!

Hi @david_l - would you be able to explain a bit more on what it is in the V1 endpoint that is not present in the V2 endpoint? As you noted, if you use the body-format param, you should able to request the body content of the page. Also - would it be possible to do this as a new topic posted here? It will help make sure we stay organized and get you an answer as soon as possible. Thanks so much!

Also - as an ask to all for future feedback - let’s start creating new topics here: Confluence Cloud topics with the rest-api-v2 tag. This will help us keep our lines of communication a bit more organized, and better assist in getting the community responses! I can assure you the team is working hard to fix any gaps and respond to any questions as quickly as possible.

If only Atlassian could get some type of application that could track issues that somebody has found and not use a community forum where things could get lost. (and before anyone in the community points out that it will just get lost - more than likely things will get lost here in the 500 different threads).

The precedent that this thread is setting is quite worrisome.


2 posts were split to a new topic: When will there be an API to delete content?

With the following update, I’m locking this thread. Please, continue to create new topics for specific questions using the rest-api-v2 tag. And comment on the update with questions about the overall program of deprecation. Thanks.