diff --git a/api/server-server/definitions/keys.yaml b/api/server-server/definitions/keys.yaml
new file mode 100644
index 00000000..5d1c39de
--- /dev/null
+++ b/api/server-server/definitions/keys.yaml
@@ -0,0 +1,96 @@
+# Copyright 2018 New Vector Ltd
+#
+# 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.
+type: object
+title: Server Keys
+description: Server keys
+example:
+  $ref: "../examples/server_key.json"
+properties:
+  server_name:
+    type: string
+    description: DNS name of the homeserver
+    required: true # TODO: Verify
+    example: "example.org"
+  verify_keys:
+    type: object
+    description: Public keys of the homeserver for verifying digital signatures
+    required: true # TODO: Verify
+    additionalProperties:
+      type: object
+      title: Verify Key
+      example: {
+        "ed25519:auto2": {
+          "key": "Base+64+Encoded+Signature+Verification+Key"
+        }
+      }
+      properties:
+        key:
+          type: string
+          description: The key
+          required: true
+          example: "Base+64+Encoded+Signature+Verification+Key"
+  old_verify_keys:
+    type: object
+    description: The public keys that the server used to use and when it stopped using them
+    additionalProperties:
+      type: object
+      title: Old Verify Key
+      example: {
+        "ed25519:auto1": {
+          "expired_ts": 922834800000,
+          "key": "Base+64+Encoded+Signature+Verification+Key"
+        }
+      }
+      properties:
+        expired_ts:
+          type: integer
+          format: int64
+          description: The expiration time
+          required: true
+          example: 922834800000
+        key:
+          type: string
+          description: The key
+          required: true
+          example: "Base+64+Encoded+Signature+Verification+Key"
+  signatures:
+    type: object
+    description: Digital signatures for this object signed using the ``verify_keys``
+    additionalProperties:
+      type: object
+      title: Signed Server
+      example: {
+        "example.org": {
+          "ad25519:auto2": "Base+64+Encoded+Signature+Verification+Key"
+        }
+      }
+      additionalProperties:
+        type: string
+        name: Encoded Signature Verification Key
+  tls_fingerprints:
+    type: array
+    description: Hashes of X.509 TLS certificates used by this server encoded as `Unpadded Base64`_
+    items:
+      type: object
+      title: TLS Fingerprint
+      properties:
+        sha256:
+          type: string
+          description: The encoded fingerprint
+          example: Base+64+Encoded+SHA-256-Fingerprint
+  valid_until_ts:
+    type: integer
+    format: int64
+    description: POSIX timestamp when the list of valid keys should be refreshed
+    example: 1052262000000
diff --git a/api/server-server/definitions/keys_query_response.yaml b/api/server-server/definitions/keys_query_response.yaml
new file mode 100644
index 00000000..8223f9ec
--- /dev/null
+++ b/api/server-server/definitions/keys_query_response.yaml
@@ -0,0 +1,27 @@
+# Copyright 2018 New Vector Ltd
+#
+# 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.
+type: object
+description: Server keys
+example: {
+  "server_keys": [{
+    $ref: "../examples/server_key.json"
+  }]
+}
+properties:
+  server_keys:
+    type: array
+    title: Server Keys
+    description: The server keys
+    items:
+      $ref: "keys.yaml"
diff --git a/api/server-server/examples/server_key.json b/api/server-server/examples/server_key.json
new file mode 100644
index 00000000..a3934bd3
--- /dev/null
+++ b/api/server-server/examples/server_key.json
@@ -0,0 +1,23 @@
+{
+    "server_name": "example.org",
+    "verify_keys": {
+        "ed25519:auto2": {
+        "key": "Base+64+Encoded+Signature+Verification+Key"
+        }
+    },
+    "old_verify_keys": {
+        "ed25519:auto1": {
+        "expired_ts": 922834800000,
+            "key": "Base+64+Encoded+Old+Verify+Key"
+        }
+    },
+    "signatures": {
+        "example.org": {
+        "ed25519:auto2": "Base+64+Encoded+Signature"
+        }
+    },
+    "tls_fingerprints": [{
+        "sha256": "Base+64+Encoded+SHA-256-Fingerprint"
+    }],
+    "valid_until_ts": 1052262000000
+}
\ No newline at end of file
diff --git a/api/server-server/keys.yaml b/api/server-server/keys.yaml
new file mode 100644
index 00000000..e8e5167d
--- /dev/null
+++ b/api/server-server/keys.yaml
@@ -0,0 +1,121 @@
+# Copyright 2018 New Vector Ltd
+#
+# 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 Key Exchange API"
+  version: "1.0.0"
+host: localhost:8448
+schemes:
+  - https
+basePath: /_matrix/key/v2
+produces:
+  - application/json
+paths:
+  "/server/{keyId}":
+    get:
+      summary: Get the server's key
+      description: Get the server's key
+      operationId: getServerKey
+      parameters:
+        - in: path
+          name: keyId
+          type: string
+          description: Key ID
+          required: false
+          x-example: TODO # No examples in the spec so far
+      responses:
+        200:
+          description: The server's keys
+          schema:
+            $ref: "definitions/keys.yaml"
+  "/query/{serverName}/{keyId}":
+    get:
+      summary: Retreive a server key
+      description: Retreive a server key
+      operationId: getQueryKeys
+      parameters:
+        - in: path
+          name: serverName
+          type: string
+          description: Server name
+          required: true
+          x-example: matrix.org
+        - in: path
+          name: keyId
+          type: string
+          description: Key ID
+          required: true
+          x-example: TODO # No examples in spec so far
+        - in: query
+          name: minimum_valid_until_ts
+          type: integer
+          format: int64
+          description: Minimum Valid Until Milliseconds
+          required: true # TODO: Verify 
+          x-example: 1234567890
+      responses:
+        200:
+          description: The keys for the server
+          schema:
+            $ref: "definitions/keys_query_response.yaml"
+  "/query":
+    post:
+      summary: Retreive a server key
+      description: Retreive a server key
+      operationId: postQueryKeys
+      parameters:
+        - in: body
+          name: body
+          schema:
+            type: object
+            # TODO: Improve example
+            example: {
+              "server_keys": {
+                "{server_name}": {
+                  "{key_id}": {
+                    "minimum_valid_until_ts": 1234567890
+                  }
+                }
+              }
+            }
+            properties:
+              server_keys:
+                type: object
+                description: The query criteria
+                required: true
+                additionalProperties:
+                  type: object
+                  name: ServerName
+                  description: The server names to query
+                  additionalProperties:
+                    type: array
+                    name: ServerKey
+                    description: The server keys to query
+                    items:
+                      type: object
+                      title: Query Criteria
+                      description: The query criteria
+                      properties:
+                        minimum_valid_until_ts:
+                          type: integer
+                          format: int64
+                          description: Minimum Valid Until MS
+                          required: true # TODO: Verify
+                          x-example: 1234567890
+      responses:
+        200:
+          description: The keys for the server
+          schema:
+            $ref: "definitions/keys_query_response.yaml"
diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst
index f2b3204a..86151991 100644
--- a/specification/server_server_api.rst
+++ b/specification/server_server_api.rst
@@ -1,5 +1,6 @@
 .. Copyright 2016 OpenMarket Ltd
 .. Copyright 2017 New Vector Ltd
+.. Copyright 2018 New Vector Ltd
 ..
 .. Licensed under the Apache License, Version 2.0 (the "License");
 .. you may not use this file except in compliance with the License.
@@ -232,38 +233,7 @@ This API can return keys for servers that are offline by using cached responses
 taken from when the server was online. Keys can be queried from multiple
 servers to mitigate against DNS spoofing.
 
-Example request:
-
-.. code::
-
-    GET /_matrix/key/v2/query/{server_name}/{key_id}/?minimum_valid_until_ts={minimum_valid_until_ts} HTTP/1.1
-
-    POST /_matrix/key/v2/query HTTP/1.1
-    Content-Type: application/json
-
-    {
-        "server_keys": {
-            "{server_name}": {
-                "{key_id}": {
-                    "minimum_valid_until_ts": {posix_timestamp}
-                }
-            }
-        }
-    }
-
-
-Response:
-
-.. code::
-
-    HTTP/1.1 200 OK
-    Content-Type: application/json
-    {
-        "server_keys": [
-           # List of responses with same format as /_matrix/key/v2/server
-           # signed by both the originating server and this server.
-        ]
-    }
+{{keys_ss_http_api}}
 
 Version 1
 +++++++++