You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
952 lines
26 KiB
YAML
952 lines
26 KiB
YAML
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:
|
|
delete:
|
|
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: {}
|
|
put:
|
|
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}/state:
|
|
delete:
|
|
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: {}
|
|
put:
|
|
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: {}
|
|
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'
|