openapi: 3.0.0
info:
  description: 'Write API for NodeBB v2.0+'
  version: 31-03-2020
  title: Write API
  contact:
    email: support@nodebb.org
  license:
    name: GPL-3.0
servers:
  - url: /api/v1
tags:
  - name: users
    description: 'Account related calls (create, modify, delete, etc.)'
  - name: categories
    description: Administrative calls to manage categories
paths:
  /users/:
    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
  '/users/{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
  '/users/{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
  '/users/{uid}/follow':
    post:
      tags:
        - users
      summary: follows a user
      parameters:
        - in: path
          name: uid
          schema:
            type: integer
          required: true
          description: uid of the user to follow
      responses:
        '200':
          description: successfully followed user
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/components/schemas/Status'
                  response:
                    type: object
    delete:
      tags:
        - users
      summary: unfollows a user
      parameters:
        - in: path
          name: uid
          schema:
            type: integer
          required: true
          description: uid of the user to unfollow
      responses:
        '200':
          description: successfully unfollowed user
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/components/schemas/Status'
                  response:
                    type: object
  '/users/{uid}/ban':
    put:
      tags:
        - users
      summary: bans a user
      parameters:
        - in: path
          name: uid
          schema:
            type: integer
          required: true
          description: uid of the user to ban
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                until:
                  type: number
                  description: UNIX timestamp of the ban expiry
                  example: 1585775608076
                reason:
                  type: string
                  example: the reason for the ban
      responses:
        '200':
          description: successfully banned user
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/components/schemas/Status'
                  response:
                    type: object
    delete:
      tags:
        - users
      summary: unbans a user
      parameters:
        - in: path
          name: uid
          schema:
            type: integer
          required: true
          description: uid of the user to unban
      responses:
        '200':
          description: successfully unbanned user
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/components/schemas/Status'
                  response:
                    type: object
  /categories/:
    post:
      tags:
        - categories
      summary: creates a category
      description: This operation creates a new category
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                description:
                  type: string
                parentCid:
                  type: number
                cloneFromCid:
                  type: number
                icon:
                  type: string
                  description: A ForkAwesome icon without the `fa-` prefix
                bgColor:
                  type: string
                color:
                  type: string
                link:
                  type: string
                class:
                  type: string
                backgroundImage:
                  type: string
              required:
                - name
            example:
              name: My New Category
              description: Lorem ipsum, dolor sit amet
              parentCid: 0
              cloneFromCid: 0
              icon: bullhorn
              bgColor: '#ffffff'
              color: '#000000'
              link: 'https://example.org'
              class: 'col-md-3 col-xs-6'
              backgroundImage: '/assets/relative/path/to/image'
      responses:
        '200':
          description: category successfully created
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/components/schemas/Status'
                  response:
                    $ref: '#/components/schemas/CategoryObj'
  /groups/:
    post:
      tags:
        - groups
      summary: Create a new group
      description: This operation creates a new group
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                timestamp:
                  type: number
                disableJoinRequests:
                  type: number
                  enum: [0, 1]
                disableLeave:
                  type: number
                  enum: [0, 1]
                hidden:
                  type: number
                  enum: [0, 1]
                ownerUid:
                  type: number
                private:
                  type: number
                  enum: [0, 1]
                description:
                  type: string
                userTitleEnabled:
                  type: number
                  enum: [0, 1]
                createtime:
                  type: number
              required:
                - name
            example:
              name: 'My Test Group'
              hidden: 1
      responses:
        '200':
          description: group successfully created
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/components/schemas/Status'
                  response:
                    $ref: components/schemas/GroupObject.yaml#/GroupDataObject
    delete:
      tags:
        - groups
      summary: Delete an existing group
      description: This operation deletes an existing group, all members within this group will cease to be members after the group is deleted.
      responses:
        '200':
          description: group successfully deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/components/schemas/Status'
                  response:
                    type: object
                    properties: {}
  /groups/{slug}/membership/{uid}:
    put:
      tags:
        - groups
      summary: Join a group
      description: This operation joins an existing group, or causes another user to join a group. If the group is private and you are not an administrator, this method will cause that user to request membership, instead. For user _invitations_, you'll want to call `PUT /groups/{slug}/invites/{uid}`.
      responses:
        '200':
          description: group successfully joined, or membership requested
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/components/schemas/Status'
                  response:
                    type: object
                    properties: {}
  /topics:
    post:
      tags:
        - topics
      summary: Create a new topic
      description: This operation creates a new topic with a post. Topic creation without a post is not allowed via the Write API as it is an internal-only method.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                cid:
                  type: number
                title:
                  type: string
                content:
                  type: string
                tags:
                  type: array
                  items:
                    type: string
              required:
                - cid
                - title
                - content
            example:
              cid: 1
              title: Test topic
              content: This is the test topic's content
      responses:
        '200':
          description: topic successfully created
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/components/schemas/Status'
                  response:
                    $ref: components/schemas/TopicObject.yaml#/TopicObject
  /topics/{tid}:
    post:
      tags:
        - topics
      summary: Reply to a topic
      description: This operation creates a new reply to an existing topic.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                content:
                  type: string
                timestamp:
                  type: number
                toPid:
                  type: number
              required:
                - content
            example:
              content: This is a test reply
      responses:
        '200':
          description: post successfully created
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/components/schemas/Status'
                  response:
                    $ref: components/schemas/PostsObject.yaml#/PostsObject
    delete:
      tags:
        - topics
      summary: Delete a topic
      description: This operation purges a topic and all of its posts (careful, there is no confirmation!)
      responses:
        '200':
          description: Topic successfully purged
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/components/schemas/Status'
                  response:
                    type: object
                    properties: {}
  /topics/{tid}/state:
    delete:
      tags:
        - topics
      summary: Delete a topic
      description: This operation deletes an existing topic.
      responses:
        '200':
          description: Topic successfully deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/components/schemas/Status'
                  response:
                    type: object
                    properties: {}
    put:
      tags:
        - topics
      summary: Restore a topic
      description: This operation restores a topic.
      responses:
        '200':
          description: Topic successfully restored
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/components/schemas/Status'
                  response:
                    type: object
                    properties: {}
  /topics/{tid}/lock:
    delete:
      tags:
        - topics
      summary: Lock a topic
      description: This operation locks an existing topic.
      responses:
        '200':
          description: Topic successfully locked
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/components/schemas/Status'
                  response:
                    type: object
                    properties: {}
    put:
      tags:
        - topics
      summary: Unlock a topic
      description: This operation unlocks a topic.
      responses:
        '200':
          description: Topic successfully unlocked
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/components/schemas/Status'
                  response:
                    type: object
                    properties: {}
  /topics/{tid}/state:
    delete:
      tags:
        - topics
      summary: Pin a topic
      description: This operation pins an existing topic.
      responses:
        '200':
          description: Topic successfully pinned
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/components/schemas/Status'
                  response:
                    type: object
                    properties: {}
    put:
      tags:
        - topics
      summary: Unpin a topic
      description: This operation unpins a topic.
      responses:
        '200':
          description: Topic successfully unpinned
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/components/schemas/Status'
                  response:
                    type: object
                    properties: {}
