readme.md

api/v1 Endpoints

Note: When requested with a master token, an additional parameter (_uid) is required in the data payload so the Write API can execute the requested action under the correct user context. This limitation means that certain actions only work with a specific uid. For example, PUT /:uid updates a user's profile information, but is only accessible by the uid of the user itself, or an administrative uid. All other uids passed in will result in an error.

• /api/v1
  • /users
    • POST /
      • Creates a new user
      • Requires: username
      • Accepts: password, email
      • Any other data passed in will be saved into the user hash
    • PUT /:uid
      • Updates a user's profile information
      • Accepts: username, email, fullname, website, location, birthday, signature
      • Also accepts any values exposed via the action:user.updateProfile hook
      • The uid specified in the route path is optional. Without it, the profile of the calling user is edited.
    • DELETE /:uid
      • Deletes a user from NodeBB (Careful: There is no confirmation!)
      • Accepts: No parameters
      • Can be called by either the target uid itself, or an administrative uid.
    • PUT /:uid/password
      • Changes a user's password
      • Requires: uid, new
      • Accepts: current
      • current is required if the calling user is not an administrator
    • POST /:uid/follow
      • Follows another user
      • Accepts: No parameters
    • DELETE /:uid/follow
      • Unfollows another user
      • Accepts: No parameters
    • POST /:uid/chats
      • Sends a chat message to another user
      • Requires: message
      • Accepts: timestamp, quiet
      • timestamp (unix timestamp in ms) allows messages to be sent from the past (useful when importing chats)
      • quiet if set, will not notify the user that a chat message has been received (also useful during imports)
    • POST /:uid/ban
      • Bans a user
    • DELETE /:uid/ban
      • Unbans a user
    • GET /:uid/tokens
      • Retrieves a list of active tokens for that user
      • Accepts: No parameters
    • POST /:uid/tokens
      • Creates a new user token for the passed in uid
      • Accepts: No parameters normally, will accept password in lieu of Bearer token
      • Can be called with an active token for that user
      • This is the only route that will allow you to pass in password in the request body. Generate a new token and then use the token in subsequent calls.
    • DELETE /:uid/tokens/:token
      • Revokes an active user token
      • Accepts: No parameters
  • /categories
    • POST /
      • Creates a new category
      • Requires: name
      • Accepts: description, bgColor, color, parentCid, class
    • PUT /:cid
      • Updates a category's data
      • Accepts: name, description, bgColor, color, parentCid
    • DELETE /:cid
      • Purges a category, including all topics and posts inside of it (Careful: There is no confirmation!)
      • Accepts: No parameters
    • PUT /:cid/state
      • Enables a category
      • Accepts: No parameters
    • DELETE /:cid/state
      • Disables a category
      • Accepts: No parameters
  • /groups
    • POST /
      • Creates a new group
      • Requires: name
      • Accepts: description, hidden, private, ownerUid
    • DELETE /:slug
      • Deletes a group (Careful: There is no confirmation!)
      • Accepts: No parameters
    • POST /:slug/membership
      • Joins a group (or requests membership if it is a private group)
      • Accepts: No parameters
    • DELETE /:slug/membership
      • Leaves a group
      • Accepts: No parameters
  • /topics
    • POST /
      • Creates a new topic
      • Requires: cid, title, content
      • Accepts: tags (array)
    • POST /:tid
      • Posts a new reply to the topic
      • Requires: content
      • Accepts: toPid
    • PUT /:tid
      • Updates a post in a topic
      • Requires: pid, content
      • Accepts: handle, title, topic_thumb, tags
    • DELETE /:tid
      • Deletes a topic (Careful: There is no confirmation!)
      • Accepts: No parameters
    • POST /:tid/follow
      • Subscribes a user to a topic
      • Accepts: No parameters
    • DELETE /:tid/follow
      • Unsubscribes a user to a topic
      • Accepts: No parameters
    • POST /:tid/tags
      • Creates or update tags in a topic
      • Requires: tags
      • This method does not append tags, it replaces the tag set associated with the topic
    • DELETE /:tid/tags
      • Accepts: No parameters
      • Clears the tag set associates with a topic
  • /posts
    • PUT /:pid
      • Edits a post by post ID
      • Requires: content
      • Accepts: title, topic_thumb, tags
    • DELETE /:pid
      • Deletes a post (Careful: There is no confirmation!)
      • Accepts: No parameters
    • POST /:pid/vote
      • Votes for a post
      • Requires: delta
      • delta must be a number. If delta > 0, it's considered an upvote; if delta < 0, it's considered a downvote; otherwise, it's an unvote.
    • DELETE /:pid/vote
      • Unvotes a post
      • Accepts: No parameters
  • /util
    • POST /upload
    • Uploads a File
    • Accepts: A multipart files array files[]