# 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:
        - accessToken: []
      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:
                      type: object
                      allOf:
                        - $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:
        - accessToken: []
      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:
                type: object
                allOf:
                  - $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:
        - accessToken: []
      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:
        - accessToken: []
      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:
        - accessToken: []
      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:
    $ref: definitions/security.yaml