diff --git a/api/server-server/directory.yaml b/api/server-server/directory.yaml
new file mode 100644
index 00000000..58449fa2
--- /dev/null
+++ b/api/server-server/directory.yaml
@@ -0,0 +1,67 @@
+# Copyright 2017 Kamax.io
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+swagger: '2.0'
+info:
+  title: "Matrix Federation Version API"
+  version: "1.0.0"
+host: localhost:8448
+schemes:
+  - https
+basePath: /_matrix/federation/v1/query
+produces:
+  - application/json
+paths:
+  "/directory":
+    get:
+      summary: Retrieve the room ID and list of resident homeservers for a room
+        alias.
+      description: Retrieve the room ID and list of resident homeservers for a Room
+        alias.
+      parameters:
+        - in: query
+          name: room_alias
+          type: string
+          description: Room alias
+          required: true
+          x-example: "#room_alias:example.org"
+      responses:
+        200:
+          description: The corresponding room ID and list of known resident
+            homeservers for the room.
+          schema:
+            type: object
+            properties:
+              room_id:
+                type: string
+                description: The room ID mapped to the queried room alias.
+                required: true
+                x-example: "!roomid1234:example.org"
+              servers:
+                type: array
+                description: An array of server names that are likely to hold
+                  then given room. This list may or may not include the server
+                  answering the query.
+                required: true
+                items:
+                  type: string
+          examples:
+            application/json: {
+              "room_id": "!roomid1234:example.org",
+              "servers": [
+                "example.org",
+                "example.com",
+                "another.example.com:8449",
+              ]
+            }
\ No newline at end of file
diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst
index 8ffe4e6a..1ca2f39b 100644
--- a/specification/server_server_api.rst
+++ b/specification/server_server_api.rst
@@ -1271,21 +1271,7 @@ Directory
 
 The server API for directory queries is also based on Federation Queries.
 
-Querying directory information::
-
-  Query type: directory
-
-  Arguments:
-    room_alias: the room alias to query
-
-  Returns: JSON object containing the following keys:
-    room_id: string giving the underlying room ID the alias maps to
-    servers: list of strings giving the join candidates
-
-The list of join candidates is a list of server names that are likely to hold
-the given room; these are servers that the requesting server may wish to use as
-resident servers as part of the remote join handshake. This list may or may not
-include the server answering the query.
+{{directory_ss_http_api}}
 
 Send-to-device messaging
 ------------------------