Re: Smart Link API, supported links types, and breaking changes

Re: v2 API support

We are prioritizing and actively working on getting the following REST v2 APIs out for Smart Links/Embeds:

POST /embeds - create embed
GET /embeds/{id} - get embed by id
DEL /embeds/{id} - delete embed

These APIs will be analagous to the existing Whiteboard APIs, but apply for Embeds instead.

Following the release of the APIs mentioned above, we’ll work on support for
PUT /embeds/{id} - to edit the title and/or link attached to the content

Each of these API changes will be accompanied by a changelog, and we will link to them here once available.

Re: supported links

Question from @aragot (from the original RFC post):

Do Smart Links have an API to build smart links for any kind of web content, not just Miro boards and Google Docs? Smart Links seem to have a limited list of built-in apps, and default to pulling the tags of webpages, but unauthenticated, which is useless in the context of documents. In other words, apps can’t provide the snippets for smart links.

The PUT method above will expose the ability to build smart links for almost all links, well beyond just Miro boards, Google Docs, and other Atlassian products. We are using the existing “Smart Link” auth mechanisms here, which can be found here.

You must be logged in to non-Atlassian products that require authentication before you can diplay the Smart Link in your page. You’ll only need to do this once, and that product’s links will work across all of Atlassian Cloud.
For links to non-Atlassian product that requires access to view, readers need to be logged in for Smart Links to display in the correct view.

More precisely, we are using existing cookies/session data present in the user’s browser to render embeds/smart links in Confluence.

Re: breaking changes within the 6 month window

On behalf of the team, I apologize for the delay, frustration, and thrash here. Introducing the embed content type is a breaking change within the 6 month window, and we are unfortunately unable to push out our feature rollout schedule to honor it.

We are working on process changes internally across multiple teams to ensure that future changes like this one are announced as early as possible, with v2 API support as a strict requirement - with a much earlier timeframe, honoring the 6 month breaking change notification window, among other checklist items. We hope to learn from our mistakes here and do better as a team.

We thank you for your continued patience and support, and please do let us know if you have further feedback or questions!


v2 APIs for smart links are now available, please see the changelog covering it here: