diff --git a/api/client-server/users.yaml b/api/client-server/users.yaml
new file mode 100644
index 00000000000..1734e3bb86a
--- /dev/null
+++ b/api/client-server/users.yaml
@@ -0,0 +1,100 @@
+# Copyright 2017 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 Client-Server User Directory API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  $ref: definitions/security.yaml
+paths:
+  "/user_directory/search":
+    post:
+      summary: Searches the user directory.
+      description: |-
+        This API performs a server-side search over all users registered on the server.
+        It searches user ID and displayname case-insensitively for users that you share a room with or that are in public rooms.
+      operationId: searchUserDirectory
+      security:
+        - accessToken: []
+      parameters:
+        - in: body
+          name: body
+          schema:
+            type: object
+            properties:
+              search_term:
+                type: string
+                description: The term to search for
+                example: "foo"
+              limit:
+                type: number
+                description: The maximum number of results to return (Defaults to 10).
+                example: 10
+            required: ["search_term"]
+      responses:
+        200:
+          description: The results of the search.
+          examples:
+            application/json: {
+                  "results": [
+                    {
+                      "user_id": "@foo:bar.com",
+                      "display_name": "Foo",
+                      "avatar_url": "mxc://bar.com/foo"
+                    }
+                  ],
+                  "limited": false
+              }
+          schema:
+            type: object
+            required: ["results", "limited"]
+            properties:
+              results:
+                type: array
+                description: Ordered by rank and then whether or not profile info is available.
+                items:
+                  title: User
+                  type: object
+                  required: ["user_id"]
+                  properties:
+                    user_id:
+                      type: string
+                      example: "@foo:bar.com"
+                      description: The user's matrix user ID.
+                    display_name:
+                      type: string
+                      example: "Foo"
+                      description: The display name of the user, if one exists.
+                    avatar_url:
+                      type: string
+                      example: "mxc://bar.com/foo"
+                      description: The avatar url, as an MXC, if one exists.
+              limited:
+                type: boolean
+                description: Indicates if the result list has been truncated by the limit.
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/error.yaml"
+      tags:
+        - User data
diff --git a/changelogs/client_server.rst b/changelogs/client_server.rst
index b0fb8426142..8d5f4559894 100644
--- a/changelogs/client_server.rst
+++ b/changelogs/client_server.rst
@@ -1,6 +1,13 @@
 Unreleased changes
 ==================
 
+- Changes to the API which will be backwards-compatible for clients:
+
+  - New endpoints:
+
+    - ``POST /user_directory/search``
+      (`#1096 <https://github.com/matrix-org/matrix-doc/pull/1096>`_).
+
 - Spec clarifications:
 
   - Mark ``home_server`` return field for ``/login`` and ``/register``
diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst
index e68aea43804..326ff282f72 100644
--- a/specification/client_server_api.rst
+++ b/specification/client_server_api.rst
@@ -1335,13 +1335,23 @@ Listing rooms
 
 {{list_public_rooms_cs_http_api}}
 
+
+User Data
+---------
+
+User Directory
+~~~~~~~~~~~~~~
+
+{{users_cs_http_api}}
+
+
 Profiles
---------
+~~~~~~~~
 
 {{profile_cs_http_api}}
 
 Events on Change of Profile Information
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
++++++++++++++++++++++++++++++++++++++++
 Because the profile display name and avatar information are likely to be used in
 many places of a client's display, changes to these fields cause an automatic
 propagation event to occur, informing likely-interested parties of the new