# 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 that setting
        a `null` value SHOULD NOT delete the field.
      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.
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties:
                type: string
              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, or the profile data exceeds allowed limits.
          content:
            application/json:
              schema:
                $ref: definitions/errors/error.yaml
              examples:
                bad_request:
                  value:
                    {
                      "errcode": "M_BAD_JSON",
                      "error": "Malformed JSON payload.",
                    }
        "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. It supports both standard fields
        (e.g. "displayname" and "avatar_url") and custom keys.
      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 (e.g. "displayname", "avatar_url", or custom).
          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
                additionalProperties:
                  type: string
              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.
      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 or specifies an invalid key.
          content:
            application/json:
              schema:
                $ref: definitions/errors/error.yaml
              examples:
                bad_request:
                  value:
                    { "errcode": "M_BAD_JSON", "error": "Malformed request." }
        "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 standard fields,
        this API may include extended custom profile fields as defined in MSC4133.
      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: The user's avatar URL if set.
                  "displayname":
                    type: string
                    description: The user's display name if set.
                additionalProperties:
                  type: string
                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