openapi: 3.0.0
info:
  description: 'Standard, out-of-the-box read & write API for NodeBB v2.0+'
  version: 31-03-2020
  title: Read/Write API
  contact:
    email: support@nodebb.org
  license:
    name: MIT
    url: 'https://opensource.org/licenses/MIT'
tags:
  - name: users
    description: 'Account related calls (create, modify, delete, etc.)'
paths:
  /:
    post:
      tags:
        - users
      summary: creates a user account
      description: This operation creates a new user account
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
                  description: 'If the username is taken, a number will be appended'
                password:
                  type: string
                email:
                  type: string
              required:
                - username
            example:
              username: Dragon Fruit
              password: s3cre7password
              email: dragonfruit@example.org
      responses:
        '200':
          description: user successfully created
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/components/schemas/Status'
                  response:
                    $ref: '#/components/schemas/UserObj'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '426':
          $ref: '#/components/responses/426'
        '500':
          $ref: '#/components/responses/500'
    delete:
      tags:
        - users
      summary: deletes one or more users
      description: This operation deletes one or many user accounts, including their contributions (posts, topics, etc.)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                uids:
                  type: array
                  description: A collection of uids
                  items:
                    type: number
            example:
              uids:
                - 1
                - 2
                - 3
      responses:
        '200':
          description: user account(s) deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/components/schemas/Status'
                  response:
                    type: object
  '/{uid}':
    put:
      tags:
        - users
      summary: updates a user account
      parameters:
        - in: path
          name: uid
          schema:
            type: integer
          required: true
          description: uid of the user to update
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserRequest'
      responses:
        '200':
          description: user profile updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/components/schemas/Status'
                  response:
                    $ref: '#/components/schemas/UserObj'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '426':
          $ref: '#/components/responses/426'
        '500':
          $ref: '#/components/responses/500'
    delete:
      tags:
        - users
      summary: delete a single user account
      parameters:
        - in: path
          name: uid
          schema:
            type: integer
          required: true
          description: uid of the user to delete
      responses:
        '200':
          description: user account deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/components/schemas/Status'
                  response:
                    type: object
  '/{uid}/password':
    put:
      tags:
        - users
      summary: changes a user's password
      parameters:
        - in: path
          name: uid
          schema:
            type: integer
          required: true
          description: uid of the user to update
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                currentPassword:
                  type: string
                  description: test
                  example: oldp455word
                newPassword:
                  type: string
                  example: s3cre7password
              required:
                - newPassword
      responses:
        '200':
          description: user profile updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/components/schemas/Status'
                  response:
                    type: object
components:
  schemas:
    Status:
      type: object
      properties:
        code:
          allOf:
            - title: Success
              type: string
              example: ok
            - title: Error
              type: string
              example: error
        message:
          type: string
          example: OK
    Error:
      type: object
      properties:
        status:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
        response:
          type: object
    UserObj:
      properties:
        uid:
          type: number
          example: 1
        username:
          type: string
          example: Dragon Fruit
        userslug:
          type: string
          example: dragon-fruit
        email:
          type: string
          example: dragonfruit@example.org
        'email:confirmed':
          type: number
          example: 1
        joindate:
          type: number
          example: 1585337827953
        lastonline:
          type: number
          example: 1585337827953
        picture:
          type: string
          example: 'https://images.unsplash.com/photo-1560070094-e1f2ddec4337?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=256&h=256&q=80'
        fullname:
          type: string
          example: Mr. Dragon Fruit Jr.
        location:
          type: string
          example: 'Toronto, Canada'
        birthday:
          type: string
          description: A birthdate given in an ISO format parseable by the Date object
          example: 03/27/2020
        website:
          type: string
          example: 'https://example.org'
        aboutme:
          type: string
          example: |
            This is a paragraph all about how my life got twist-turned upside-down
            and I'd like to take a minute and sit right here,
            to tell you all about how I because the administrator of NodeBB
        signature:
          type: string
          example: |
            This is an example signature
            It can span multiple lines.
        uploadedpicture:
          type: string
          example: /assets/profile/1-profileimg.png
          description: 'In almost all cases, defer to "picture" instead. Use this if you need to specifically reference the picture uploaded to the forum.'
        profileviews:
          type: number
          example: 1000
        reputation:
          type: number
          example: 100
        postcount:
          type: number
          example: 1000
        topiccount:
          type: number
          example: 50
        lastposttime:
          type: number
          example: 1585337827953
        banned:
          type: number
          example: 0
        'banned:expire':
          type: number
          example: 1585337827953
        status:
          type: string
          example: online
        flags:
          type: number
          example: 0
        followercount:
          type: number
          example: 2
        followingcount:
          type: number
          example: 5
        'cover:url':
          type: string
          example: /assets/profile/1-cover.png
        'cover:position':
          type: string
          example: 50.0301% 19.2464%
        groupTitle:
          type: string
          example: '["administrators","Staff"]'
        groupTitleArray:
          type: array
          example:
            - administrators
            - Staff
        'icon:text':
          type: string
          example: D
        'icon:bgColor':
          type: string
          example: '#9c27b0'
        joindateISO:
          type: string
          example: '2020-03-27T20:30:36.590Z'
        lastonlineISO:
          type: string
          example: '2020-03-27T20:30:36.590Z'
        banned_until:
          type: number
          example: 0
        banned_until_readable:
          type: string
          example: Not Banned
    UserRequest:
      properties:
        username:
          type: string
          example: Dragon Fruit
        email:
          type: string
          example: dragonfruit@example.org
        fullname:
          type: string
          example: Mr. Dragon Fruit Jr.
        website:
          type: string
          example: 'https://example.org'
        location:
          type: string
          example: 'Toronto, Canada'
        groupTitle:
          type: string
          example: '["administrators","Staff"]'
        birthday:
          type: string
          description: A birthdate given in an ISO format parseable by the Date object
          example: 03/27/2020
        signature:
          type: string
          example: |
            This is an example signature
            It can span multiple lines.
        aboutme:
          type: string
          example: |
            This is a paragraph all about how my life got twist-turned upside-down
            and I'd like to take a minute and sit right here,
            to tell you all about how I because the administrator of NodeBB
  responses:
    '400':
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '401':
      description: Not Authorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '403':
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '404':
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '426':
      description: Upgrade Required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '500':
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'