diff --git a/api/client-server/v2_alpha/filter.yaml b/api/client-server/v2_alpha/filter.yaml
new file mode 100644
index 00000000..99dc0ebc
--- /dev/null
+++ b/api/client-server/v2_alpha/filter.yaml
@@ -0,0 +1,188 @@
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server v2 filter API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+basePath: /_matrix/client/api/v2_alpha
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  accessToken:
+    type: apiKey
+    description: The user_id or application service access_token
+    name: access_token
+    in: query
+definitions:
+  EventFilter:
+    title:
+    type: object
+    properties:
+      types:
+        type: array
+        description: |-
+          A list of event types to include.
+          If this list is absent then all event types are included.
+        items:
+          type: string
+      not_types:
+        type: array
+        description: |-
+          A list of event types to exclude.
+          If this list is absent then no event types are excluded.
+        items:
+          type: string
+      senders:
+        type: array
+        description: |-
+          A list of senders IDs to include.
+          If this list is absent then all senders are included.
+        items:
+          type: string
+      not_senders:
+        type: array
+        description: |-
+          A list of sender IDs to exclude
+          If this list is absent then no senders are excluded.
+        items:
+          type: string
+      rooms:
+        type: array
+        description: |-
+          A list of room IDs to include.
+          If this list is absent then all rooms are included.
+        items:
+          type: string
+      not_rooms:
+        type: array
+        description: |-
+          A list of room IDs to exclude
+          If this list is absent then no rooms are excluded.
+        items:
+          type: string
+  SyncFilter:
+    room:
+      type: object
+      properties:
+        state:
+          description:
+            The state events to include for rooms.
+          allOf:
+          - $ref: "#/definitions/EventFilter"
+        events:
+          description:
+            The message and state update events to include for rooms.
+          allOf:
+          - $ref: "#/definitions/EventFilter"
+        ephemeral:
+          description: |-
+            The events that aren't recorded in the permenant history, e.g.
+            typing and receipts, to include for rooms.
+          allOf:
+          - $ref: "#/definitions/EventFilter"
+    public_user_data:
+      description: |-
+        The public user data, e.g. profile and presence, to include.
+      allOf:
+          - $ref: "#/definitions/EventFilter"
+    private_user_data:
+      description: |-
+        Events that are private to a user but shared amoungst their devices,
+        e.g. notification settings, to include.
+      allOf:
+          - $ref: "#/definitions/EventFilter"
+    event_format:
+      description: |-
+        The format to use for events. "client" will return the events in a
+        format suitable for clients. "federation" will return the raw event
+        as receieved over federation. The default is "client".
+      type: string
+    event_fields:
+      type: array
+      description: |-
+        List of event fields to include. If this list is absent then all fields
+        are included. The entries may include "." charaters to indicate
+        sub-fields. So ["content.body"] will include the "body" field of the
+        "content" object. A server may include more fields than were requested.
+      items:
+        string
+paths:
+    "/user/{userId}/filter":
+      post:
+        summary: Upload a new filter.
+      description: |-
+        Uploads a new filter definition to the homeserver.
+        Returns a filter ID that may be used in /sync requests to
+        retrict which events are returned to the client.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: userId
+          required: true
+          description:
+            The id of the user uploading the filter. The access token must be
+            authorized to make requests for this user id.
+          x-example: "@alice:example.com"
+        - in: body
+          name: filter
+          required: true
+          description: The filter to upload.
+          schema:
+            type: object
+            allOf:
+              - $ref: "#/definitions/SyncFilter"
+            example:
+              type: object
+              example: |-
+                {
+                  "room": {
+                    "state": {
+                      "types": ["m.room.*"],
+                      "not_rooms": ["!726s6s6q:example.com"],
+                    },
+                    "events": {
+                      "types": ["m.room.message"],
+                      "not_rooms": ["!726s6s6q:example.com"],
+                      "not_senders": ["@spam:example.com"]
+                    },
+                    "emphemeral": {
+                      "types": ["m.receipt", "m.typing"],
+                      "not_rooms": ["!726s6s6q:example.com"],
+                      "not_senders": ["@spam:example.com"]
+                    }
+                  },
+                  "public_user_data": {
+                    "types": ["m.presence"]
+                  },
+                  "private_user_data": {
+                    "types": []
+                  },
+                  "server_data": {
+                    "types": []
+                  },
+                  "event_format": "client",
+                  "event_fields": ["type", "content", "sender"]
+                }
+      responses:
+        200:
+          description: The filter was created.
+          examples:
+            application/json: |-
+              {
+                "filter_id": "66696p746572"
+              }
+          schema:
+            type: object
+            properties:
+              filter_id:
+                type: string
+                description:
+                  The ID of the filter that was created.
+
+
+