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/ :
post :
tags :
- users
summary : create a user
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 : delete 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}' :
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
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'
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'
'/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'
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'
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 : 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'
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
'/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'
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'
response :
type : object
/categories/ :
post :
tags :
- categories
summary : create 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 : peply 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:
put :
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 : {}
delete :
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}/pin:
put :
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 : {}
delete :
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 : {}
/topics/{tid}/follow:
put :
tags :
- topics
summary : follow a topic
description : This operation follows (or watches) a topic.
responses :
'200' :
description : Topic successfully followed
content :
application/json :
schema :
type : object
properties :
status :
$ref : '#/components/schemas/Status'
response :
type : object
properties : {}
delete :
tags :
- topics
summary : unfollow a topic
description : This operation unfollows (or unwatches) a topic.
responses :
'200' :
description : Topic successfully unwatched
content :
application/json :
schema :
type : object
properties :
status :
$ref : '#/components/schemas/Status'
response :
type : object
properties : {}
/topics/{tid}/ignore:
put :
tags :
- topics
summary : ignore a topic
description : This operation ignores (or watches) a topic.
responses :
'200' :
description : Topic successfully ignored
content :
application/json :
schema :
type : object
properties :
status :
$ref : '#/components/schemas/Status'
response :
type : object
properties : {}
delete :
tags :
- topics
summary : unignore a topic
description : This operation unignores (or unfollows/unwatches) a topic. It is functionally identical to `DEL /topics/{tid}/follow`.
responses :
'200' :
description : Topic successfully unignored/unwatched
content :
application/json :
schema :
type : object
properties :
status :
$ref : '#/components/schemas/Status'
response :
type : object
properties : {}
/topics/{tid}/tags:
put :
tags :
- topics
summary : adds tags to a topic
description : This operation adds tags to a topic
requestBody :
required : true
content :
application/json :
schema :
type : object
properties :
tags :
type : array
description : 'An array of tags'
items :
type : string
example :
tags :
- test
- foobar
responses :
'200' :
description : Topic tags successfully added
content :
application/json :
schema :
type : object
properties :
status :
$ref : '#/components/schemas/Status'
response :
type : object
properties : {}
delete :
tags :
- topics
summary : Removes all tags from a topic
description : This operation removed all tags associated with a topic.
responses :
'200' :
description : Topic tags successfully removed.
content :
application/json :
schema :
type : object
properties :
status :
$ref : '#/components/schemas/Status'
response :
type : object
properties : {}
/posts/{pid}:
put :
tags :
- posts
summary : edit a post
description : This operation edits a post
requestBody :
required : true
content :
application/json :
schema :
type : object
properties :
content :
type : string
description : New post content
title :
type : string
description : Topic title, only accepted for main posts
required :
- content
example :
content : 'New post content'
title : 'New title'
responses :
'200' :
description : Post successfully edited
content :
application/json :
schema :
type : object
properties :
status :
$ref : '#/components/schemas/Status'
response :
$ref : components/schemas/PostsObject.yaml#/PostsObject
delete :
tags :
- posts
summary : purge a post
description : This operation purges a post.
responses :
'200' :
description : Post successfully purged
content :
application/json :
schema :
type : object
properties :
status :
$ref : '#/components/schemas/Status'
response :
type : object
properties : {}
/posts/{pid}/state:
put :
tags :
- posts
summary : restore a post
description : This operation restores a post.
responses :
'200' :
description : Topic successfully restored
content :
application/json :
schema :
type : object
properties :
status :
$ref : '#/components/schemas/Status'
response :
type : object
properties : {}
delete :
tags :
- posts
summary : deletes a post
description : This operation soft deletes a post.
responses :
'200' :
description : Post successfully deleted
content :
application/json :
schema :
type : object
properties :
status :
$ref : '#/components/schemas/Status'
response :
type : object
properties : {}
/posts/{pid}/vote:
put :
tags :
- posts
summary : vote on a post
description : This operation casts a vote on a post.
requestBody :
required : true
content :
application/json :
schema :
type : object
properties :
delta :
type : number
description : Positive integer for upvote, negative integer for downvote (0 to unvote.)
example :
delta : 1
responses :
'200' :
description : Post successfully upvoted
content :
application/json :
schema :
type : object
properties :
status :
$ref : '#/components/schemas/Status'
response :
type : object
properties : {}
delete :
tags :
- posts
summary : unvote a post
description : This operation removes a pre-cast vote on a post.
responses :
'200' :
description : Post successfully unvoted
content :
application/json :
schema :
type : object
properties :
status :
$ref : '#/components/schemas/Status'
response :
type : object
properties : {}
/posts/{pid}/bookmark:
put :
tags :
- posts
summary : bookmark a post
description : This operation bookmarks a post.
responses :
'200' :
description : Post successfully bookmarked
content :
application/json :
schema :
type : object
properties :
status :
$ref : '#/components/schemas/Status'
response :
type : object
properties : {}
delete :
tags :
- posts
summary : unbookmark a post
description : This operation unbookmarks a post.
responses :
'200' :
description : Post successfully unbookmarked
content :
application/json :
schema :
type : object
properties :
status :
$ref : '#/components/schemas/Status'
response :
type : object
properties : {}
/admin/settings/{setting}:
put :
tags :
- admin
summary : update configuration setting
description : This operation updates a configuration setting in the backend. The calling user must have the `admin:settings` privilege (or be a superadmin) in order for this call to proceed.
parameters :
- in : path
name : setting
schema :
type : string
required : true
description : backend id of the setting to update
responses :
'200' :
description : Admin setting updated
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'
