DiamondLightSource · rosesyrett · May 17, 2023 · May 12, 2023 · May 12, 2023 · May 17, 2023
diff --git a/docs/user/index.rst b/docs/user/index.rst
@@ -51,8 +51,8 @@ side-bar.
             :maxdepth: 1
 
             reference/api
-            reference/asyncapi
-            reference/openapi
+            reference/messaging-spec
+            reference/rest-spec
             ../genindex
 
         +++

diff --git a/docs/user/reference/asyncapi.rst b/docs/user/reference/asyncapi.rst
diff --git a/docs/user/reference/messaging-spec.rst b/docs/user/reference/messaging-spec.rst
@@ -0,0 +1,10 @@
+Messaging Specification
+======================
+
+The Blueapi service publishes Bluesky documents and other events to the message 
+bus, allowing subscribers to keep track of the status of plans, as well as 
+other status changes. This page documents the channels to which clients can 
+subscribe to recieve these messages and their structure.
+
+.. literalinclude:: ./asyncapi.yaml
+   :language: yaml
diff --git a/docs/user/reference/openapi.json b/docs/user/reference/openapi.json
diff --git a/docs/user/reference/openapi.rst b/docs/user/reference/openapi.rst