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

# 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.16": This endpoint now accepts a variable `keyName` parameter and `m.tz` was added as a defined key. Previously only `displayname` and `avatar_url` were accepted.
      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.

        Servers MAY reject `null` values. Servers that accept `null` values SHOULD store
        them rather than treating `null` as a deletion request. Clients that want to delete a
        field, including its key and value, SHOULD use the `DELETE` endpoint instead.
      operationId: setProfileField
      security:
        - accessTokenQuery: []
        - accessTokenBearer: []
      parameters:
        - in: path
          name: userId
          description: The user whose profile field should be set.
          required: true
          example: "@alice:example.com"
          schema:
            type: string
        - in: path
          name: keyName
          description: The name of the profile field to set. This MUST be either
            `avatar_url`, `displayname`, `m.tz`, 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|m\.tz|[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+)$'
      requestBody:
        description: A JSON object containing the property whose name matches
          the `keyName` specified in the URL. See `additionalProperties` for
          further details.
        required: true
        content:
          application/json:
            schema:
              type: object
              minProperties: 1
              description: |
                An object which contains exactly one property. The key
                of that property MUST match the `keyName` specified in the URL.
                
                For `avatar_url`, the value MUST be an MXC URI string. 
                
                For `displayname`, the value MUST be a string.
                
                For `m.tz`, the value MUST be a valid identifier from the  [IANA Time Zone Database](https://www.iana.org/time-zones).
                Servers MAY choose to validate the value. Clients MUST expect unknown or invalid
                values.

                For custom keys, any JSON type is allowed. Servers MAY not validate
                these values, but clients SHOULD follow the format defined for that key.
              additionalProperties: true
              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 input was invalid in some way. This can include one
            of the following error codes:
            
            - `M_BAD_JSON`: The provided value is not valid JSON.
            - `M_MISSING_PARAM`: The required `keyName` property is
              missing from the request body.
            - `M_PROFILE_TOO_LARGE`: Storing the supplied value would
              make the profile exceed its maximum allowed size of 64 KiB.
            - `M_KEY_TOO_LARGE`: The supplied profile key exceeds the
              maximum allowed key length of 255 bytes.
          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.16": This endpoint now accepts a variable `keyName` parameter and `m.tz` was added as a defined key. Previously only `displayname` and `avatar_url` were accepted.
      summary: Get a profile field for a user.
      description: Get the value of a profile field for a user.
      operationId: getProfileField
      parameters:
        - in: path
          name: userId
          description: The user whose profile field should be returned.
          required: true
          example: "@alice:example.com"
          schema:
            type: string
        - in: path
          name: keyName
          description: The name of the profile field to retrieve.
          required: true
          example: "displayname"
          schema:
            type: string
            pattern: '^(avatar_url|displayname|m\.tz|[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
                description: |
                  An object with one property, whose key matches the `keyName` specified
                  in the URL, and whose value is the current setting of that profile field.
                additionalProperties: true
              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:
      x-addedInMatrixVersion: "1.16"
      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 should be deleted.
          required: true
          example: "@alice:example.com"
          schema:
            type: string
        - in: path
          name: keyName
          description: The name of the profile field to delete.
          required: true
          example: "displayname"
          schema:
            type: string
            pattern: '^(avatar_url|displayname|m\.tz|[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+)$'
      responses:
        "200":
          description: The profile field was deleted or it doesn't exist.
          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.
      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: mx-mxc-uri
                    description: The user's avatar URL if they have set one, otherwise not present.
                  displayname:
                    type: string
                    description: The user's display name if they have set one, otherwise not
                      present.
                  m.tz:
                    x-addedInMatrixVersion: "1.16"
                    type: string
                    description: The user's time zone.
                additionalProperties:
                  x-addedInMatrixVersion: "1.16"
                  description: Additional profile fields.
              examples:
                response:
                  value:
                    {
                      "avatar_url": "mxc://matrix.org/SDGdghriugerRg",
                      "displayname": "Alice Margatroid",
                      "m.tz": "Europe/London",
                      "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