async-matrix 0.1.3 → 1.0.0

data/data/matrix-spec/api/client-server/pushrules.yaml

@@ -0,0 +1,633 @@
+# 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.
+openapi: 3.1.0
+info:
+  title: Matrix Client-Server Push Rules API
+  version: 1.0.0
+paths:
+  /pushrules/:
+    get:
+      summary: Retrieve all push rulesets.
+      description: |-
+        Retrieve all push rulesets for this user. Currently the only push ruleset
+        defined is `global`.
+      operationId: getPushRules
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      responses:
+        "200":
+          description: All the push rulesets for this user.
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - global
+                properties:
+                  global:
+                    type: object
+                    description: The global ruleset.
+                    title: Ruleset
+                    allOf:
+                      - $ref: definitions/push_ruleset.yaml
+      tags:
+        - Push notifications
+  /pushrules/global/:
+    get:
+      summary: Retrieve all push rules.
+      description: |-
+        Retrieve all push rules for this user.
+      operationId: getPushRulesGlobal
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      responses:
+        "200":
+          description: All the push rules for this user.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/push_ruleset.yaml
+      tags:
+        - Push notifications
+  "/pushrules/global/{kind}/{ruleId}":
+    get:
+      summary: Retrieve a push rule.
+      description: Retrieve a single specified push rule.
+      operationId: getPushRule
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: kind
+          required: true
+          description: |
+            The kind of rule
+          example: content
+          schema:
+            type: string
+            enum:
+              - override
+              - underride
+              - sender
+              - room
+              - content
+        - in: path
+          name: ruleId
+          required: true
+          description: |
+            The identifier for the rule.
+          example: nocake
+          schema:
+            type: string
+      responses:
+        "200":
+          description: |-
+            The specific push rule. This will also include keys specific to the
+            rule itself such as the rule's `actions` and `conditions` if set.
+          content:
+            application/json:
+              schema:
+                type: object
+                description: The push rule.
+                allOf:
+                  - $ref: definitions/push_rule.yaml
+              examples:
+                response:
+                  value: {
+                    "actions": [],
+                    "pattern": "cake*lie",
+                    "rule_id": "nocake",
+                    "enabled": true,
+                    "default": false
+                  }
+        "404":
+          description: The push rule does not exist.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NOT_FOUND",
+                    "error": "The push rule was not found."
+                  }
+      tags:
+        - Push notifications
+    delete:
+      summary: Delete a push rule.
+      description: This endpoint removes the push rule defined in the path.
+      operationId: deletePushRule
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: kind
+          required: true
+          description: |
+            The kind of rule
+          example: content
+          schema:
+            type: string
+            enum:
+              - override
+              - underride
+              - sender
+              - room
+              - content
+        - in: path
+          name: ruleId
+          required: true
+          description: |
+            The identifier for the rule.
+          example: nocake
+          schema:
+            type: string
+      responses:
+        "200":
+          description: The push rule was deleted.
+          content:
+            application/json:
+              schema:
+                type: object  # empty json object
+              examples:
+                response:
+                  value: {}
+        "404":
+          description: The push rule does not exist.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NOT_FOUND",
+                    "error": "The push rule was not found."
+                  }
+      tags:
+        - Push notifications
+    put:
+      summary: Add or change a push rule.
+      description: |-
+        This endpoint allows the creation and modification of user defined push
+        rules.
+
+        If a rule with the same `rule_id` already exists among rules of the same
+        kind, it is updated with the new parameters, otherwise a new rule is
+        created.
+
+        If both `after` and `before` are provided, the new or updated rule must
+        be the next most important rule with respect to the rule identified by
+        `before`.
+
+        If neither `after` nor `before` are provided and the rule is created, it
+        should be added as the most important user defined rule among rules of
+        the same kind.
+
+        When creating push rules, they MUST be enabled by default.
+      operationId: setPushRule
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: kind
+          required: true
+          description: |
+            The kind of rule
+          example: content
+          schema:
+            type: string
+            enum:
+              - override
+              - underride
+              - sender
+              - room
+              - content
+        - in: path
+          name: ruleId
+          required: true
+          description: |
+            The identifier for the rule. If the string starts with a dot ("."),
+            the request MUST be rejected as this is reserved for server-default
+            rules. Slashes ("/") and backslashes ("\\") are also not allowed.
+          example: nocake
+          schema:
+            type: string
+        - in: query
+          name: before
+          required: false
+          description: |-
+            Use 'before' with a `rule_id` as its value to make the new rule the
+            next-most important rule with respect to the given user defined rule.
+            It is not possible to add a rule relative to a predefined server rule.
+          example: someRuleId
+          schema:
+            type: string
+        - in: query
+          name: after
+          required: false
+          description: |-
+            This makes the new rule the next-less important rule relative to the
+            given user defined rule. It is not possible to add a rule relative
+            to a predefined server rule.
+          example: anotherRuleId
+          schema:
+            type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              example: {
+                "pattern": "cake*lie",
+                "actions": [
+                  "notify"
+                ]
+              }
+              properties:
+                actions:
+                  type: array
+                  description: The action(s) to perform when the conditions for this rule are met.
+                  items:
+                    type: ["string", "object"]
+                conditions:
+                  type: array
+                  description: |-
+                    The conditions that must hold true for an event in order for a
+                    rule to be applied to an event. A rule with no conditions
+                    always matches. Only applicable to `underride` and `override` rules.
+                  items:
+                    $ref: definitions/push_condition.yaml
+                pattern:
+                  type: string
+                  description: Only applicable to `content` rules. The glob-style pattern to match
+                    against.
+              required:
+                - actions
+        description: |-
+          The push rule data. Additional top-level keys may be present depending
+          on the parameters for the rule `kind`.
+        required: true
+      responses:
+        "200":
+          description: The push rule was created/updated.
+          content:
+            application/json:
+              schema:
+                type: object  # empty json object
+              examples:
+                response:
+                  value: {}
+        "400":
+          description: There was a problem configuring this push rule.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "error": "before/after rule not found: someRuleId",
+                    "errcode": "M_UNKNOWN"
+                  }
+        "404":
+          description: The push rule does not exist (when updating a push rule).
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NOT_FOUND",
+                    "error": "The push rule was not found."
+                  }
+        "429":
+          description: This request was rate-limited.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/rate_limited.yaml
+      tags:
+        - Push notifications
+  "/pushrules/global/{kind}/{ruleId}/enabled":
+    get:
+      summary: Get whether a push rule is enabled
+      description: This endpoint gets whether the specified push rule is enabled.
+      operationId: isPushRuleEnabled
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: kind
+          required: true
+          description: |
+            The kind of rule
+          example: content
+          schema:
+            type: string
+            enum:
+              - override
+              - underride
+              - sender
+              - room
+              - content
+        - in: path
+          name: ruleId
+          required: true
+          description: |
+            The identifier for the rule.
+          example: nocake
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Whether the push rule is enabled.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  enabled:
+                    type: boolean
+                    description: Whether the push rule is enabled or not.
+                required:
+                  - enabled
+              examples:
+                response:
+                  value: {
+                    "enabled": true
+                  }
+        "404":
+          description: The push rule does not exist.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NOT_FOUND",
+                    "error": "The push rule was not found."
+                  }
+      tags:
+        - Push notifications
+    put:
+      summary: Enable or disable a push rule.
+      description: This endpoint allows clients to enable or disable the specified
+        push rule.
+      operationId: setPushRuleEnabled
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: kind
+          required: true
+          description: |
+            The kind of rule
+          example: content
+          schema:
+            type: string
+            enum:
+              - override
+              - underride
+              - sender
+              - room
+              - content
+        - in: path
+          name: ruleId
+          required: true
+          description: |
+            The identifier for the rule.
+          example: nocake
+          schema:
+            type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                enabled:
+                  type: boolean
+                  description: Whether the push rule is enabled or not.
+              required:
+                - enabled
+              example: {
+                "enabled": true
+              }
+        description: |
+          Whether the push rule is enabled or not.
+        required: true
+      responses:
+        "200":
+          description: The push rule was enabled or disabled.
+          content:
+            application/json:
+              schema:
+                type: object
+              examples:
+                response:
+                  value: {}
+        "404":
+          description: The push rule does not exist.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NOT_FOUND",
+                    "error": "The push rule was not found."
+                  }
+      tags:
+        - Push notifications
+  "/pushrules/global/{kind}/{ruleId}/actions":
+    get:
+      summary: The actions for a push rule
+      description: This endpoint get the actions for the specified push rule.
+      operationId: getPushRuleActions
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: kind
+          required: true
+          description: |
+            The kind of rule
+          example: content
+          schema:
+            type: string
+            enum:
+              - override
+              - underride
+              - sender
+              - room
+              - content
+        - in: path
+          name: ruleId
+          required: true
+          description: |
+            The identifier for the rule.
+          example: nocake
+          schema:
+            type: string
+      responses:
+        "200":
+          description: The actions for this push rule.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  actions:
+                    type: array
+                    description: The action(s) to perform for this rule.
+                    items:
+                      type: ["string", "object"]
+                required:
+                  - actions
+              examples:
+                response:
+                  value: {
+                    "actions": [
+                      "notify",
+                      {
+                        "set_tweak": "sound",
+                        "value": "bing"
+                      }
+                    ]
+                  }
+        "404":
+          description: The push rule does not exist.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NOT_FOUND",
+                    "error": "The push rule was not found."
+                  }
+      tags:
+        - Push notifications
+    put:
+      summary: Set the actions for a push rule.
+      description: |-
+        This endpoint allows clients to change the actions of a push rule.
+        This can be used to change the actions of builtin rules.
+      operationId: setPushRuleActions
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: kind
+          required: true
+          description: |
+            The kind of rule
+          example: room
+          schema:
+            type: string
+            enum:
+              - override
+              - underride
+              - sender
+              - room
+              - content
+        - in: path
+          name: ruleId
+          required: true
+          description: |
+            The identifier for the rule.
+          example: "#spam:example.com"
+          schema:
+            type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                actions:
+                  type: array
+                  description: The action(s) to perform for this rule.
+                  items:
+                    type: ["string", "object"]
+              required:
+                - actions
+              example: {
+                "actions": [
+                  "notify",
+                  {
+                    "set_tweak": "highlight"
+                  }
+                ]
+              }
+        description: |
+          The action(s) to perform when the conditions for this rule are met.
+        required: true
+      responses:
+        "200":
+          description: The actions for the push rule were set.
+          content:
+            application/json:
+              schema:
+                type: object
+              examples:
+                response:
+                  value: {}
+        "404":
+          description: The push rule does not exist.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NOT_FOUND",
+                    "error": "The push rule was not found."
+                  }
+      tags:
+        - Push notifications
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/client/v3
+components:
+  securitySchemes:
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer