# Copyright 2016 OpenMarket Ltd # 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 Application Service API" version: "1.0.0" host: localhost:8008 schemes: - https - http basePath: "/" consumes: - application/json produces: - application/json paths: "/transactions/{txnId}": put: summary: Send some events to the application service. description: |- This API is called by the homeserver when it wants to push an event (or batch of events) to the application service. operationId: sendTransaction 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: A list of events schema: type: object example: { "events": [ { "age": 32, "content": { "body": "incoming message", "msgtype": "m.text" }, "event_id": "$14328055551tzaee:localhost", "origin_server_ts": 1432804485886, "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", "type": "m.room.message", "user_id": "@bob:localhost" }, { "age": 1984, "content": { "body": "another incoming message", "msgtype": "m.text" }, "event_id": "$1228055551ffsef:localhost", "origin_server_ts": 1432804485886, "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", "type": "m.room.message", "user_id": "@bob:localhost" } ] } description: "Transaction informations" properties: events: type: array description: A list of events items: type: object title: Event required: ["events"] responses: 200: description: The transaction was processed successfully. examples: application/json: { } schema: type: object "/rooms/{roomAlias}": get: summary: Query if a room alias should exist on the application service. description: |- This endpoint is invoked by the homeserver on an application service to query the existence of a given room alias. The homeserver will only query room aliases inside the application service's ``aliases`` namespace. The homeserver will send this request when it receives a request to join a room alias within the application service's namespace. operationId: queryRoomByAlias parameters: - in: path name: roomAlias type: string description: The room alias being queried. required: true x-example: "#magicforest:example.com" responses: 200: description: |- The application service indicates that this room alias exists. The application service MUST have created a room and associated it with the queried room alias using the client-server API. Additional information about the room such as its name and topic can be set before responding. examples: application/json: { } schema: type: object 401: description: |- The homeserver has not supplied credentials to the application service. Optional error information can be included in the body of this response. examples: application/json: { "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" } schema: $ref: ../client-server/definitions/errors/error.yaml 403: description: |- The credentials supplied by the homeserver were rejected. examples: application/json: { "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" } schema: $ref: ../client-server/definitions/errors/error.yaml 404: description: |- The application service indicates that this room alias does not exist. Optional error information can be included in the body of this response. examples: application/json: { "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" } schema: $ref: ../client-server/definitions/errors/error.yaml "/users/{userId}": get: summary: Query if a user should exist on the application service. description: |- This endpoint is invoked by the homeserver on an application service to query the existence of a given user ID. The homeserver will only query user IDs inside the application service's ``users`` namespace. The homeserver will send this request when it receives an event for an unknown user ID in the application service's namespace. operationId: queryUserById parameters: - in: path name: userId type: string description: The user ID being queried. required: true x-example: "@alice:example.com" responses: 200: description: |- The application service indicates that this user exists. The application service MUST create the user using the client-server API. examples: application/json: { } schema: type: object 401: description: |- The homeserver has not supplied credentials to the application service. Optional error information can be included in the body of this response. examples: application/json: { "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" } schema: $ref: ../client-server/definitions/errors/error.yaml 403: description: |- The credentials supplied by the homeserver were rejected. examples: application/json: { "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" } schema: $ref: ../client-server/definitions/errors/error.yaml 404: description: |- The application service indicates that this user does not exist. Optional error information can be included in the body of this response. examples: application/json: { "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" } schema: $ref: ../client-server/definitions/errors/error.yaml "/_matrix/app/unstable/thirdparty/protocol/{protocol}": get: summary: Retrieve metadata about a specific protocol that the application service supports. description: |- This API is called by the homeserver when it wants to present clients with specific information about the various third party networks that an application service supports. operationId: getProtocolMetadata parameters: - in: path name: protocol type: string description: The protocol ID. required: true x-example: "irc" responses: 200: description: The protocol was found and metadata returned. schema: $ref: definitions/protocol_metadata.yaml 401: description: |- The homeserver has not supplied credentials to the application service. Optional error information can be included in the body of this response. examples: application/json: { "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" } schema: $ref: ../client-server/definitions/errors/error.yaml 403: description: |- The credentials supplied by the homeserver were rejected. examples: application/json: { "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" } schema: $ref: ../client-server/definitions/errors/error.yaml 404: description: No protocol was found with the given path. examples: application/json: { "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" } schema: $ref: ../client-server/definitions/errors/error.yaml "/_matrix/app/unstable/thirdparty/user/{protocol}": get: summary: Retrieve the Matrix User ID of a corresponding third party user. description: |- This API is called by the homeserver in order to retrieve a Matrix User ID linked to a user on the third party network, given a set of user parameters. operationId: queryUserByProtocol parameters: - in: path name: protocol type: string description: The protocol ID. required: true x-example: irc - in: query name: fields... type: string description: |- One or more custom fields that are passed to the application service to help identify the user. responses: 200: description: The Matrix User IDs found with the given parameters. schema: $ref: definitions/user_batch.yaml 401: description: |- The homeserver has not supplied credentials to the application service. Optional error information can be included in the body of this response. examples: application/json: { "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" } schema: $ref: ../client-server/definitions/errors/error.yaml 403: description: |- The credentials supplied by the homeserver were rejected. examples: application/json: { "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" } schema: $ref: ../client-server/definitions/errors/error.yaml 404: description: No users were found with the given parameters. examples: application/json: { "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" } schema: $ref: ../client-server/definitions/errors/error.yaml "/_matrix/app/unstable/thirdparty/location/{protocol}": get: summary: Retreive Matrix-side portal rooms leading to a third party location. description: |- Retrieve a list of Matrix portal rooms that lead to the matched third party location. operationId: queryLocationByProtocol parameters: - in: path name: protocol type: string description: The protocol ID. required: true x-example: irc - in: query name: fields... type: string description: |- One or more custom fields that are passed to the application service to help identify the third party location. responses: 200: description: At least one portal room was found. schema: $ref: definitions/location_batch.yaml 401: description: |- The homeserver has not supplied credentials to the application service. Optional error information can be included in the body of this response. examples: application/json: { "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" } schema: $ref: ../client-server/definitions/errors/error.yaml 403: description: |- The credentials supplied by the homeserver were rejected. examples: application/json: { "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" } schema: $ref: ../client-server/definitions/errors/error.yaml 404: description: No mappings were found with the given parameters. examples: application/json: { "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" } schema: $ref: ../client-server/definitions/errors/error.yaml "/_matrix/app/unstable/thirdparty/location": get: summary: Reverse-lookup third party locations given a Matrix room alias. description: |- Retreive an array of third party network locations from a Matrix room alias. operationId: queryLocationByAlias parameters: - in: query name: alias type: string description: The Matrix room alias to look up. responses: 200: description: |- All found third party locations. schema: $ref: definitions/location_batch.yaml 401: description: |- The homeserver has not supplied credentials to the application service. Optional error information can be included in the body of this response. examples: application/json: { "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" } schema: $ref: ../client-server/definitions/errors/error.yaml 403: description: |- The credentials supplied by the homeserver were rejected. examples: application/json: { "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" } schema: $ref: ../client-server/definitions/errors/error.yaml 404: description: No mappings were found with the given parameters. examples: application/json: { "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" } schema: $ref: ../client-server/definitions/errors/error.yaml "/_matrix/app/unstable/thirdparty/user": get: summary: Reverse-lookup third party users given a Matrix User ID. description: |- Retreive an array of third party users from a Matrix User ID. operationId: queryUserByID parameters: - in: query name: userid type: string description: The Matrix User ID to look up. responses: 200: description: |- An array of third party users. schema: $ref: definitions/user_batch.yaml 401: description: |- The homeserver has not supplied credentials to the application service. Optional error information can be included in the body of this response. examples: application/json: { "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" } schema: $ref: ../client-server/definitions/errors/error.yaml 403: description: |- The credentials supplied by the homeserver were rejected. examples: application/json: { "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" } schema: $ref: ../client-server/definitions/errors/error.yaml 404: description: No mappings were found with the given parameters. examples: application/json: { "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" } schema: $ref: ../client-server/definitions/errors/error.yaml