# Copyright 2018 New Vector 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 Federation Transaction API
  version: 1.0.0
paths:
  "/send/{txnId}":
    put:
      summary: Send a transaction
      description: |-
        Push messages representing live activity to another server. The destination name
        will be set to that of the receiving server itself. Each embedded PDU in the
        transaction body will be processed.

        The sending server must wait and retry for a 200 OK response before sending a
        transaction with a different `txnId` to the receiving server.

        Note that events have a different format depending on the room version - check
        the [room version specification](/rooms) for precise event formats.
      operationId: sendTransaction
      security:
        - signedRequest: []
      parameters:
        - in: path
          name: txnId
          description: The transaction ID.
          required: true
          example: S0meTransacti0nId
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: definitions/transaction.yaml
                - type: object
                  properties:
                    edus:
                      type: array
                      description: |-
                        List of ephemeral messages. May be omitted if there are no ephemeral
                        messages to be sent. Must not include more than 100 EDUs.
                      items:
                        $ref: definitions/edu_with_example.yaml
              type: object
        required: true
      responses:
        "200":
          description: |-
            The result of processing the transaction. The server is to use this response even in
            the event of one or more PDUs failing to be processed.
          content:
            application/json:
              schema:
                type: object
                title: PDU Processing Results
                description: The results for the processing of each PDU in the transaction.
                properties:
                  pdus:
                    type: object
                    description: |-
                      The PDUs from the original transaction. The string key represents the ID of the
                      PDU (event) that was processed.
                    patternProperties:
                      "^\\$":
                        x-pattern-format: mx-event-id
                        type: object
                        title: PDU Processing Result
                        description: Information about how the PDU was handled.
                        properties:
                          error:
                            type: string
                            description: |-
                              A human readable description about what went wrong in processing this PDU.
                              If no error is present, the PDU can be considered successfully handled.
                            example: You are not allowed to send a message to this room.
                required:
                  - pdus
              examples:
                response:
                  value: {
                    "pdus": {
                      "$successful_event:example.org": {},
                      "$failed_event:example.org": {
                        "error": "You are not allowed to send a message to this room."
                      }
                    }
                  }
servers:
  - url: "{protocol}://{hostname}{basePath}"
    variables:
      protocol:
        enum:
          - http
          - https
        default: https
      hostname:
        default: localhost:8448
      basePath:
        default: /_matrix/federation/v1
components:
  securitySchemes:
    signedRequest:
      $ref: definitions/security.yaml#/signedRequest