# Copyright 2018 Travis Ralston
#
# 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 Report Content API
  version: 1.0.0
paths:
  "/rooms/{roomId}/report":
    post:
      x-addedInMatrixVersion: "1.13"
      summary: Report a room as inappropriate.
      description: |-
        Reports a room as inappropriate to the server, which may then notify
        the appropriate people. How such information is delivered is left up to
        implementations. The caller is not required to be joined to the room to
        report it.
      operationId: reportRoom
      parameters:
        - in: path
          name: roomId
          description: The room being reported.
          required: true
          example: "!637q39766251:example.com"
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example: {
                "reason": "this makes me sad"
              }
              properties:
                reason:
                  type: string
                  description: The reason the room is being reported. May be blank.
              required:
                - reason
        required: true
      security:
        - accessTokenQuery: []
        - accessTokenBearer: []
      responses:
        "200":
          description: The room has been reported successfully.
          content:
            application/json:
              schema:
                type: object
              examples:
                response:
                  value: {}
        "404":
          description: |-
            The room was not found on the homeserver.
          content:
            application/json:
              schema:
                $ref: definitions/errors/error.yaml
              examples:
                response:
                  value: {
                    "errcode": "M_NOT_FOUND",
                    "error": "The room was not found."
                  }
        "429":
          description: This request was rate-limited.
          content:
            application/json:
              schema:
                $ref: definitions/errors/rate_limited.yaml
      tags:
        - Reporting content
  "/rooms/{roomId}/report/{eventId}":
    post:
      summary: Report an event in a joined room as inappropriate.
      description: |-
        Reports an event as inappropriate to the server, which may then notify
        the appropriate people. The caller must be joined to the room to report
        it.

        Furthermore, it might be possible for clients to deduce whether a reported
        event exists by timing the response. This is because only a report for an
        existing event will require the homeserver to do further processing. To
        combat this, homeservers MAY add a random delay when generating a response.
      operationId: reportEvent
      parameters:
        - in: path
          name: roomId
          description: The room in which the event being reported is located.
          required: true
          example: "!637q39766251:example.com"
          schema:
            type: string
        - in: path
          name: eventId
          description: The event to report.
          required: true
          example: $something:example.org
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example: {
                "score": -100,
                "reason": "this makes me sad"
              }
              properties:
                score:
                  type: integer
                  description: |-
                    The score to rate this content as where -100 is most offensive
                    and 0 is inoffensive.
                reason:
                  type: string
                  description: The reason the content is being reported.
        required: true
      security:
        - accessTokenQuery: []
        - accessTokenBearer: []
      x-changedInMatrixVersion:
        1.8: |
          This endpoint now requires the user to be joined to the room.
      responses:
        "200":
          description: The event has been reported successfully.
          content:
            application/json:
              schema:
                type: object
              examples:
                response:
                  value: {}
        "404":
          description: |-
            The event was not found or you are not joined to the room where the
            event resides.
            
            Homeserver implementations can additionally return this error if the
            reported event has been redacted.
          content:
            application/json:
              schema:
                $ref: definitions/errors/error.yaml
              examples:
                response:
                  value: {
                    "errcode": "M_NOT_FOUND",
                    "error": "The event was not found or you are not joined to the room."
                  }
      tags:
        - Reporting content
  "/users/{userId}/report":
    post:
      x-addedInMatrixVersion: "1.14"
      summary: Report a user as inappropriate.
      description: |-
        Reports a user as inappropriate to the server, which may then notify
        the appropriate people. How such information is delivered is left up to
        implementations. The caller is not required to be joined to any rooms
        that the reported user is joined to.

        Clients may wish to [ignore](#ignoring-users) users after reporting them.

        Clients could infer whether a reported user exists based on the 404 response.
        Homeservers that wish to conceal this information MAY return 200 responses
        regardless of the existence of the reported user.

        Furthermore, it might be possible for clients to deduce whether a reported
        user exists by timing the response. This is because only a report for an
        existing user will require the homeserver to do further processing. To
        combat this, homeservers MAY add a random delay when generating a response.
      operationId: reportUser
      parameters:
        - in: path
          name: userId
          description: The user being reported.
          required: true
          example: "@someguy:example.com"
          schema:
            type: string
            format: mx-user-id
            pattern: "^@"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example: {
                "reason": "this makes me sad"
              }
              properties:
                reason:
                  type: string
                  description: The reason the room is being reported. May be blank.
              required:
                - reason
        required: true
      security:
        - accessTokenQuery: []
        - accessTokenBearer: []
      responses:
        "200":
          description: |
            The user has been reported successfully or the server chose
            to not disclose whether the users exists.
          content:
            application/json:
              schema:
                type: object
              examples:
                response:
                  value: {}
        "404":
          description: |-
            The user was not found on the homeserver.
          content:
            application/json:
              schema:
                $ref: definitions/errors/error.yaml
              examples:
                response:
                  value: {
                    "errcode": "M_NOT_FOUND",
                    "error": "The user was not found."
                  }
        "429":
          description: This request was rate-limited.
          content:
            application/json:
              schema:
                $ref: definitions/errors/rate_limited.yaml
      tags:
        - Reporting content
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