2016-07-12 16:22:33 +00:00
# Copyright 2016 OpenMarket Ltd
2017-11-14 14:36:38 +00:00
# Copyright 2017 Kamax.io
# Copyright 2017 New Vector Ltd
2018-08-30 02:57:41 +00:00
# Copyright 2018 New Vector Ltd
2016-07-12 16:22:33 +00:00
#
# 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.
2016-03-10 13:59:34 +00:00
swagger : '2.0'
info :
2019-09-10 01:49:49 +00:00
title : "Matrix Identity Service Lookup API"
2016-03-10 13:59:34 +00:00
version : "1.0.0"
host : localhost:8090
schemes :
- https
2016-10-07 17:17:45 +00:00
basePath : /_matrix/identity/api/v1
2018-08-30 02:57:41 +00:00
consumes :
- application/json
2016-03-10 13:59:34 +00:00
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.
2017-08-02 23:19:34 +00:00
operationId : lookupUser
2019-08-28 20:19:13 +00:00
deprecated : true
2016-03-10 13:59:34 +00:00
parameters :
- in : query
type : string
name : medium
required : true
2017-11-14 15:01:58 +00:00
description : The medium type of the 3pid. See the `3PID Types`_ Appendix.
2016-03-10 13:59:34 +00:00
x-example : "email"
- in : query
type : string
name : address
required : true
2017-11-14 15:01:58 +00:00
description : The address of the 3pid being looked up. See the `3PID Types`_ Appendix.
2016-03-10 13:59:34 +00:00
x-example : "louise@bobs.burgers"
responses :
200 :
description :
2018-08-30 02:57:41 +00:00
The association for that 3pid, or an empty object if no association is known.
2016-03-10 13:59:34 +00:00
examples :
2017-09-26 16:53:28 +00:00
application/json : {
2018-08-24 21:53:27 +00:00
"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"
2016-03-10 13:59:34 +00:00
}
}
2018-08-24 21:53:27 +00:00
}
2016-03-10 13:59:34 +00:00
schema :
type : object
properties :
address :
type : string
2018-08-30 02:57:41 +00:00
description : The 3pid address of the user being looked up, matching the address requested.
2016-03-10 13:59:34 +00:00
medium :
type : string
2018-08-30 02:57:41 +00:00
description : A medium from the `3PID Types`_ Appendix, matching the medium requested.
2016-03-10 13:59:34 +00:00
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
2018-08-31 21:03:48 +00:00
description : The signatures of the verifying identity servers which show that the association should be trusted, if you trust the verifying identity servers.
2018-08-24 21:53:27 +00:00
$ref : "../../schemas/server-signatures.yaml"
2018-08-24 21:53:00 +00:00
required :
- address
- medium
- mxid
- not_before
- not_after
- ts
- signatures
2017-10-26 01:04:43 +00:00
"/bulk_lookup" :
post :
2017-10-26 10:37:25 +00:00
summary : Lookup Matrix user IDs for a list of 3pids.
description : Lookup Matrix user IDs for a list of 3pids.
2017-11-14 22:53:36 +00:00
operationId : lookupUsers
2019-08-28 20:19:13 +00:00
deprecated : true
2017-10-26 01:04:43 +00:00
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
2018-08-24 21:53:27 +00:00
minItems : 2
maxItems : 2
2017-10-26 01:04:43 +00:00
items :
2018-08-29 23:52:02 +00:00
# TODO: Give real names to these values. Adding a `title` does not work.
#- type: 3PID Medium
#- type: 3PID Address
- type : string
- type : string
2018-08-30 02:57:41 +00:00
description : |-
An array of arrays containing the `3PID Types`_ with the ``medium``
in first position and the ``address`` in second position.
2017-10-26 01:04:43 +00:00
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
2018-08-24 21:53:27 +00:00
minItems : 3
maxItems : 3
2017-10-26 01:04:43 +00:00
items :
2018-08-29 23:52:02 +00:00
# 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
2018-08-30 02:57:41 +00:00
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.
2017-10-26 01:04:43 +00:00
required :
- "threepids"