# 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}/{key_name}":
    put:
      summary: Set the user's profile field.
      description: |-
        This API sets or updates a specified profile field in a user's profile. You must have the
        appropriate permissions (i.e. an access token) to modify the profile field.

        **Note:** Setting a `null` value SHOULD NOT delete the field. However, servers MAY reject
        requests to store `null` values if they do not allow keys to exist with a `null` value.
        For more details, see [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133).
      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: key_name
          description: The profile field key name to set.
          required: true
          example: "displayname"
          schema:
            oneOf:
              - type: string
                enum: ["displayname", "avatar_url"]
              - type: string
                description: Must follow the [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
      requestBody:
        description: >
          The new profile field value. The JSON object must contain the "key_name" specified in the URL.
          For custom keys, the value may be any valid JSON type. However, if the key is "displayname"
          or "avatar_url", the value MUST be a string as per the stabilised spec requirements.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                displayname:
                  type: string
                  description: "Spec-conformant displayname value; must be a string."
                avatar_url:
                  type: string
                  description: "Spec-conformant avatar URL value (MXC URI format); must be a string."
              additionalProperties:
                description: "Any additional profile field value; 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, missing a required parameter, contains invalid JSON (for the value),
            or specifies an invalid key, or the profile data exceeds allowed 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:
      summary: Get the user's profile field.
      description: |-
        Get the value of a user's profile field. This API can retrieve the profile fields of the user
        or other users, either locally or on remote homeservers. For more details, see
        [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133).
      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: key_name
          description: The profile field key name to retrieve.
          required: true
          example: "displayname"
          schema:
            oneOf:
              - type: string
                enum: ["displayname", "avatar_url"]
              - type: string
                description: Must follow the
                  [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
      responses:
        "200":
          description: The profile field value was retrieved.
          content:
            application/json:
              schema:
                type: object
                properties:
                  displayname:
                    type: string
                    description: "Spec-conformant displayname value; must be a string."
                  avatar_url:
                    type: string
                    description: "Spec-conformant avatar URL value (MXC URI format); must be a string."
                additionalProperties:
                  description: "Any additional profile field value; may be any valid JSON type."
              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: Delete a profile field.
      description: |-
        Delete the specified profile field from a user's profile.

        **Note:** Setting a null value using the `PUT` endpoint retains the key with a null value.
        Use this `DELETE` endpoint to fully remove the key if required. For more details, see
        [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133).
      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: key_name
          description: The profile field key name to delete.
          required: true
          example: "displayname"
          schema:
            oneOf:
              - type: string
                enum: ["displayname", "avatar_url"]
              - type: string
                description: Must follow the
                  [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
      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 this user's profile information.
      description: |-
        Retrieve the combined profile information for a user. In addition to the
        stabilised fields, this API may include custom profile fields as defined in
        [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133).
      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: "Spec-conformant avatar URL value (MXC URI format); must be a string."
                  displayname:
                    type: string
                    description: "Spec-conformant displayname value; must be a string."
                additionalProperties:
                  description: "Any additional profile field value; may be any valid JSON type."
              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