# Copyright 2016 OpenMarket 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 Client-Server device management API" version: "1.0.0" host: localhost:8008 schemes: - https - http basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% consumes: - application/json produces: - application/json securityDefinitions: $ref: definitions/security.yaml paths: "/devices": get: summary: List registered devices for the current user description: |- Gets information about all devices for the current user. operationId: getDevices security: - accessToken: [] responses: 200: description: Device information schema: type: object properties: devices: type: array description: A list of all registered devices for this user. items: type: object allOf: - $ref: "definitions/client_device.yaml" examples: application/json: { "devices": [ { "device_id": "QBUAZIFURK", "display_name": "android", "last_seen_ip": "1.2.3.4", "last_seen_ts": 1474491775024 } ] } tags: - Device management "/devices/{deviceId}": get: summary: Get a single device description: |- Gets information on a single device, by device id. operationId: getDevice security: - accessToken: [] parameters: - in: path type: string name: deviceId description: The device to retrieve. required: true x-example: "QBUAZIFURK" responses: 200: description: Device information schema: type: object allOf: - $ref: "definitions/client_device.yaml" examples: application/json: { "device_id": "QBUAZIFURK", "display_name": "android", "last_seen_ip": "1.2.3.4", "last_seen_ts": 1474491775024 } 404: description: The current user has no device with the given ID. tags: - Device management put: summary: Update a device description: |- Updates the metadata on the given device. operationId: updateDevice security: - accessToken: [] parameters: - in: path type: string name: deviceId description: The device to update. required: true x-example: "QBUAZIFURK" - in: body name: body required: true description: New information for the device. schema: type: object properties: display_name: type: string description: |- The new display name for this device. If not given, the display name is unchanged. example: { "display_name": "My other phone" } responses: 200: description: The device was successfully updated. examples: application/json: { } schema: type: object # empty json object 404: description: The current user has no device with the given ID. tags: - Device management delete: summary: Delete a device description: |- This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api). Deletes the given device, and invalidates any access token associated with it. operationId: deleteDevice security: - accessToken: [] parameters: - in: path type: string name: deviceId description: The device to delete. required: true x-example: "QBUAZIFURK" - in: body name: body required: true schema: type: object properties: auth: description: |- Additional authentication information for the user-interactive authentication API. allOf: - "$ref": "definitions/auth_data.yaml" responses: 200: description: |- The device was successfully removed, or had been removed previously. schema: type: object examples: application/json: { } 401: description: |- The homeserver requires additional authentication information. schema: "$ref": "definitions/auth_response.yaml" tags: - Device management "/delete_devices": post: summary: Bulk deletion of devices description: |- This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api). Deletes the given devices, and invalidates any access token associated with them. operationId: deleteDevices security: - accessToken: [] parameters: - in: body name: body required: true schema: type: object properties: devices: type: array description: The list of device IDs to delete. items: type: string description: A list of device IDs. example: ["QBUAZIFURK", "AUIECTSRND"] auth: allOf: - "$ref": "definitions/auth_data.yaml" description: |- Additional authentication information for the user-interactive authentication API. required: - devices responses: 200: description: |- The devices were successfully removed, or had been removed previously. schema: type: object examples: application/json: { } 401: description: |- The homeserver requires additional authentication information. schema: "$ref": "definitions/auth_response.yaml" tags: - Device management