# 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. swagger: '2.0' info: title: "Matrix Federation Events API" version: "1.0.0" host: localhost:8448 schemes: - https basePath: /_matrix/federation/v1 consumes: - application/json produces: - application/json paths: "/backfill/{roomId}": get: summary: Retrieves the events which precede the given event description: |- Retrieves a sliding-window history of previous PDUs that occurred in the given room. Starting from the PDU ID(s) given in the ``v`` argument, the PDUs that preceded it are retrieved, up to the total number given by the ``limit``. operationId: backfillRoom parameters: - in: path name: roomId type: string description: The room ID to backfill. required: true x-example: "!SomeRoom:matrix.org" - in: query name: v type: array items: type: string description: The event IDs to backfill from. required: true x-example: ["$abc123:matrix.org"] - in: query name: limit type: integer description: The maximum number of PDUs to retrieve, including the given events. required: true x-example: 2 responses: 200: description: |- A transaction containing the PDUs that preceded the given event(s), including the given event(s), up to the given limit. schema: $ref: "definitions/transaction.yaml" # Override the example to show the response of the request a bit better examples: application/json: { "$ref": "examples/transaction.json", "pdus": [ { "$ref": "pdu.json", "room_id": "!SomeRoom:matrix.org", "event_id": "$abc123:matrix.org" }, { "$ref": "pdu.json", "room_id": "!SomeRoom:matrix.org" }, ] } "/get_missing_events/{roomId}": post: summary: Retrieves events that the sender is missing description: |- Retrieves the previous events that the sender is missing for a given set of events. operationId: getMissingPreviousEvents parameters: - in: path name: roomId type: string description: The room ID to search in. required: true x-example: "!SomeRoom:matrix.org" - in: body name: body schema: type: object properties: limit: type: integer description: The maximum number of events to retrieve. Defaults to 10. example: 10 min_depth: type: integer description: The minimum depth of events to retrieve. Defaults to 0. example: 0 earliest_events: type: array description: |- The events the sender is missing. The response will only contain events that didn't happen before these events. items: type: string example: ["$missing_event:domain.com"] latest_events: type: array description: |- The events that the sender has, but does not have previous events for. items: type: string example: ["$event_that_has_the_missing_event_as_a_previous_event:domain.com"] required: ['earliest_events', 'latest_events'] responses: 200: description: |- The events that happened after the ``earliest_events`` which are also previous to the ``latest_events`` and have the minimum depth specified. Does not include any of the events in the request. schema: type: object properties: events: type: array description: The missing events. items: $ref: definitions/pdu.yaml required: ['events'] examples: application/json: { "events": [ {"$ref": "examples/pdu.json"} ] }