diff --git a/docs/migration/v1.2.md b/docs/migration/v1.2.md
new file mode 100644
index 000000000..143fe4f89
--- /dev/null
+++ b/docs/migration/v1.2.md
@@ -0,0 +1,25 @@
+# Migrate to v1.2
+
+Updating the SDK from version 1.1.z to 1.2.z is an easy task for Kotlin projects as there are no (runtime-) breaking
+changes introduced. Java projects might need some additional work due to the Java compatibility changes.
+
+## WebSockets
+
+We've introduced a rewritten WebSocket API to make it easier to receive realtime events from the Jellyfin server.
+Lean more on the [WebSockets](../websockets.md) page. The old WebSocket code is still available but will be removed
+entirely in v1.3.
+
+## Java compatibility
+
+This version introduces new helpers for Java compatibility. Previous helpers have been renamed or removed.
+
+- Removed JavaCallback
+- Renamed JavaDataCallback to JavaResponseContinuation
+- Added JavaFlow to receive flow data
+
+Note that we still recommend writing code using the SDK in Kotlin.
+
+### Exception for missing base url
+
+Previously when calling an API without a URL set in the ApiClient an IllegalArgumentException was thrown. This has now
+been changed to a newly introduced MissingBaseUrlException that extends our existing ApiClientException.