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.
214 lines
7.4 KiB
YAML
214 lines
7.4 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.
|
|
Since NodeBB v1.15.0, NodeBB has used 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) supercedes v2 of the Write API plugin, and is currently maintained.
|
|
|
|
# Authentication
|
|
|
|
Similarly to the Read API, the Write API support both session-based (cookie) and Bearer token authentication.
|
|
Please see the ["Authentication" section under the Read API](../read/#section/Overview/Authentication) for more information on how to authenticate against this API in order to make calls.
|
|
version: 3.0.0
|
|
contact:
|
|
email: support@nodebb.org
|
|
license:
|
|
name: GPL-3.0
|
|
servers:
|
|
- url: /api/v3
|
|
tags:
|
|
- name: utilities
|
|
description: Utility calls to test Write API functionality
|
|
- name: users
|
|
description: Account related calls (create, modify, delete, etc.)
|
|
- name: groups
|
|
description: Calls related to user groups
|
|
- name: categories
|
|
description: Administrative calls to manage categories
|
|
- name: topics
|
|
description: Topic-based calls (create, modify, delete, etc.)
|
|
- name: posts
|
|
description: Individual post-related calls (create, modify, delete, etc.)
|
|
- name: chats
|
|
description: Calls related to the user private messaging system
|
|
- name: admin
|
|
description: Administrative calls
|
|
- name: files
|
|
description: File upload routes
|
|
paths:
|
|
/ping:
|
|
$ref: 'write/ping.yaml'
|
|
/utilities/login:
|
|
$ref: 'write/login.yaml'
|
|
/users/:
|
|
$ref: 'write/users.yaml'
|
|
/users/{uid}:
|
|
$ref: 'write/users/uid.yaml'
|
|
/users/{uid}/picture:
|
|
$ref: 'write/users/uid/picture.yaml'
|
|
/users/{uid}/content:
|
|
$ref: 'write/users/uid/content.yaml'
|
|
/users/{uid}/account:
|
|
$ref: 'write/users/uid/account.yaml'
|
|
/users/{uid}/settings:
|
|
$ref: 'write/users/uid/settings.yaml'
|
|
/users/{uid}/password:
|
|
$ref: 'write/users/uid/password.yaml'
|
|
/users/{uid}/follow:
|
|
$ref: 'write/users/uid/follow.yaml'
|
|
/users/{uid}/ban:
|
|
$ref: 'write/users/uid/ban.yaml'
|
|
/users/{uid}/mute:
|
|
$ref: 'write/users/uid/mute.yaml'
|
|
/users/{uid}/tokens:
|
|
$ref: 'write/users/uid/tokens.yaml'
|
|
/users/{uid}/tokens/{token}:
|
|
$ref: 'write/users/uid/tokens/token.yaml'
|
|
/users/{uid}/sessions/{uuid}:
|
|
$ref: 'write/users/uid/sessions/uuid.yaml'
|
|
/users/{uid}/invites:
|
|
$ref: 'write/users/uid/invites.yaml'
|
|
/users/{uid}/invites/groups:
|
|
$ref: 'write/users/uid/invites/groups.yaml'
|
|
/users/{uid}/emails:
|
|
$ref: 'write/users/uid/emails.yaml'
|
|
/users/{uid}/emails/{email}:
|
|
$ref: 'write/users/uid/emails/email.yaml'
|
|
/users/{uid}/emails/{email}/confirm:
|
|
$ref: 'write/users/uid/emails/email/confirm.yaml'
|
|
/users/{uid}/exports/{type}:
|
|
$ref: 'write/users/uid/exports/type.yaml'
|
|
/groups/:
|
|
$ref: 'write/groups.yaml'
|
|
/groups/{slug}:
|
|
$ref: 'write/groups/slug.yaml'
|
|
/groups/{slug}/membership/{uid}:
|
|
$ref: 'write/groups/slug/membership/uid.yaml'
|
|
/groups/{slug}/ownership/{uid}:
|
|
$ref: 'write/groups/slug/ownership/uid.yaml'
|
|
/groups/{slug}/pending:
|
|
$ref: 'write/groups/slug/pending.yaml'
|
|
/groups/{slug}/pending/{uid}:
|
|
$ref: 'write/groups/slug/pending/uid.yaml'
|
|
/groups/{slug}/invites:
|
|
$ref: 'write/groups/slug/invites.yaml'
|
|
/groups/{slug}/invites/{uid}:
|
|
$ref: 'write/groups/slug/invites/uid.yaml'
|
|
/categories/:
|
|
$ref: 'write/categories.yaml'
|
|
/categories/{cid}:
|
|
$ref: 'write/categories/cid.yaml'
|
|
/categories/{cid}/privileges:
|
|
$ref: 'write/categories/cid/privileges.yaml'
|
|
/categories/{cid}/privileges/{privilege}:
|
|
$ref: 'write/categories/cid/privileges/privilege.yaml'
|
|
/categories/{cid}/moderator/{uid}:
|
|
$ref: 'write/categories/cid/moderator/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'
|
|
/topics/{tid}/thumbs:
|
|
$ref: 'write/topics/tid/thumbs.yaml'
|
|
/topics/{tid}/thumbs/order:
|
|
$ref: 'write/topics/tid/thumbs/order.yaml'
|
|
/topics/{tid}/events:
|
|
$ref: 'write/topics/tid/events.yaml'
|
|
/topics/{tid}/events/{eventId}:
|
|
$ref: 'write/topics/tid/events/eventId.yaml'
|
|
/topics/{tid}/read:
|
|
$ref: 'write/topics/tid/read.yaml'
|
|
/topics/{tid}/bump:
|
|
$ref: 'write/topics/tid/bump.yaml'
|
|
/posts/{pid}:
|
|
$ref: 'write/posts/pid.yaml'
|
|
/posts/{pid}/index:
|
|
$ref: 'write/posts/pid/index.yaml'
|
|
/posts/{pid}/raw:
|
|
$ref: 'write/posts/pid/raw.yaml'
|
|
/posts/{pid}/summary:
|
|
$ref: 'write/posts/pid/summary.yaml'
|
|
/posts/{pid}/state:
|
|
$ref: 'write/posts/pid/state.yaml'
|
|
/posts/{pid}/move:
|
|
$ref: 'write/posts/pid/move.yaml'
|
|
/posts/{pid}/vote:
|
|
$ref: 'write/posts/pid/vote.yaml'
|
|
/posts/{pid}/bookmark:
|
|
$ref: 'write/posts/pid/bookmark.yaml'
|
|
/posts/{pid}/diffs:
|
|
$ref: 'write/posts/pid/diffs.yaml'
|
|
/posts/{pid}/diffs/{since}:
|
|
$ref: 'write/posts/pid/diffs/since.yaml'
|
|
/posts/{pid}/diffs/{timestamp}:
|
|
$ref: 'write/posts/pid/diffs/timestamp.yaml'
|
|
/posts/{pid}/replies:
|
|
$ref: 'write/posts/pid/replies.yaml'
|
|
/chats/:
|
|
$ref: 'write/chats.yaml'
|
|
/chats/{roomId}:
|
|
$ref: 'write/chats/roomId.yaml'
|
|
/chats/{roomId}/state:
|
|
$ref: 'write/chats/roomId/state.yaml'
|
|
/chats/{roomId}/users:
|
|
$ref: 'write/chats/roomId/users.yaml'
|
|
/chats/{roomId}/users/{uid}:
|
|
$ref: 'write/chats/roomId/users/uid.yaml'
|
|
/chats/{roomId}/messages:
|
|
$ref: 'write/chats/roomId/messages.yaml'
|
|
/chats/{roomId}/messages/{mid}:
|
|
$ref: 'write/chats/roomId/messages/mid.yaml'
|
|
/chats/{roomId}/messages/{mid}/pin:
|
|
$ref: 'write/chats/roomId/messages/mid/pin.yaml'
|
|
/flags/:
|
|
$ref: 'write/flags.yaml'
|
|
/flags/{flagId}:
|
|
$ref: 'write/flags/flagId.yaml'
|
|
/flags/{flagId}/notes:
|
|
$ref: 'write/flags/flagId/notes.yaml'
|
|
/flags/{flagId}/notes/{datetime}:
|
|
$ref: 'write/flags/flagId/notes/datetime.yaml'
|
|
/admin/settings/{setting}:
|
|
$ref: 'write/admin/settings/setting.yaml'
|
|
/admin/analytics:
|
|
$ref: 'write/admin/analytics.yaml'
|
|
/admin/analytics/{set}:
|
|
$ref: 'write/admin/analytics/set.yaml'
|
|
/admin/chats/{roomId}:
|
|
$ref: 'write/admin/chats/roomId.yaml'
|
|
/admin/tokens:
|
|
$ref: 'write/admin/tokens.yaml'
|
|
/admin/tokens/{token}:
|
|
$ref: 'write/admin/tokens/token.yaml'
|
|
/admin/tokens/{token}/roll:
|
|
$ref: 'write/admin/tokens/token/roll.yaml'
|
|
/files/:
|
|
$ref: 'write/files.yaml'
|
|
/files/folder:
|
|
$ref: 'write/files/folder.yaml' |