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.
313 lines
9.2 KiB
YAML
313 lines
9.2 KiB
YAML
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/{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.yaml#/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.yaml#/UserRequest
|
|
responses:
|
|
'200':
|
|
description: user profile updated
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
status:
|
|
$ref: components/schemas/Status.yaml#/Status
|
|
response:
|
|
$ref: components/schemas/UserObj.yaml#/UserObj
|
|
'401':
|
|
$ref: components/responses/401.yaml#/401
|
|
'403':
|
|
$ref: components/responses/403.yaml#/403
|
|
'426':
|
|
$ref: components/responses/426.yaml#/426
|
|
'500':
|
|
$ref: components/responses/500.yaml#/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.yaml#/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.yaml#/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.yaml#/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.yaml#/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.yaml#/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.yaml#/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.yaml#/Status
|
|
response:
|
|
type: object
|
|
/categories/:
|
|
$ref: 'write/categories.yaml'
|
|
/groups/:
|
|
$ref: 'write/groups.yaml'
|
|
/groups/{slug}/membership/{uid}:
|
|
$ref: 'write/groups/slug/membership/uid.yaml'
|
|
/topics:
|
|
$ref: 'write/topics.yaml'
|
|
/topics/{tid}:
|
|
$ref: 'write/topics/tid.yaml'
|
|
/topics/{tid}/state:
|
|
$ref: 'write/topics/tid/state.yaml'
|
|
/topics/{tid}/lock:
|
|
$ref: 'write/topics/tid/lock.yaml'
|
|
/topics/{tid}/pin:
|
|
$ref: 'write/topics/tid/pin.yaml'
|
|
/topics/{tid}/follow:
|
|
$ref: 'write/topics/tid/follow.yaml'
|
|
/topics/{tid}/ignore:
|
|
$ref: 'write/topics/tid/ignore.yaml'
|
|
/topics/{tid}/tags:
|
|
$ref: 'write/topics/tid/tags.yaml'
|
|
/posts/{pid}:
|
|
$ref: 'write/posts/pid.yaml'
|
|
/posts/{pid}/state:
|
|
$ref: 'write/posts/pid/state.yaml'
|
|
/posts/{pid}/vote:
|
|
$ref: 'write/posts/pid/vote.yaml'
|
|
/posts/{pid}/bookmark:
|
|
$ref: 'write/posts/pid/bookmark.yaml'
|
|
/admin/settings/{setting}:
|
|
$ref: 'write/admin/settings/setting.yaml'
|
|
/files:
|
|
$ref: 'write/files.yaml' |