openapi: 3.0.0
info:
  description: Standard, out-of-the-box read & write API for NodeBB v2.0+
  version: "1.0.0"
  title: Read/Write API
  contact:
    email: support@nodebb.org
  license:
    name: MIT
    url: 'https://opensource.org/licenses/MIT'
tags:
  # - name: admins
  #   description: Secured Admin-only calls
  # - name: developers
  #   description: Operations available to regular developers
  - name: users
    description: Account related calls (create, modify, delete, etc.)
paths:
  # /inventory:
  #   get:
  #     tags:
  #       - developers
  #     summary: searches inventory
  #     operationId: searchInventory
  #     description: |
  #       By passing in the appropriate options, you can search for
  #       available inventory in the system
  #     parameters:
  #       - in: query
  #         name: searchString
  #         description: pass an optional search string for looking up inventory
  #         required: false
  #         schema:
  #           type: string
  #       - in: query
  #         name: skip
  #         description: number of records to skip for pagination
  #         schema:
  #           type: integer
  #           format: int32
  #           minimum: 0
  #       - in: query
  #         name: limit
  #         description: maximum number of records to return
  #         schema:
  #           type: integer
  #           format: int32
  #           minimum: 0
  #           maximum: 50
  #     responses:
  #       '200':
  #         description: search results matching criteria
  #         content:
  #           application/json:
  #             schema:
  #               type: array
  #               items:
  #                 $ref: '#/components/schemas/InventoryItem'
  #       '400':
  #         description: bad input parameter
  #   post:
  #     tags:
  #       - admins
  #     summary: adds an inventory item
  #     operationId: addInventory
  #     description: Adds an item to the system
  #     responses:
  #       '201':
  #         description: item created
  #       '400':
  #         description: 'invalid input, object invalid'
  #       '409':
  #         description: an existing item already exists
  #     requestBody:
  #       content:
  #         application/json:
  #           schema:
  #             $ref: '#/components/schemas/InventoryItem'
  #       description: Inventory item to add
  /:
    post:
      tags:
        - users
      summary: creates a user account
      operationId: createUser
      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:
                $ref: '#/components/schemas/User'
components:
  schemas:
    # InventoryItem:
    #   type: object
    #   required:
    #     - id
    #     - name
    #     - manufacturer
    #     - releaseDate
    #   properties:
    #     id:
    #       type: string
    #       format: uuid
    #       example: d290f1ee-6c54-4b01-90e6-d701748f0851
    #     name:
    #       type: string
    #       example: Widget Adapter
    #     releaseDate:
    #       type: string
    #       format: date-time
    #       example: '2016-08-29T09:12:33.001Z'
    #     manufacturer:
    #       $ref: '#/components/schemas/Manufacturer'
    # Manufacturer:
    #   required:
    #     - name
    #   properties:
    #     name:
    #       type: string
    #       example: ACME Corporation
    #     homePage:
    #       type: string
    #       format: url
    #       example: 'https://www.acme-corp.com'
    #     phone:
    #       type: string
    #       example: 408-867-5309
    #   type: object
    User:
      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