# `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[]`