# 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. openapi: 3.1.0 info: title: Matrix Client-Server device management API version: 1.0.0 paths: /devices: get: summary: List registered devices for the current user description: Gets information about all devices for the current user. operationId: getDevices security: - accessTokenQuery: [] - accessTokenBearer: [] responses: "200": description: Device information content: application/json: schema: type: object properties: devices: type: array description: A list of all registered devices for this user. items: $ref: definitions/client_device.yaml examples: response: value: { "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: - accessTokenQuery: [] - accessTokenBearer: [] parameters: - in: path name: deviceId description: The device to retrieve. required: true example: QBUAZIFURK schema: type: string responses: "200": description: Device information content: application/json: schema: $ref: definitions/client_device.yaml examples: response: value: { "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: - accessTokenQuery: [] - accessTokenBearer: [] parameters: - in: path name: deviceId description: The device to update. required: true example: QBUAZIFURK schema: type: string requestBody: content: application/json: 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" } description: New information for the device. required: true responses: "200": description: The device was successfully updated. content: application/json: schema: type: object # empty json object examples: response: value: {} "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: - accessTokenQuery: [] - accessTokenBearer: [] parameters: - in: path name: deviceId description: The device to delete. required: true example: QBUAZIFURK schema: type: string requestBody: content: application/json: schema: type: object properties: auth: description: |- Additional authentication information for the user-interactive authentication API. allOf: - $ref: definitions/auth_data.yaml required: true responses: "200": description: |- The device was successfully removed, or had been removed previously. content: application/json: schema: type: object examples: response: value: {} "401": description: The homeserver requires additional authentication information. content: application/json: 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: - accessTokenQuery: [] - accessTokenBearer: [] requestBody: content: application/json: 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 required: true responses: "200": description: |- The devices were successfully removed, or had been removed previously. content: application/json: schema: type: object examples: response: value: {} "401": description: The homeserver requires additional authentication information. content: application/json: schema: $ref: definitions/auth_response.yaml tags: - Device management servers: - url: "{protocol}://{hostname}{basePath}" variables: protocol: enum: - http - https default: https hostname: default: localhost:8008 basePath: default: /_matrix/client/v3 components: securitySchemes: accessTokenQuery: $ref: definitions/security.yaml#/accessTokenQuery accessTokenBearer: $ref: definitions/security.yaml#/accessTokenBearer