# 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 Profile API
  version: 1.0.0
paths:
  "/profile/{userId}/{keyName}":
    put:
      x-changedInMatrixVersion:
        "1.14": Endpoint now accepts variable `keyName` parameter.
      summary: Set a profile field for a user.
      description: |-
        Set or update a profile field for a user.
        Must be authenticated with an access token authorised to make changes.
        Servers may impose size limits on individual fields, and the total profile must be under 64 KiB.

        **Note**: Setting a field to `null` keeps the key but with a `null` value, which some servers may reject.
        To remove a field completely, use the `DELETE` endpoint instead.
      operationId: setProfileField
      security:
        - accessTokenQuery: []
        - accessTokenBearer: []
      parameters:
        - in: path
          name: userId
          description: The user whose profile field to set.
          required: true
          example: "@alice:example.com"
          schema:
            type: string
        - in: path
          name: keyName
          description: The profile field key name to set.
            It must be either `avatar_url`, `displayname`, or a custom field following the
            [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
          required: true
          example: "displayname"
          schema:
            type: string
            pattern: '^(avatar_url|displayname|[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+)$'
      requestBody:
        description:
          A JSON object that must contain the `keyName` specified in the URL.
          For custom keys, the value may be any valid JSON type,
          but if the key is `avatar_url` or `displayname`, the value MUST be a string.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                "<keyName>":
                  description: The field value to set; may be any valid JSON type.
              example: { "displayname": "Alice Wonderland" }
      responses:
        "200":
          description: The profile field was set.
          content:
            application/json:
              schema:
                type: object # empty JSON object
              examples:
                response:
                  value: {}
        "400":
          description: The request is malformed, contains invalid JSON,
            missing a required parameter, specifies an invalid key, or exceeds allowed size limits.
          content:
            application/json:
              schema:
                $ref: definitions/errors/error.yaml
              examples:
                bad_json:
                  value:
                    {
                      "errcode": "M_BAD_JSON",
                      "error": "Malformed JSON payload.",
                    }
                invalid_key:
                  value:
                    {
                      "errcode": "M_INVALID_PARAM",
                      "error": "Invalid profile key.",
                    }
        "403":
          description: The server is unwilling to perform the operation,
            either due to insufficient permissions or because profile modifications are disabled.
          content:
            application/json:
              schema:
                $ref: definitions/errors/error.yaml
              examples:
                forbidden:
                  value:
                    {
                      "errcode": "M_FORBIDDEN",
                      "error": "Profile modification is not permitted.",
                    }
        "429":
          description: This request was rate-limited.
          content:
            application/json:
              schema:
                $ref: definitions/errors/rate_limited.yaml
      tags:
        - User data
    get:
      x-changedInMatrixVersion:
        "1.14": Endpoint now accepts variable `keyName` parameter.
      summary: Get a profile field for a user.
      description: |-
        Get the value of a profile field for a user. Any individual field must be within the total profile limit of 64 KiB.
      operationId: getProfileField
      parameters:
        - in: path
          name: userId
          description: The user whose profile field to get.
          required: true
          example: "@alice:example.com"
          schema:
            type: string
        - in: path
          name: keyName
          description: The profile field key name to retrieve.
            It must be either `avatar_url`, `displayname`, or a custom field following the
            [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
          required: true
          example: "displayname"
          schema:
            type: string
            pattern: '^(avatar_url|displayname|[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+)$'
      responses:
        "200":
          description: The profile field value was retrieved.
          content:
            application/json:
              schema:
                type: object
                properties:
                  "<keyName>":
                    description: The field value to set; may be any valid JSON type.
                additionalProperties: false
              examples:
                response:
                  value: { "displayname": "Alice" }
        "403":
          x-addedInMatrixVersion: "1.12"
          description: The server is unwilling to disclose whether the user exists and/or has the specified profile field.
          content:
            application/json:
              schema:
                $ref: definitions/errors/error.yaml
              examples:
                response:
                  value:
                    {
                      "errcode": "M_FORBIDDEN",
                      "error": "Profile lookup is disabled on this homeserver",
                    }
        "404":
          description: There is no profile field with this key for this user, or the user does not exist.
      tags:
        - User data
    delete:
      summary: Remove a profile field from a user.
      description: Remove a specific field from a user's profile.
      operationId: deleteProfileField
      security:
        - accessTokenQuery: []
        - accessTokenBearer: []
      parameters:
        - in: path
          name: userId
          description: The user whose profile field to delete.
          required: true
          example: "@alice:example.com"
          schema:
            type: string
        - in: path
          name: keyName
          description: The profile field key name to delete.
            It must be either `avatar_url`, `displayname`, or a custom field following the
            [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
          required: true
          example: "displayname"
          schema:
            type: string
            pattern: '^(avatar_url|displayname|[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+)$'
      responses:
        "200":
          description: The profile field was deleted.
          content:
            application/json:
              schema:
                type: object
              examples:
                response:
                  value: {}
        "400":
          description: The request is malformed, contains invalid JSON, or specifies an invalid key.
          content:
            application/json:
              schema:
                $ref: definitions/errors/error.yaml
              examples:
                bad_json:
                  value:
                    { "errcode": "M_BAD_JSON", "error": "Malformed request." }
                invalid_key:
                  value:
                    {
                      "errcode": "M_INVALID_PARAM",
                      "error": "Invalid profile key.",
                    }
        "403":
          description: The user is not authorised to delete this profile field.
          content:
            application/json:
              schema:
                $ref: definitions/errors/error.yaml
              examples:
                forbidden:
                  value:
                    {
                      "errcode": "M_FORBIDDEN",
                      "error": "Profile deletion is not permitted.",
                    }
        "429":
          description: This request was rate-limited.
          content:
            application/json:
              schema:
                $ref: definitions/errors/rate_limited.yaml
      tags:
        - User data
  "/profile/{userId}":
    get:
      summary: Get all profile information for a user.
      description: |-
        Get the complete profile for a user. The response includes `avatar_url` and `displayname`
        (unless set to `null`) plus any custom profile fields.

        **Note**: The complete profile must be under 64 KiB.
      operationId: getUserProfile
      parameters:
        - in: path
          name: userId
          description: The user whose profile information to get.
          required: true
          example: "@alice:example.com"
          schema:
            type: string
      responses:
        "200":
          description: The profile information for this user.
          content:
            application/json:
              schema:
                type: object
                properties:
                  avatar_url:
                    type: string
                    format: uri
                    description: "Avatar URL value (MXC URI format)."
                  displayname:
                    type: string
                additionalProperties:
                  description:
                    Any additional profile field value; may be any valid JSON type, with keys following the
                    [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
              examples:
                response:
                  value:
                    {
                      "avatar_url": "mxc://matrix.org/SDGdghriugerRg",
                      "displayname": "Alice Margatroid",
                      "m.example_field": "custom_value",
                    }
        "403":
          x-addedInMatrixVersion: "1.2"
          description: The server is unwilling to disclose whether the user exists and/or has profile information.
          content:
            application/json:
              schema:
                $ref: definitions/errors/error.yaml
              examples:
                response:
                  value:
                    {
                      "errcode": "M_FORBIDDEN",
                      "error": "Profile lookup is disabled on this homeserver",
                    }
        "404":
          description: There is no profile information for this user or this user does not exist.
          content:
            application/json:
              schema:
                $ref: definitions/errors/error.yaml
              examples:
                response:
                  value:
                    { "errcode": "M_NOT_FOUND", "error": "Profile not found" }
      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:
    accessTokenQuery:
      $ref: definitions/security.yaml#/accessTokenQuery
    accessTokenBearer:
      $ref: definitions/security.yaml#/accessTokenBearer