diff --git a/docs/specification.rst b/docs/specification.rst
index 239e51b4f34e2dae9ff013848ebd4df35b736021..a329c0754267b35e6e0be5c83bc33408eb0c5fb3 100644
--- a/docs/specification.rst
+++ b/docs/specification.rst
@@ -742,15 +742,17 @@ There are several APIs provided to ``GET`` events for a room:
   Description:
     Get all ``m.room.member`` state events.
   Response format:
-    ``{ "start": "token", "end": "token", "chunk": [ { m.room.member event }, ... ] }``
+    ``{ "start": "<token>", "end": "<token>", "chunk": [ { m.room.member event }, ... ] }``
   Example:
     TODO
 
 |/rooms/<room_id>/messages|_
   Description:
-    Get all ``m.room.message`` events.
+    Get all ``m.room.message`` and ``m.room.member`` events. This API supports pagination
+	using ``from`` and ``to`` query parameters, coupled with the ``start`` and ``end``
+	tokens from an |initialSync|_ API.
   Response format:
-    ``{ TODO }``
+    ``{ "start": "<token>", "end": "<token>" }``
   Example:
     TODO