matrix-spec/api/application-service/application_service.yaml

# 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.

        The application service should take care to ensure that it handles
        state events by the presence of a ``state_key``, not by 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