snapshot of https://github.com/mattermost/mattermost.git (master, 2026-09-16; blobs > 131072B omitted)

api/v4/source/custom_profile_attributes.yaml

@@ -0,0 +1,471 @@
+  "/api/v4/custom_profile_attributes/fields":
+    get:
+      tags:
+        - custom profile attributes
+      summary: List all the Custom Profile Attributes fields
+      description: |
+        List all the Custom Profile Attributes fields.
+
+        __Minimum server version__: 10.5
+
+        ##### Permissions
+        Must be authenticated.
+      operationId: ListAllCPAFields
+      responses:
+        "200":
+          description: Custom Profile Attributes fetch successful. Result may be empty.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/PropertyField"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+
+    post:
+      tags:
+        - custom profile attributes
+      summary: Create a Custom Profile Attribute field
+      description: |
+        Create a new Custom Profile Attribute field on the system.
+
+        __Minimum server version__: 10.5
+
+        ##### Permissions
+        Must have `manage_system` permission.
+      operationId: CreateCPAField
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - name
+                - type
+              properties:
+                name:
+                  type: string
+                  description: >
+                    The internal identifier for this attribute. Must match
+                    `^[A-Za-z_][A-Za-z0-9_]*$` and must not be a CEL reserved
+                    word (true, false, null, in, as, break, const, continue, else,
+                    for, function, if, import, let, loop, package, namespace,
+                    return, var, void, while). This name is used in ABAC policy
+                    expressions as `user.attributes.<name>`.
+                type:
+                  type: string
+                attrs:
+                  type: object
+                  properties:
+                    visibility:
+                      type: string
+                      description: "Visibility of the attribute"
+                      enum: ["hidden", "when_set", "always"]
+                      default: "when_set"
+                    sort_order:
+                      type: number
+                      description: "Sort order for displaying this attribute"
+                    options:
+                      type: array
+                      description: "Options for select/multiselect fields"
+                      items:
+                        type: object
+                        properties:
+                          name:
+                            type: string
+                          color:
+                            type: string
+                    value_type:
+                      type: string
+                      description: "Type of text value"
+                      enum: ["email", "url", "phone"]
+                    ldap:
+                      type: string
+                      description: "LDAP attribute for syncing"
+                    saml:
+                      type: string
+                      description: "SAML attribute for syncing"
+                    protected:
+                      type: boolean
+                      description: "If true, the field is read-only and cannot be modified."
+                    source_plugin_id:
+                      type: string
+                      description: "The ID of the plugin that created this field. This attribute cannot be changed."
+                    access_mode:
+                      type: string
+                      description: "Access mode of the field"
+                      enum: ["", "source_only", "shared_only"]
+                      default: ""
+                    display_name:
+                      type: string
+                      description: >
+                        Human-readable label shown in the UI. Defaults to the field
+                        `name` when omitted or empty. Maximum 255 characters.
+      responses:
+        "201":
+          description: Custom Profile Attribute field creation successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PropertyField"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "422":
+          description: >
+            Validation error. Returned when `name` does not match the
+            required identifier pattern, is a CEL reserved word, or when
+            `attrs.display_name` exceeds 255 characters.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AppError"
+
+  "/api/v4/custom_profile_attributes/fields/{field_id}":
+    patch:
+      tags:
+        - custom profile attributes
+      summary: Patch a Custom Profile Attribute field
+      description: |
+        Partially update a Custom Profile Attribute field by providing
+        only the fields you want to update. Omitted fields will not be
+        updated. The fields that can be updated are defined in the
+        request body, all other provided fields will be ignored.
+
+        **Note:** Fields with `attrs.protected = true` cannot be
+        modified and will return an error.
+
+        __Minimum server version__: 10.5
+
+        ##### Permissions
+        Must have `manage_system` permission.
+      operationId: PatchCPAField
+      parameters:
+        - name: field_id
+          in: path
+          description: Custom Profile Attribute field GUID
+          required: true
+          schema:
+            type: string
+      requestBody:
+        description: Custom Profile Attribute field that is to be updated
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                name:
+                  type: string
+                  description: >
+                    New name for the attribute. When changed, must match
+                    `^[A-Za-z_][A-Za-z0-9_]*$` and must not be a CEL reserved
+                    word. Pre-existing fields with non-conforming names remain
+                    patchable on all other attributes; the validation only fires
+                    when `name` actually changes.
+                type:
+                  type: string
+                attrs:
+                  type: object
+                  properties:
+                    visibility:
+                      type: string
+                      description: "Visibility of the attribute"
+                      enum: ["hidden", "when_set", "always"]
+                      default: "when_set"
+                    sort_order:
+                      type: number
+                      description: "Sort order for displaying this attribute"
+                    options:
+                      type: array
+                      description: "Options for select/multiselect fields"
+                      items:
+                        type: object
+                        properties:
+                          id:
+                            type: string
+                          name:
+                            type: string
+                          color:
+                            type: string
+                    value_type:
+                      type: string
+                      description: "Type of text value"
+                      enum: ["email", "url", "phone"]
+                    ldap:
+                      type: string
+                      description: "LDAP attribute for syncing"
+                    saml:
+                      type: string
+                      description: "SAML attribute for syncing"
+                    protected:
+                      type: boolean
+                      description: "If true, the field is read-only and cannot be modified."
+                    source_plugin_id:
+                      type: string
+                      description: "The ID of the plugin that created this field. This attribute cannot be changed."
+                    access_mode:
+                      type: string
+                      description: "Access mode of the field"
+                      enum: ["", "source_only", "shared_only"]
+                      default: ""
+                    display_name:
+                      type: string
+                      description: >
+                        Human-readable label shown in the UI. Maximum 255 characters.
+      responses:
+        "200":
+          description: Custom Profile Attribute field patch successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PropertyField"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "422":
+          description: >
+            Validation error. Returned when a `name` change does not match
+            the required identifier pattern, is a CEL reserved word, or
+            when `attrs.display_name` exceeds 255 characters.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AppError"
+
+    delete:
+      tags:
+        - custom profile attributes
+      summary: Delete a Custom Profile Attribute field
+      description: |
+        Marks a Custom Profile Attribute field and all its values as
+        deleted.
+
+        __Minimum server version__: 10.5
+
+        ##### Permissions
+        Must have `manage_system` permission.
+      operationId: DeleteCPAField
+      parameters:
+        - name: field_id
+          in: path
+          description: Custom Profile Attribute field GUID
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Custom Profile Attribute field deletion successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/StatusOK"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+
+  "/api/v4/custom_profile_attributes/values":
+    patch:
+      tags:
+        - custom profile attributes
+      summary: Patch Custom Profile Attribute values
+      description: |
+        Partially update a set of values on the requester's Custom
+        Profile Attribute fields by providing only the information you
+        want to update. Omitted fields will not be updated. The fields
+        that can be updated are defined in the request body, all other
+        provided fields will be ignored.
+
+        **Note:** Values for fields with `attrs.protected = true` cannot be
+        updated and will return an error.
+
+        __Minimum server version__: 10.5
+
+        ##### Permissions
+        Must be authenticated.
+      operationId: PatchCPAValues
+      requestBody:
+        description: Custom Profile Attribute values that are to be updated
+        required: true
+        content:
+          application/json:
+            schema:
+              type: array
+              items:
+                type: object
+                properties:
+                  id:
+                    type: string
+                  value:
+                    oneOf:
+                      - type: string
+                      - type: array
+                        items:
+                          type: string
+      responses:
+        "200":
+          description: Custom Profile Attribute values patch successful
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    id:
+                      type: string
+                    value:
+                      oneOf:
+                        - type: string
+                        - type: array
+                          items:
+                            type: string
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+  "/api/v4/custom_profile_attributes/group":
+    get:
+      tags:
+        - custom profile attributes
+      summary: Get Custom Profile Attribute property group data
+      description: |
+        Get the property group used for Custom Profile Attributes.
+
+        __Minimum server version__: 10.8
+
+        ##### Permissions
+        Must be authenticated.
+      operationId: GetCPAGroup
+      responses:
+        "200":
+          description: Group fetch successful
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  id:
+                    type: string
+                    description: The ID of the custom profile attributes group
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+
+  "/api/v4/users/{user_id}/custom_profile_attributes":
+    get:
+      tags:
+        - custom profile attributes
+      summary: List Custom Profile Attribute values
+      description: |
+        List all the Custom Profile Attributes values for specified user.
+
+        __Minimum server version__: 10.5
+
+        ##### Permissions
+        Must have `view members` permission.
+      operationId: ListCPAValues
+      parameters:
+        - name: user_id
+          in: path
+          description: User GUID
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Custom Profile Attribute values fetch successful. Result may be empty.
+          content:
+            application/json:
+            schema:
+              type: array
+              items:
+                type: object
+                properties:
+                  field_id:
+                    type: string
+                  value:
+                    type: string
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+    patch:
+      tags:
+        - custom profile attributes
+      summary: Update custom profile attribute values for a user
+      description: |
+        Update Custom Profile Attribute field values for a specific user.
+
+        **Note:** Values for fields with `attrs.protected = true` cannot be
+        updated and will return an error.
+
+        __Minimum server version__: 11
+
+        ##### Permissions
+        Must have permission to edit the user. Users can only edit their own CPA values unless they are system administrators.
+      parameters:
+        - name: user_id
+          in: path
+          description: User GUID
+          required: true
+          schema:
+            type: string
+      operationId: PatchCPAValuesForUser
+      requestBody:
+        description: Custom Profile Attribute values that are to be updated
+        required: true
+        content:
+          application/json:
+            schema:
+              type: array
+              items:
+                type: object
+                properties:
+                  id:
+                    type: string
+                  value:
+                    oneOf:
+                      - type: string
+                      - type: array
+                        items:
+                          type: string
+      responses:
+        '200':
+          description: Custom profile attribute values updated successfully
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    id:
+                      type: string
+                    value:
+                      oneOf:
+                        - type: string
+                        - type: array
+                          items:
+                            type: string
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'