diff --git a/api/client-server/v1/typing.yaml b/api/client-server/v1/typing.yaml
new file mode 100644
index 00000000..737c6928
--- /dev/null
+++ b/api/client-server/v1/typing.yaml
@@ -0,0 +1,77 @@
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server v1 Typing API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/api/v1
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  accessToken:
+    type: apiKey
+    description: The user_id or application service access_token
+    name: access_token
+    in: query
+paths:
+  "/rooms/{roomId}/typing/{userId}":
+    put:
+      summary: Informs the server that the user has started or stopped typing.
+      description: |-
+        This tells the server that the user is typing for the next N
+        milliseconds where N is the value specified in the ``timeout`` key.
+        Alternatively, if ``typing`` is ``false``, it tells the server that the
+        user has stopped typing.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: userId
+          description: The user who has started to type.
+          required: true
+          x-example: "@alice:example.com"
+        - in: path
+          type: string
+          name: roomId
+          description: The room in which the user is typing.
+          required: true
+          x-example: "!wefh3sfukhs:example.com"
+        - in: body
+          name: typingState
+          description: The current typing state.
+          required: true
+          schema:
+            type: object
+            example: |-
+              {
+                "typing": true,
+                "timeout": 30000
+              }
+            properties:
+              typing:
+                type: boolean
+                description: |-
+                  Whether the user is typing or not. If ``false``, the ``timeout``
+                  key can be omitted.
+              timeout:
+                type: integer
+                description: The length of time in milliseconds to mark this user as typing.
+            required: ["typing"]
+      responses:
+        200:
+          description: The new typing state was set.
+          examples:
+            application/json: |-
+              {}
+          schema:
+            type: object  # empty json object
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/error.yaml"
+
diff --git a/event-schemas/examples/v1/m.typing b/event-schemas/examples/v1/m.typing
new file mode 100644
index 00000000..bd53f6fb
--- /dev/null
+++ b/event-schemas/examples/v1/m.typing
@@ -0,0 +1,7 @@
+{
+    "type": "m.typing",
+    "room_id": "!z0mnsuiwhifuhwwfw:matrix.org",
+    "content": {
+        "user_ids": ["@alice:matrix.org", "@bob:example.com"]
+    }
+}
\ No newline at end of file
diff --git a/event-schemas/schema/v1/m.typing b/event-schemas/schema/v1/m.typing
new file mode 100644
index 00000000..b712f6ec
--- /dev/null
+++ b/event-schemas/schema/v1/m.typing
@@ -0,0 +1,28 @@
+{
+    "type": "object",
+    "title": "Typing Event",
+    "description": "Informs the client of the list of users currently typing.",
+    "properties": {
+        "content": {
+            "type": "object",
+            "properties": {
+                "user_ids": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "description": "The list of user IDs typing in this room, if any."
+                }
+            },
+            "required": ["user_ids"]
+        },
+        "type": {
+            "type": "string",
+            "enum": ["m.typing"]
+        },
+        "room_id": {
+            "type": "string"
+        }
+    },
+    "required": ["type", "room_id", "content"]
+}
diff --git a/specification/modules/typing_notifications.rst b/specification/modules/typing_notifications.rst
index 25b714ab..b32e3411 100644
--- a/specification/modules/typing_notifications.rst
+++ b/specification/modules/typing_notifications.rst
@@ -1,45 +1,30 @@
 Typing Notifications
---------------------
+====================
 
-Client APIs
-~~~~~~~~~~~
+Events
+------
 
-To set "I am typing for the next N msec"::
+{{m_typing_event}}
 
-  PUT .../rooms/<room_id>/typing/<user_id>
-  Content:  { "typing": true, "timeout": N }
-  # timeout is in milliseconds; suggested no more than 20 or 30 seconds
+Client behaviour
+----------------
+
+ - suggested no more than 20-30 seconds
 
 This should be re-sent by the client to continue informing the server the user
 is still typing; a safety margin of 5 seconds before the expected
 timeout runs out is recommended. Just keep declaring a new timeout, it will
 replace the old one.
 
-To set "I am no longer typing"::
-
-  PUT ../rooms/<room_id>/typing/<user_id>
-  Content: { "typing": false }
-
-Client Events
-~~~~~~~~~~~~~
-
-All room members will receive an event on the event stream::
-
-  {
-    "type": "m.typing",
-    "room_id": "!room-id-here:matrix.org",
-    "content": {
-      "user_ids": ["list of", "every user", "who is", "currently typing"]
-    }
-  }
-
-The client must use this list to *REPLACE* its knowledge of every user who is
+Event: The client must use this list to *REPLACE* its knowledge of every user who is
 currently typing. The reason for this is that the server DOES NOT remember
 users who are not currently typing, as that list gets big quickly. The client
 should mark as not typing, any user ID who is not in that list.
 
-Server APIs
-~~~~~~~~~~~
+{{typing_http_api}}
+
+Server behaviour
+----------------
 
 Servers will emit EDUs in the following form::
 
@@ -59,3 +44,9 @@ originating HSes to ensure they eventually send "stop" notifications.
   ((This will eventually need addressing, as part of the wider typing/presence
   timer addition work))
 
+Security considerations
+-----------------------
+
+Clients may not wish to inform everyone in a room that they are typing and
+instead only specific users in the room.
+