Vanilla Forums Users API

openapi: 3.0.3
info:
  description: API access to your community.
  title: Vanilla Addons Users API
  version: '2.0'
servers:
- url: https://open.vanillaforums.com/api/v2
tags:
- name: Users
paths:
  /users:
    get:
      parameters:
      - $ref: '#/components/parameters/DateInserted'
      - $ref: '#/components/parameters/DateUpdated'
      - name: dateLastActive
        description: When the user was last active on the community.
        in: query
        schema:
          type: string
          format: date-filter
      - name: roleID
        description: Filter by the role ID of a user.
        in: query
        schema:
          type: integer
      - name: roleIDs
        description: Filter by one of multiple role IDs.
        in: query
        schema:
          type: array
          items:
            type: integer
      - name: isBanned
        description: Filter by the banned status of a user. Pass true to filter only banned users, and false to exclude banned users.
        in: query
        schema:
          type: boolean
      - name: rankIDs
        description: Filter by one of multiple rank IDs.
        in: query
        schema:
          type: array
          items:
            type: integer
      - name: userID
        description: Filter by a range or CSV of user IDs.
        in: query
        schema:
          $ref: '#/components/schemas/RangeExpression'
      - name: name
        description: Filter by the user's username.
        in: query
        schema:
          type: string
      - name: email
        description: Filter by the user's email address.
        in: query
        schema:
          type: string
      - name: query
        description: Filter by the user's email address or username.
        in: query
        schema:
          type: string
      - name: ipAddresses
        description: Filter by the user's associated IP addresses
        in: query
        schema:
          items:
            type: string
          type: array
      - $ref: '#/components/parameters/Page'
      - description: 'Desired number of items per page.

          '
        in: query
        name: limit
        schema:
          type: integer
          default: 30
          maximum: 500
          minimum: 1
      - description: 'Token used to fetch next page of results. Cannot be combined with page.

          Warning: May lead to duplicate results if not sorted by primary key.

          '
        in: query
        name: cursor
        schema:
          type: string
      - name: sort
        in: query
        description: Sort the results.
        schema:
          type: string
          enum:
          - dateInserted
          - dateLastActive
          - name
          - userID
          - points
          - countPosts
          - dateFollowed
          - -dateInserted
          - -dateLastActive
          - -name
          - -userID
          - -points
          - -countPosts
          - -dateFollowed
          - groups.dateInserted
          - -groups.dateInserted
      - name: fields
        description: 'Fields that will be included in the response.

          '
        in: query
        schema:
          items:
            type: string
          type: array
        style: form
      - name: groupID
        description: Filter users by group association
        in: query
        schema:
          type: integer
      - name: membershipStatus
        description: Filter users by group membership status. Depends on groupID.
        in: query
        schema:
          type: string
          enum:
          - member
          - leader
          - pending
          - invited
          - banned
      - $ref: '#/components/parameters/UserExpand'
      - $ref: '#/components/parameters/ProfileFieldFilters'
      - name: followed
        description: Filter by users that the current user is following.
        in: query
        schema:
          type: boolean
      - name: fields
        in: query
        style: form
        description: Only return fields with these keys from the output. Use dot notation for nested fields.
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/User'
                type: array
          description: Success
      tags:
      - Users
      summary: List users.
      x-addon: dashboard
    post:
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
          description: Success
      tags:
      - Users
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserPost'
        required: true
      summary: Add a user.
      x-addon: dashboard
  /users/by-names:
    get:
      parameters:
      - description: 'Filter for username. Supports full or partial matching with appended wildcard (e.g. User*).

          '
        in: query
        name: name
        required: true
        schema:
          minLength: 1
          type: string
      - description: 'Sort method for results.

          Must be one of: "countComments", "dateLastActive", "name", "mention".

          '
        in: query
        name: order
        schema:
          type: string
          default: name
          enum:
          - countComments
          - dateLastActive
          - name
          - mention
      - description: 'Enforce setting to limit results, similar to default settings.

          '
        in: query
        name: mentionSettings
        schema:
          type: string
          default: name
          enum:
          - global
          - filter-loose
          - filter-strict
      - description: 'Specified what we are filtering by category/group/discussion/escalation

          '
        in: query
        name: recordType
        schema:
          type: string
          enum:
          - category
          - group
          - discussion
          - escalation
      - description: 'Specify value of the recordType

          '
        in: query
        name: recordID
        schema:
          type: integer
      - description: 'Page number. See [Pagination](https://docs.vanillaforums.com/apiv2/#pagination).

          '
        in: query
        name: page
        schema:
          type: integer
          default: 1
          minimum: 1
      - description: 'Desired number of items per page.

          '
        in: query
        name: limit
        schema:
          type: integer
          default: 30
          maximum: 100
          minimum: 1
      - name: fields
        in: query
        style: form
        description: Only return fields with these keys from the output. Use dot notation for nested fields.
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/UserFragment'
                type: array
          description: Success
      tags:
      - Users
      summary: Search for users by full or partial name matching.
      x-addon: dashboard
  /users/leaders:
    get:
      summary: Get user's leaderboard.
      tags:
      - Users
      parameters:
      - description: Leaderboard type ("reputation" => "Reputation points", "posts" => "Discussion/comment posts", "acceptedAnswers" => "Accepted Answers count").
        in: query
        name: leaderboardType
        required: true
        schema:
          type: string
          enum:
          - reputation
          - posts
          - acceptedAnswers
          default: reputation
      - description: Slot type ("d" = day, "w" = week, "m" = month, "y" = year, "a" = all).
        in: query
        name: slotType
        required: true
        schema:
          type: string
          enum:
          - d
          - w
          - m
          - y
          - a
          default: a
      - description: The numeric ID of a category to limit search results to.
        in: query
        name: categoryID
        required: false
        schema:
          type: integer
      - description: The maximum amount of records to be returned.
        in: query
        name: limit
        required: false
        schema:
          type: integer
      - description: Specify a range or CSV of included role IDs.
        in: query
        name: includedRoleIDs
        required: false
        schema:
          $ref: '#/components/schemas/RangeExpression'
      - description: Specify a range or CSV of excluded role IDs.
        in: query
        name: excludedRoleIDs
        required: false
        schema:
          $ref: '#/components/schemas/RangeExpression'
      - name: fields
        in: query
        style: form
        description: Only return fields with these keys from the output. Use dot notation for nested fields.
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    slotType:
                      description: Slot type ("d" = day, "w" = week, "m" = month, "y" = year, "a" = all).
                      type: string
                      enum:
                      - d
                      - w
                      - m
                      - y
                      - a
                    timeSlot:
                      description: The starting date/time for the requested Slot type.
                      type: string
                      format: date-time
                    source:
                      description: The score's source (Total, Badges, etc.) for the requested Slot type.
                      type: string
                    userID:
                      description: ID of the user.
                      type: integer
                    points:
                      description: The total number of points the user has accumulated.
                      type: integer
                    name:
                      description: Name of the user.
                      minLength: 1
                      type: string
                    photo:
                      description: URL to the user photo.
                      minLength: 0
                      nullable: true
                      type: string
                  required:
                  - categoryID
                  - userID
          description: Success
      x-addon: dashboard
  /users/me:
    get:
      responses:
        '200':
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/UserFragment'
                - type: object
                  properties:
                    email:
                      description: The current user's email address.
                      type: string
                      format: email
                    ssoID:
                      description: The unique ID of the default SSO connection. This will be YOUR user ID.
                      type: string
                    isSsoUser:
                      description: Whether the user has an active SSO connection.
                      type: boolean
                    isAdmin:
                      description: Whether or not the user is a global admin.
                      type: boolean
                    isSysAdmin:
                      description: Whether or not the user is a system admin.
                      type: boolean
                    permissions:
                      description: Global permissions available to the current user.
                      type: array
                      items:
                        type: string
                    countUnreadNotifications:
                      description: Total number of unread notifications for the current user.
                      type: integer
                    countUnreadConversations:
                      description: Total number of unread conversations for the current user.
                      type: integer
                  required:
                  - isAdmin
                  - isSysAdmin
                  - permissions
          description: Success
      tags:
      - Users
      summary: Get information about the current user.
      x-addon: dashboard
      parameters:
      - name: fields
        in: query
        style: form
        description: Only return fields with these keys from the output. Use dot notation for nested fields.
        schema:
          type: array
          items:
            type: string
  /users/me-counts:
    get:
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  counts:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          description: Menu counter name
                          type: string
                        count:
                          description: Counter value
                          type: integer
                    example:
                    - name: UnreadNotifications
                      count: 2
                    - name: Bookmarks
                      count: 3
                required:
                - counts
          description: Success
      tags:
      - Users
      summary: Get information about menu counts for current user.
      x-addon: dashboard
      parameters:
      - name: fields
        in: query
        style: form
        description: Only return fields with these keys from the output. Use dot notation for nested fields.
        schema:
          type: array
          items:
            type: string
  /users/register:
    post:
      responses:
        '201':
          content:
            application/json:
              schema:
                properties:
                  email:
                    description: Email address of the user.
                    minLength: 0
                    type: string
                  name:
                    description: Name of the user.
                    minLength: 1
                    type: string
                  userID:
                    description: ID of the user.
                    type: integer
                required:
                - userID
                - name
                - email
                type: object
          description: Success
      tags:
      - Users
      requestBody:
        content:
          application/json:
            schema:
              properties:
                discoveryText:
                  description: 'Why does the user wish to join? Only used when the registration is flagged as SPAM (response code: 202).'
                  type: string
                email:
                  description: An email address for this user.
                  minLength: 1
                  type: string
                name:
                  description: The username.
                  minLength: 1
                  type: string
                password:
                  description: A password for this user.
                  minLength: 1
                  type: string
              required:
              - email
              - name
              - password
              type: object
        required: true
      summary: Submit a new user registration.
      x-addon: dashboard
  /users/request-password:
    post:
      responses:
        '201':
          description: Success
      tags:
      - Users
      requestBody:
        content:
          application/json:
            schema:
              properties:
                email:
                  description: The email/username of the user.
                  minLength: 1
                  type: string
              required:
              - email
              type: object
        required: true
      x-addon: dashboard
  /users/{id}:
    delete:
      parameters:
      - description: The user ID.
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '204':
          description: Success
      tags:
      - Users
      requestBody:
        content:
          application/json:
            schema:
              properties:
                deleteMethod:
                  type: string
                  default: delete
                  description: The deletion method / strategy.
                  enum:
                  - keep
                  - wipe
                  - delete
              type: object
        required: true
      summary: Delete a user.
      x-addon: dashboard
    get:
      parameters:
      - description: 'The user ID.

          '
        in: path
        name: id
        required: true
        schema:
          type: integer
      - description: 'Expand associated records using one or more valid field names. A value of "all" will expand all expandable fields.

          '
        in: query
        name: expand
        schema:
          items:
            enum:
            - rank
            - discoveryText
            - profileFields
            - reactionsReceived
            - moderationCounts
            - followed
            - all
            type: string
          type: array
        style: form
      - description: 'Authenticate using a JWT, [role/token](https://success.vanillaforums.com/kb/articles/436-api-role-tokens).

          '
        in: query
        name: role-token
        schema:
          type: string
      - name: fields
        in: query
        style: form
        description: Only return fields with these keys from the output. Use dot notation for nested fields.
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
          description: Success
        '403':
          description: 'Forbidden, e.g. expired or invalid role token, role token used with another auth mechanism.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicError'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
      - Users
      summary: Get a user.
      x-addon: dashboard
    patch:
      parameters:
      - description: The user ID.
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
          description: Success
      tags:
      - Users
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserPatch'
        required: true
      summary: Update a user.
      x-addon: dashboard
  /users/{id}/ban:
    put:
      parameters:
      - description: The user ID.
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  banned:
                    description: The current banned value.
                    type: boolean
                required:
                - banned
                type: object
          description: Success
      tags:
      - Users
      requestBody:
        content:
          application/json:
            schema:
              properties:
                banned:
                  description: Pass true to ban or false to unban.
                  type: boolean
              required:
              - banned
              type: object
        required: true
      summary: Ban a user.
      x-addon: dashboard
  /users/{id}/confirm-email:
    post:
      parameters:
      - description: The user ID.
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  email:
                    minLength: 1
                    type: string
                  emailConfirmed:
                    type: boolean
                  userID:
                    type: integer
                required:
                - userID
                - email
                - emailConfirmed
                type: object
          description: Success
      tags:
      - Users
      requestBody:
        content:
          application/json:
            schema:
              properties:
                confirmationCode:
                  description: Email confirmation code
                  minLength: 1
                  type: string
              required:
              - confirmationCode
              type: object
        required: true
      summary: Confirm a users current email address by using a confirmation code
      x-addon: dashboard
  /users/{id}/edit:
    get:
      parameters:
      - description: 'The user ID.

          '
        in: path
        name: id
        required: true
        schema:
          type: integer
      - description: 'Expand associated records using one or more valid field names. A value of "all" will expand all expandable fields.

          '
        in: query
        name: expand
        schema:
          items:
            enum:
            - rank
            - all
            type: string
          type: array
        style: form
      - name: fields
        in: query
        style: form
        description: Only return fields with these keys from the output. Use dot notation for nested fields.
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  bypassSpam:
                    description: Should submissions from this user bypass SPAM checks?
                    type: boolean
                  email:
                    description: Email address of the user.
                    minLength: 0
                    type: string
                  emailConfirmed:
                    description: Has the email address for this user been confirmed?
                    type: boolean
                  name:
                    description: Name of the user.
                    minLength: 1
                    type: string
                  photo:
                    description: Raw photo field value from the user record.
                    minLength: 0
                    nullable: true
                    type: string
                  userID:
                    description: ID of the user.
                    type: integer
                required:
                - userID
                - name
                - email
                - photo
                - emailConfirmed
                - bypassSpam
                type: object
          description: Success
      tags:
      - Users
      summary: Get a user for editing.
      x-addon: dashboard
  /users/{id}/follow:
    patch:
      summary: Follow or unfollow a user.
      tags:
      - Users
      parameters:
      - description: The user ID to follow/unfollow.
        in: path
        name: id
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserFollow'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserFollowingPreferences'
          description: Success
      x-addon: dashboard
    get:
      summary: Get a user's following preferences.
      tags:
      - Users
      parameters:
      - description: The user ID to get following preferences for.
        in: path
        name: id
        required: true
        schema:
          type: integer
      - name: fields
        in: query
        style: form
        description: Only return fields with these keys from the output. Use dot notation for nested fields.
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserFollowingPreferences'
          description: Success
      x-addon: dashboard
  /users/{id}/hidden:
    put:
      parameters:
      - description: The user ID.
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  hidden:
                    description: Whether not the user is hidden from Online status.
                    type: boolean
                required:
                - hidden
                type: object
          description: Success
      tags:
      - Users
      requestBody:
        content:
          application/json:
            schema:
              properties:
                hidden:
                  description: Whether not the user should be hidden from Online status.
                  type: boolean
              required:
              - hidden
              type: object
        required: true
      summary: Adjust a user’s Online privacy.
      x-addon: dashboard
  /users/{id}/photo:
    delete:
      parameters:
      - description: 'The user ID.

          '
        in: path
        name: id
        required: true
        schema:
          type: integer
      - description: 'Expand associated records using one or more valid field names. A value of "all" will expand all expandable fields.

          '
        in: query
        name: expand
        schema:
          items:
            enum:
            - rank
            - all
            type: string
          type: array
        style: form
      responses:
        '204':
          description: Success
      tags:
      - Users
      summary: Delete a user photo.
      x-addon: dashboard
    post:
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  photoUrl:
                    description: URL to the user photo.
                    minLength: 0
                    nullable: true
                    type: string
                required:
                - photoUrl
                type: object
          description: Success
      tags:
      - Users
      requestBody:
        content:
          multipart/form-data:
            schema:
              properties:
                photo:
                  type: string
                  format: binary
              required:
              - photo
              type: object
        required: true
      x-addon: dashboard
  /users/{id}/rank:
    x-addon: ranks
    put:
      summary: Update the rank of a user.
      tags:
      - Users
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              properties:
                rankID:
                  description: ID of the user rank.
                  nullable: true
                  type: integer
              required:
              - rankID
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  rankID:
                    description: ID of the user rank.
                    nullable: true
                    type: integer
                required:
                - rankID
                type: object
          description: Success
      x-addon: dashboard
  /users/{id}/reacted:
    get:
      summary: Get a user's posts that have received a certain reaction.
      tags:
      - Users
      parameters:
      - description: The user ID.
        in: path
        name: id
        required: true
        schema:
          type: integer
      - description: The reaction to filter by.
        in: query
        name: reactionUrlcode
        required: true
        schema:
          type: string
      - description: expand parameters
        in: query
        name: expand
        schema:
          items:
            enum:
            - insertUser
            - updateUser
            - reactions
            - all
            - insertUser.ssoID
            - insertUser.roles
            - insertUser.profileFields
            - insertUser.extended
            - updateUser.ssoID
            - updateUser.roles
            - updateUser.profileFields
            - updateUser.extended
            type: string
          type: array
        style: form
      - name: fields
        in: query
        style: form
        description: Only return fields with these keys from the output. Use dot notation for nested fields.
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ReactedRecord'
          description: Success
      x-addon: dashboard
