diff --git a/api/client-server/users.yaml b/api/client-server/users.yaml
new file mode 100644
index 00000000..e04faac8
--- /dev/null
+++ b/api/client-server/users.yaml
@@ -0,0 +1,93 @@
+# Copyright 2016 OpenMarket 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 Profile 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 paginates over search results of the user directory.
+      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
+                example: 10
+            required: ["search_term"]
+      responses:
+        200:
+          description: The results of the paginated 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
+                items:
+                  title: User
+                  type: object
+                  properties:
+                    user_id:
+                      type: string
+                      example: "@foo:bar.com"
+                    display_name:
+                      type: string
+                      example: "Foo"
+                    avatar_url:
+                      type: string
+                      example: "mxc://bar.com/foo"
+              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/specification/client_server_api.rst b/specification/client_server_api.rst
index e68aea43..2586041d 100644
--- a/specification/client_server_api.rst
+++ b/specification/client_server_api.rst
@@ -1335,6 +1335,13 @@ Listing rooms
 
 {{list_public_rooms_cs_http_api}}
 
+
+Users
+-----
+
+{{users_cs_http_api}}
+
+
 Profiles
 --------