# 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 500: description: There was a problem completing the request. 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: type: object 403: description: |- The credentials supplied by the homeserver were rejected. examples: application/json: { "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" } schema: type: object 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: type: object 500: description: There was a problem completing the request. examples: application/json: { } schema: type: object "/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: type: object 403: description: |- The credentials supplied by the homeserver were rejected. examples: application/json: { "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" } schema: type: object 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: type: object 500: description: There was a problem completing the request. examples: application/json: { } schema: type: object "/_matrix/app/unstable/thirdparty/{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: queryMetadata parameters: - in: path name: protocol type: string description: |- The name of the protocol. required: true x-example: "irc" responses: 200: description: The protocol was found and metadata returned. examples: application/json: { "user_fields": ["network", "nickname"], "location_fields": ["network", "channel"], "icon": "mxc://example.org/aBcDeFgH", "field_types": { "network": { "regexp": "([a-z0-9]+\\.)*[a-z0-9]+", "placeholder": "irc.example.org" }, "nickname": { "regexp": "[^\\s]+", "placeholder": "username" }, "channel": { "regexp": "#[^\\s]+", "placeholder": "#foobar" } }, "instances": [ { "desc": "Freenode", "icon": "mxc://example.org/JkLmNoPq", "fields": { "network": "freenode.net", } } ] } 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: type: object 403: description: |- The credentials supplied by the homeserver were rejected. examples: application/json: { "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" } schema: type: object 404: description: No protocol was found with the given path. examples: application/json: { "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" } schema: type: object 500: description: There was a problem completing the request. examples: application/json: { } schema: type: object "/_matrix/app/unstable/thirdparty/user/{protocol}": get: summary: Retrieve the Matrix ID of a corresponding third party user. description: |- This API is called by the homeserver in order to retrieve a Matrix ID linked to a user on the external service, given a set of user parameters. operationId: queryUserByProtocol parameters: - in: path name: protocol type: string description: |- The name of the protocol. required: true x-example: irc - in: query name: field1, field2... 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 IDs found with the given parameters. examples: application/json: [{ "userid": "@_gitter_jim:matrix.org", "protocol": "gitter", "fields": { "user": "jim" } }] schema: type: array description: Matched users. items: type: object title: User properties: userid: type: string description: The Matrix ID of the matched user. protocol: type: string description: The third party protocol. fields: type: object description: The third party network fields used to identify this user. properties: user: type: string description: An example field, in this case the username for a Gitter user. 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: type: object 403: description: |- The credentials supplied by the homeserver were rejected. examples: application/json: { "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" } schema: type: object 404: description: No users were found with the given parameters. examples: application/json: { "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" } schema: type: object 500: description: There was a problem completing the request. examples: application/json: { } schema: type: object "/_matrix/app/unstable/thirdparty/location/{protocol}": get: summary: Retreive Matrix-side portal rooms leading to a third party location. description: |- Requesting this endpoint with a valid protocol name results in a list of successful mapping results in a JSON array. Each result contains objects to represent the Matrix room or rooms that represent a portal to this third party network. Each has the Matrix room alias string, an identifier for the particular third party network protocol, and an object containing the network-specific fields that comprise this identifier. It should attempt to canonicalise the identifier as much as reasonably possible given the network type. operationId: queryLocationByProtocol parameters: - in: path name: protocol type: string description: The protocol used to communicate to the third party network. required: true x-example: "irc" - in: query name: field1, field2... 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. examples: application/json: [{ "alias": "#freenode_#matrix:matrix.org", "protocol": "irc", "fields": { "network": "freenode", "channel": "#matrix" } }] schema: type: array description: |- Array of portal rooms leading to the requested third party location. items: type: object title: Portal Room 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: type: object 403: description: |- The credentials supplied by the homeserver were rejected. examples: application/json: { "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" } schema: type: object 404: description: No mappings were found with the given parameters. examples: application/json: { "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" } schema: type: object 500: description: There was a problem completing the request. examples: application/json: { } schema: type: object "/_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. Same response format as the forward lookup response. examples: application/json: [{ "alias": "#freenode_#matrix:matrix.org", "protocol": "irc", "fields": { "network": "freenode", "channel": "#matrix" } }] schema: type: array description: Matched third party locations. items: type: object title: Location 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: type: object 403: description: |- The credentials supplied by the homeserver were rejected. examples: application/json: { "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" } schema: type: object 404: description: No mappings were found with the given parameters. examples: application/json: { "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" } schema: type: object 500: description: There was a problem completing the request. examples: application/json: { } schema: type: object "/_matrix/app/unstable/thirdparty/user": get: summary: Reverse-lookup third party users given a Matrix ID. description: |- Retreive an array of third party users from a Matrix ID. operationId: queryUserByID paramters: - in: query name: userid type: string description: The Matrix ID to look up. responses: 200: description: |- An array of third party users. examples: application/json: [{ "userid": "@_gitter_jim:matrix.org", "protocol": "gitter", "fields": { "user": "jim" } }] schema: type: array description: Matched third party users items: type: object title: User 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: type: object 403: description: |- The credentials supplied by the homeserver were rejected. examples: application/json: { "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" } schema: type: object 404: description: No mappings were found with the given parameters. examples: application/json: { "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" } schema: type: object 500: description: There was a problem completing the request. examples: application/json: { } schema: type: object