diff --git a/api/client-server/v1/directory.yaml b/api/client-server/v1/directory.yaml
index c70b9f6b..4966a920 100644
--- a/api/client-server/v1/directory.yaml
+++ b/api/client-server/v1/directory.yaml
@@ -29,6 +29,7 @@ paths:
           name: roomAlias
           description: The room alias to set.
           required: true
+          x-example: "#monkeys:matrix.org"
         - in: body
           name: roomInfo
           description: Information about this room alias.
@@ -39,11 +40,18 @@ paths:
               room_id:
                 type: string
                 description: The room ID to set.
+            example: |-
+              {
+                "room_id": "!abnjk1jdasj98:capuchins.com"
+              }
       responses:
         200:
           description: The mapping was created.
+          examples:
+            application/json: |-
+              {}
           schema:
-            type: object  # empty json object
+            type: object
     get:
       summary: Get the room ID corresponding to this room alias.
       parameters:
@@ -52,6 +60,7 @@ paths:
           name: roomAlias
           description: The room alias.
           required: true
+          x-example: "#monkeys:matrix.org"
       responses:
         200:
           description: The room ID and other information for this alias.
@@ -67,10 +76,38 @@ paths:
                 items:
                   type: string
                   description: A server which is aware of this room ID.
+          examples:
+            application/json: |-
+              {
+                "room_id": "!abnjk1jdasj98:capuchins.com",
+                "servers": [
+                  "capuchins.com",
+                  "matrix.org",
+                  "another.com"
+                ]
+              }
         404:
           description: There is no mapped room ID for this room alias.
+          examples:
+            application/json: |-
+              {
+                "errcode": "M_NOT_FOUND",
+                "error": "Room ID !abnjk1jdasj98:capuchins.com not found."
+              }
+        409:
+          description: A room alias with that name already exists.
+          examples:
+            application/json: |-
+              {
+                "errcode": "M_UNKNOWN",
+                "error": "Room alias #monkeys:matrix.org already exists."
+              }
     delete:
       summary: Remove a mapping of room alias to room ID.
+      description: |-
+        Remove a mapping of room alias to room ID.
+
+        Servers may choose to implement additional access control checks here, for instance that room aliases can only be deleted by their creator or a server administrator.
       security:
         - accessToken: []
       parameters:
@@ -79,9 +116,12 @@ paths:
           name: roomAlias
           description: The room alias to remove.
           required: true
+          x-example: "#monkeys:matrix.org"
       responses:
         200:
-          description: The mapping was removed.
+          description: The mapping was deleted.
+          examples:
+            application/json: |-
+              {}
           schema:
-            type: object  # empty json object
-
+            type: object
diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst
index ba5578bc..245a9eab 100644
--- a/specification/client_server_api.rst
+++ b/specification/client_server_api.rst
@@ -783,19 +783,9 @@ client has to use the the following API.
 
 Room aliases
 ~~~~~~~~~~~~
-.. NOTE::
-  This section is a work in progress.
-
-Room aliases can be created by sending a ``PUT /directory/room/<room alias>``::
-
-  {
-    "room_id": <room id>
-  }
 
-They can be deleted by sending a ``DELETE /directory/room/<room alias>`` with
-no content. Only some privileged users may be able to delete room aliases, e.g.
-server admins, the creator of the room alias, etc. This specification does not
-outline the privilege level required for deleting room aliases.
+Servers may host aliases for rooms with human-friendly names. Aliases take the
+form ``#friendlyname:server.name``.
 
 As room aliases are scoped to a particular home server domain name, it is
 likely that a home server will reject attempts to maintain aliases on other
@@ -812,17 +802,11 @@ appears to have a room alias of ``#alias:example.com``, this SHOULD be checked
 to make sure that the room's ID matches the ``room_id`` returned from the
 request.
 
-Room aliases can be checked in the same way they are resolved; by sending a
-``GET /directory/room/<room alias>``::
-
-  {
-    "room_id": <room id>,
-    "servers": [ <domain>, <domain2>, <domain3> ]
-  }
-
 Home servers can respond to resolve requests for aliases on other domains than
 their own by using the federation API to ask other domain name home servers.
 
+{{directory_http_api}}
+
 
 Permissions
 ~~~~~~~~~~~