# Copyright 2023 Tulir Asokan
#
# 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 Application Service API"
  version: "1.0.0"
host: localhost:8008
schemes:
  - https
  - http
basePath: /_matrix/app/v1
produces:
  - application/json
securityDefinitions:
  $ref: definitions/security.yaml
paths:
  "/ping":
    post:
      x-addedInMatrixVersion: "1.7"
      summary: Ping the application service
      description: |-
        This API is called by the homeserver to ensure that the connection works
        and the `hs_token` the homeserver has is correct.

        Currently this is only called by the homeserver as a direct result of
        the application service calling the appservice ping endpoint in the
        client API.
      operationId: ping
      security:
        - homeserverAccessToken: []
      parameters:
        - in: path
          name: txnId
          type: string
          description: |-
            The transaction ID for this set of events. Homeservers generate
            these IDs and they are used to ensure idempotency of requests.
          required: true
          x-example: "35"
        - in: body
          name: body
          description: Ping body with optional transaction ID.
          schema:
            type: object
            example: {
              "transaction_id": "mautrix-go_1683636478256400935_123"
            }
            properties:
              transaction_id:
                type: string
                description: |-
                  A transaction ID for the ping, copied directly from the
                  client API appservice ping call.
            required: ["events"]
      responses:
        200:
          description: The hs_token is valid and the ping request was successful.
          examples:
            application/json: {}
          schema:
            type: object