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:
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 : {}
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'