components:
  schemas:
    Status:
      type: object
      properties:
        code:
          type: string
          example: ok
        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
    CategoryObj:
      properties:
        cid:
          type: number
          example: 1
        name:
          type: string
          example: My New Category
        description:
          type: string
          example: Lorem ipsum, dolor sit amet
        descriptionParsed:
          type: string
          example: Lorem ipsum, dolor sit amet
        icon:
          type: string
          example: bullhorn
        bgColor:
          type: string
          example: '#ffffff'
        color:
          type: string
          example: '#000000'
        slug:
          type: string
          example: 1/my-new-category
        parentCid:
          type: number
          example: 0
        topic_count:
          type: number
          example: 0
        post_count:
          type: number
          example: 0
        disabled:
          type: number
          example: 0
        order:
          type: number
          example: 5
        link:
          type: number
          example: 'https://example.org'
        numRecentReplies:
          type: number
          example: 1
        class:
          type: string
          example: col-md-3 col-xs-6
        imageClass:
          type: string
          example: cover
        isSection:
          type: number
          example: 0
        totalPostCount:
          type: number
          example: 0
        totalTopicCount:
          type: number
          example: 0
        tagWhitelist:
          type: array
          example:
            - some-tag
            - another-tag
        unread-class:
          type: string
        backgroundImage:
          type: string
          example: '/assets/images/covers/Circuit1.png'
  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'