nodebb/public/openapi/write.yaml

openapi: 3.0.0
info:
  title: NodeBB Write API
  description: >-
    # Overview

    The following document outlines every route exposed by the NodeBB Write API. As of NodeBB v1.15.0, NodeBB will use these routes to make changes to the database (e.g. creating new posts, editing user profiles, etc.)

    We invite you to build external integrations with NodeBB using this document as a guide.

    # History

    Up until v1.15.0, NodeBB utilised the [WebSocket](https://en.wikipedia.org/wiki/WebSocket) protocol to communicate with the backend. However, it was decided in early 2020 that this usage of WebSocket – while functional – led to occasional wheel reinvention and disregarded an otherwise fully-featured technology (that is, REST).

    Years prior to this determination, many users of NodeBB had asked for a RESTful API to call against NodeBB, which led to the creation of [`nodebb-plugin-write-api`](https://github.com/NodeBB/nodebb-plugin-write-api). In tandem with the above decision, the Write API was merged into NodeBB core in late 2020.

    v3 of the Write API (this document) achieves rough feature parity with v2 of the Write API plugin.
  version: 1.15.0
  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/{uid}':
    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.yaml#/Status
                  response:
                    type: object
    put:
      tags:
        - users
      summary: update 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.yaml#/UserRequest
      responses:
        '200':
          description: user profile updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: components/schemas/Status.yaml#/Status
                  response:
                    $ref: components/schemas/UserObj.yaml#/UserObj
        '401':
          $ref: components/responses/401.yaml#/401
        '403':
          $ref: components/responses/403.yaml#/403
        '426':
          $ref: components/responses/426.yaml#/426
        '500':
          $ref: components/responses/500.yaml#/500
  '/users/{uid}/password':
    put:
      tags:
        - users
      summary: change 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.yaml#/Status
                  response:
                    type: object
  '/users/{uid}/follow':
    post:
      tags:
        - users
      summary: follow 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.yaml#/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.yaml#/Status
                  response:
                    type: object
  '/users/{uid}/ban':
    put:
      tags:
        - users
      summary: ban 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.yaml#/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.yaml#/Status
                  response:
                    type: object
  '/users/{uid}/tokens':
    post:
      tags:
        - users
      summary: generate a user token
      description: This route can only be used to generate tokens for the same user. In other words, you cannot use this route to generate a token for a different user than the one you are authenticated as.
      responses:
        '200':
          description: successfully generated a user token
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: components/schemas/Status.yaml#/Status
                  response:
                    type: object
    delete:
      tags:
        - users
      summary: delete user token
      parameters:
        - in: path
          name: token
          schema:
            type: string
          required: true
          description: a valid API token
      responses:
        '200':
          description: successfully deleted user token
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: components/schemas/Status.yaml#/Status
                  response:
                    type: object
  /categories/:
    $ref: 'write/categories.yaml'
  /groups/:
    $ref: 'write/groups.yaml'
  /groups/{slug}/membership/{uid}:
    $ref: 'write/groups/slug/membership/uid.yaml'
  /topics:
    $ref: 'write/topics.yaml'
  /topics/{tid}:
    $ref: 'write/topics/tid.yaml'
  /topics/{tid}/state:
    $ref: 'write/topics/tid/state.yaml'
  /topics/{tid}/lock:
    $ref: 'write/topics/tid/lock.yaml'
  /topics/{tid}/pin:
    $ref: 'write/topics/tid/pin.yaml'
  /topics/{tid}/follow:
    $ref: 'write/topics/tid/follow.yaml'
  /topics/{tid}/ignore:
    $ref: 'write/topics/tid/ignore.yaml'
  /topics/{tid}/tags:
    $ref: 'write/topics/tid/tags.yaml'
  /posts/{pid}:
    $ref: 'write/posts/pid.yaml'
  /posts/{pid}/state:
    $ref: 'write/posts/pid/state.yaml'
  /posts/{pid}/vote:
    $ref: 'write/posts/pid/vote.yaml'
  /posts/{pid}/bookmark:
    $ref: 'write/posts/pid/bookmark.yaml'
  /admin/settings/{setting}:
    $ref: 'write/admin/settings/setting.yaml'
  /files:
    $ref: 'write/files.yaml'