diff --git a/docs/changes.rst b/docs/changes.rst
new file mode 100644
index 00000000..28afdf23
--- /dev/null
+++ b/docs/changes.rst
@@ -0,0 +1,31 @@
+=======
+Changes
+=======
+
+
+.. _changes:
+
+Breaking changes from v2.x to v3.x
+==================================
+
+With the upgrade from v2.x of the bookmarks app to v3.x several breaking changes in the API were introduced which were not possible to avoid.
+
+.. object:: Bookmark
+
+   :param int id: All bookmark IDs are now integer values instead of strings
+
+.. object:: Folder
+
+   :param int id: All folder IDs are now integer values instead of strings
+
+.. get:: /public/rest/v2/bookmark
+
+  This endpoint no longer accepts the ``item[tags]`` query parameter. Use the normal ``tags`` param
+
+.. post:: /public/rest/v2/bookmark
+
+  This endpoint no longer accepts the ``item[tags]`` query parameter. Use the normal ``tags`` param
+
+.. put:: /public/rest/v2/bookmark
+
+  This endpoint no longer accepts the ``item[tags]`` query parameter. Use the normal ``tags`` param
diff --git a/docs/index.rst b/docs/index.rst
index b3813602..7b6f4ec1 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -13,3 +13,4 @@ This documentation describes how to use this API.
    tag
    folder
    share
+   changes