matrix-spec/data/api/client-server/tags.yaml

# Copyright 2016 OpenMarket 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.
openapi: 3.1.0
info:
  title: Matrix Client-Server tag API
  version: 1.0.0
paths:
  "/user/{userId}/rooms/{roomId}/tags":
    get:
      summary: List the tags for a room.
      description: List the tags set by a user on a room.
      operationId: getRoomTags
      security:
        - accessToken: []
      parameters:
        - in: path
          name: userId
          required: true
          description: |-
            The id of the user to get tags for. The access token must be
            authorized to make requests for this user ID.            
          example: "@alice:example.com"
          schema:
            type: string
        - in: path
          name: roomId
          required: true
          description: The ID of the room to get tags for.
          example: "!726s6s6q:example.com"
          schema:
            type: string
      responses:
        "200":
          description: The list of tags for the user for the room.
          content:
            application/json:
              schema:
                type: object
                properties:
                  tags:
                    type: object
                    additionalProperties:
                      title: Tag
                      type: object
                      properties:
                        order:
                          type: number
                          format: float
                          description: |-
                            A number in a range `[0,1]` describing a relative
                            position of the room under the given tag.                            
                      additionalProperties: true
              examples:
                response:
                  value: {
                    "tags": {
                      "m.favourite": {
                        "order": 0.1
                      },
                      "u.Work": {
                        "order": 0.7
                      },
                      "u.Customers": {}
                    }
                  }
      tags:
        - User data
  "/user/{userId}/rooms/{roomId}/tags/{tag}":
    put:
      summary: Add a tag to a room.
      description: Add a tag to the room.
      operationId: setRoomTag
      security:
        - accessToken: []
      parameters:
        - in: path
          name: userId
          required: true
          description: |-
            The id of the user to add a tag for. The access token must be
            authorized to make requests for this user ID.            
          example: "@alice:example.com"
          schema:
            type: string
        - in: path
          name: roomId
          required: true
          description: The ID of the room to add a tag to.
          example: "!726s6s6q:example.com"
          schema:
            type: string
        - in: path
          name: tag
          required: true
          description: The tag to add.
          example: u.work
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                order:
                  type: number
                  format: float
                  description: |-
                    A number in a range `[0,1]` describing a relative
                    position of the room under the given tag.                    
              additionalProperties: true
              example: {
                "order": 0.25
              }
        description: Extra data for the tag, e.g. ordering.
        required: true
      responses:
        "200":
          description: The tag was successfully added.
          content:
            application/json:
              schema:
                type: object
              examples:
                response:
                  value: {}
      tags:
        - User data
    delete:
      summary: Remove a tag from the room.
      description: Remove a tag from the room.
      operationId: deleteRoomTag
      security:
        - accessToken: []
      parameters:
        - in: path
          name: userId
          required: true
          description: |-
            The id of the user to remove a tag for. The access token must be
            authorized to make requests for this user ID.            
          example: "@alice:example.com"
          schema:
            type: string
        - in: path
          name: roomId
          required: true
          description: The ID of the room to remove a tag from.
          example: "!726s6s6q:example.com"
          schema:
            type: string
        - in: path
          name: tag
          required: true
          description: The tag to remove.
          example: u.work
          schema:
            type: string
      responses:
        "200":
          description: The tag was successfully removed.
          content:
            application/json:
              schema:
                type: object
              examples:
                response:
                  value: {}
      tags:
        - User data
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