components:
  schemas:
    User:
      properties:
        userID:
          description: ID of the user.
          type: integer
        name:
          description: Name of the user.
          minLength: 1
          type: string
        photoUrl:
          description: URL to the user photo.
          minLength: 0
          nullable: true
          type: string
        email:
          description: Email address of the user.
          minLength: 0
          type: string
        hashMethod:
          type: string
          description: Hashing mechanism used for this user's password.
        roles:
          items:
            $ref: '#/components/schemas/RoleFragment'
          type: array
        dateInserted:
          description: When the user was created.
          format: date-time
          type: string
        dateLastActive:
          description: Time the user was last active.
          format: date-time
          nullable: true
          type: string
        dateUpdated:
          description: When the user was last updated.
          format: date-time
          nullable: true
          type: string
        points:
          description: The total number of points the user has accumulated.
          type: integer
          default: 0
        emailConfirmed:
          description: Has the email address for the user been confirmed?
          type: boolean
        hidden:
          description: Is this user hiding their online status?
          type: boolean
        bypassSpam:
          description: Should submissions from this user bypass SPAM checks?
          type: boolean
        banned:
          description: Is the user banned?
          type: integer
        rank:
          x-addon: ranks
          properties:
            name:
              description: Name of the rank.
              minLength: 1
              type: string
            rankID:
              description: Rank ID.
              type: integer
            userTitle:
              description: Label that will display beside the user.
              minLength: 1
              type: string
          required:
          - rankID
          - name
          - userTitle
          type: object
        rankID:
          x-addon: ranks
          description: ID of the user rank.
          nullable: true
          type: integer
        showEmail:
          description: Is the email address visible to other users?
          type: boolean
        suggestAnswers:
          description: Should we 

# --- truncated at 32 KB (57 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/vanilla-forums/refs/heads/main/openapi/vanilla-forums-users-api-openapi.yml