# 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. Note that the application service should distinguish state events from message events via the presence of a ``state_key``, rather than via the event type. 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