matrix-spec/api/identity/lookup.yaml

# Copyright 2016 OpenMarket Ltd
# Copyright 2017 Kamax.io
# Copyright 2017 New Vector 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 Identity Service Lookup  API"
  version: "1.0.0"
host: localhost:8090
schemes:
  - https
basePath: /_matrix/identity/api/v1
consumes:
  - application/json
produces:
  - application/json
paths:
  "/lookup":
    get:
      summary: Look up the Matrix user ID for a 3pid.
      description: Look up the Matrix user ID for a 3pid.
      operationId: lookupUser
      parameters:
        - in: query
          type: string
          name: medium
          required: true
          description: The medium type of the 3pid. See the `3PID Types`_ Appendix.
          x-example: "email"
        - in: query
          type: string
          name: address
          required: true
          description: The address of the 3pid being looked up. See the `3PID Types`_ Appendix.
          x-example: "louise@bobs.burgers"
      responses:
        200:
          description:
            The association for that 3pid, or an empty object if no association is known.
          examples:
            application/json: {
              "address": "louise@bobs.burgers",
              "medium": "email",
              "mxid": "@ears:matrix.org",
              "not_before": 1428825849161,
              "not_after": 4582425849161,
              "ts": 1428825849161,
              "signatures": {
                "matrix.org": {
                  "ed25519:0": "ENiU2YORYUJgE6WBMitU0mppbQjidDLanAusj8XS2nVRHPu+0t42OKA/r6zV6i2MzUbNQ3c3MiLScJuSsOiVDQ"
                }
              }
            }
          schema:
            type: object
            properties:
              address:
                type: string
                description: The 3pid address of the user being looked up, matching the address requested.
              medium:
                type: string
                description: A medium from the `3PID Types`_ Appendix, matching the medium requested.
              mxid:
                type: string
                description: The Matrix user ID associated with the 3pid.
              not_before:
                type: integer
                description: A unix timestamp before which the association is not known to be valid.
              not_after:
                type: integer
                description: A unix timestamp after which the association is not known to be valid.
              ts:
                type: integer
                description: The unix timestamp at which the association was verified.
              signatures:
                type: object
                description: The signatures of the verifying identity servers which show that the association should be trusted, if you trust the verifying identity servers.
                $ref: "../../schemas/server-signatures.yaml"
            required:
              - address
              - medium
              - mxid
              - not_before
              - not_after
              - ts
              - signatures
  "/bulk_lookup":
    post:
      summary: Lookup Matrix user IDs for a list of 3pids.
      description: Lookup Matrix user IDs for a list of 3pids.
      operationId: lookupUsers
      parameters:
        - in: body
          name: body
          schema:
            type: object
            example: {
              "threepids":
              [
                ["email","user@example.org"],
                ["msisdn", "123456789"],
                ["email","user2@example.org"]
              ]
            }
            properties:
              threepids:
                type: array
                items:
                  type: array
                  title: 3PID mappings
                  minItems: 2
                  maxItems: 2
                  items:
                    # TODO: Give real names to these values. Adding a `title` does not work.
                    #- type: 3PID Medium
                    #- type: 3PID Address
                    - type: string
                    - type: string
                description: |-
                  An array of arrays containing the `3PID Types`_ with the ``medium``
                  in first position and the ``address`` in second position.
            required:
              - "threepids"
      responses:
        200:
          description: A list of known 3PID mappings for the supplied 3PIDs.
          examples:
            application/json: {
              "threepids": [
                ["email","user@example.org", "@bla:example.org"],
                ["msisdn", "123456789", "@blah2:example.com"]
              ]
            }
          schema:
            type: object
            properties:
              threepids:
                type: array
                items:
                  type: array
                  title: 3PID mappings
                  minItems: 3
                  maxItems: 3
                  items:
                    # TODO: Give real names to these values. Adding a `title` does not work.
                    #- type: 3PID Medium
                    #- type: 3PID Address
                    #- type: Matrix User ID
                    - type: string
                    - type: string
                    - type: string
                description: |-
                  An array of array containing the `3PID Types`_ with the ``medium``
                  in first position, the ``address`` in second position and Matrix user
                  ID in third position.
            required:
              - "threepids"