mirror of
https://github.com/NodeBB/NodeBB.git
synced 2026-05-07 10:25:46 +02:00
e395fb0919
* **feat**: add support for setting watch state via category ID and member UID in route params * **feat**: update category watch/privilege routes and logic to use `member` param instead of `uid`/`member` body field * **feat**: add support for unfollowing via actor parameter in category routes * **feat**: add deprecation warnings for legacy category routes and refactor privilege fetching to inline async call * docs: add openapi specs for new category routes with path parameters Co-authored-by: aider (ollama/ministral-3:8b) <aider@aider.chat> * fix: some minor errors in file paths * feat: support path extraction from req.query in assert.path middleware Co-authored-by: aider (ollama/ministral-3:8b) <aider@aider.chat> * feat: support message from both query and body in removeQueuedPost Co-authored-by: aider (ollama/ministral-3:8b) <aider@aider.chat> * fix: remove ai-added check that path is defined, it is not required * fix: send message as query param instead of in body, when rejecting queued post * lint: comma dangle * `feat(openapi): add optional query parameter support for topic delete endpoints` Co-authored-by: aider (ollama/ministral-3:8b) <aider@aider.chat> * feat: add query parameter and make request body optional for topic thumbnail deletion Co-authored-by: aider (ollama/ministral-3:8b) <aider@aider.chat> * feat: support query params for thumb path and crosspost id in topics endpoints Co-authored-by: aider (ollama/ministral-3:8b) <aider@aider.chat> * feat: add query params for mute/unmute reason and timestamp Co-authored-by: aider (ollama/ministral-3:8b) <aider@aider.chat> * docs: update unmute API to support query params for reason and until timestamp Co-authored-by: aider (ollama/ministral-3:8b) <aider@aider.chat> * docs: update unmute endpoint to support reason via request body Co-authored-by: aider (ollama/ministral-3:8b) <aider@aider.chat> * feat: add reason parameter support to users.unmute Co-authored-by: aider (ollama/ministral-3:8b) <aider@aider.chat> * feat: allow unban reason to be sent via req.query * fix: timestamps are unix timestamps not 8601 * docs: mute shouldn't have been updated * chore: remove deprecation warnings --------- Co-authored-by: aider (ollama/ministral-3:8b) <aider@aider.chat>
312 lines
11 KiB
YAML
312 lines
11 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}/status:
|
|
$ref: 'write/users/uid/status.yaml'
|
|
/users/{uid}/status/{status}:
|
|
$ref: 'write/users/uid/status/status.yaml'
|
|
/users/{uid}/chat:
|
|
$ref: 'write/users/uid/chat.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}/members:
|
|
$ref: 'write/groups/slug/members.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}/count:
|
|
$ref: 'write/categories/cid/count.yaml'
|
|
/categories/{cid}/posts:
|
|
$ref: 'write/categories/cid/posts.yaml'
|
|
/categories/{cid}/children:
|
|
$ref: 'write/categories/cid/children.yaml'
|
|
/categories/{cid}/topics:
|
|
$ref: 'write/categories/cid/topics.yaml'
|
|
/categories/{cid}/watch:
|
|
$ref: 'write/categories/cid/watch.yaml'
|
|
/categories/{cid}/watch/{member}:
|
|
$ref: 'write/categories/cid/watch/member.yaml'
|
|
/categories/{cid}/privileges:
|
|
$ref: 'write/categories/cid/privileges.yaml'
|
|
/categories/{cid}/privileges/{privilege}:
|
|
$ref: 'write/categories/cid/privileges/privilege.yaml'
|
|
/categories/{cid}/privileges/{privilege}/{member}:
|
|
$ref: 'write/categories/cid/privileges/privilege/member.yaml'
|
|
/categories/{cid}/moderator/{uid}:
|
|
$ref: 'write/categories/cid/moderator/uid.yaml'
|
|
/categories/{cid}/follow:
|
|
$ref: 'write/categories/cid/follow.yaml'
|
|
/categories/{cid}/follow/{actor}:
|
|
$ref: 'write/categories/cid/follow/actor.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'
|
|
/topics/{tid}/move:
|
|
$ref: 'write/topics/tid/move.yaml'
|
|
/topics/{tid}/crossposts:
|
|
$ref: 'write/topics/tid/crossposts.yaml'
|
|
/tags/{tag}/follow:
|
|
$ref: 'write/tags/tag/follow.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}/voters:
|
|
$ref: 'write/posts/pid/voters.yaml'
|
|
/posts/{pid}/upvoters:
|
|
$ref: 'write/posts/pid/upvoters.yaml'
|
|
/posts/{pid}/announcers:
|
|
$ref: 'write/posts/pid/announcers.yaml'
|
|
/posts/{pid}/announcers/tooltip:
|
|
$ref: 'write/posts/pid/announcers-tooltip.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'
|
|
/posts/queue/{id}:
|
|
$ref: 'write/posts/queue/id.yaml'
|
|
/posts/queue/{id}/notify:
|
|
$ref: 'write/posts/queue/notify.yaml'
|
|
/posts/{pid}/owner:
|
|
$ref: 'write/posts/pid/owner.yaml'
|
|
/posts/owner:
|
|
$ref: 'write/posts/owner.yaml'
|
|
/notifications:
|
|
$ref: 'write/notifications.yaml'
|
|
/notifications/{nid}:
|
|
$ref: 'write/notifications/nid.yaml'
|
|
/notifications/count:
|
|
$ref: 'write/notifications/count.yaml'
|
|
/notifications/{nid}/read:
|
|
$ref: 'write/notifications/nid/read.yaml'
|
|
/chats/:
|
|
$ref: 'write/chats.yaml'
|
|
/chats/unread:
|
|
$ref: 'write/chats/unread.yaml'
|
|
/chats/sort:
|
|
$ref: 'write/chats/sort.yaml'
|
|
/chats/{roomId}:
|
|
$ref: 'write/chats/roomId.yaml'
|
|
/chats/{roomId}/state:
|
|
$ref: 'write/chats/roomId/state.yaml'
|
|
/chats/{roomId}/watch:
|
|
$ref: 'write/chats/roomId/watch.yaml'
|
|
/chats/{roomId}/typing:
|
|
$ref: 'write/chats/roomId/typing.yaml'
|
|
/chats/{roomId}/users:
|
|
$ref: 'write/chats/roomId/users.yaml'
|
|
/chats/{roomId}/users/{uid}:
|
|
$ref: 'write/chats/roomId/users/uid.yaml'
|
|
/chats/{roomId}/owners/{uid}:
|
|
$ref: 'write/chats/roomId/owners/uid.yaml'
|
|
/chats/{roomId}/messages:
|
|
$ref: 'write/chats/roomId/messages.yaml'
|
|
/chats/{roomId}/messages/pinned:
|
|
$ref: 'write/chats/roomId/messages/pinned.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'
|
|
/chats/{roomId}/messages/{mid}/raw:
|
|
$ref: 'write/chats/roomId/messages/mid/raw.yaml'
|
|
/chats/{roomId}/messages/{mid}/ip:
|
|
$ref: 'write/chats/roomId/messages/mid/ip.yaml'
|
|
/flags/:
|
|
$ref: 'write/flags.yaml'
|
|
/flags/{flagId}:
|
|
$ref: 'write/flags/flagId.yaml'
|
|
/flags/{flagId}/report:
|
|
$ref: 'write/flags/flagId/report.yaml'
|
|
/flags/{flagId}/notes:
|
|
$ref: 'write/flags/flagId/notes.yaml'
|
|
/flags/{flagId}/notes/{datetime}:
|
|
$ref: 'write/flags/flagId/notes/datetime.yaml'
|
|
/search/categories:
|
|
$ref: 'write/search/categories.yaml'
|
|
/search/chats/{roomId}/users:
|
|
$ref: 'write/search/chats/roomId/users.yaml'
|
|
/search/chats/{roomId}/messages:
|
|
$ref: 'write/search/chats/roomId/messages.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/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'
|
|
/admin/chats/{roomId}:
|
|
$ref: 'write/admin/chats/roomId.yaml'
|
|
/admin/groups:
|
|
$ref: 'write/admin/groups.yaml'
|
|
/admin/activitypub/rules:
|
|
$ref: 'write/admin/activitypub/rules.yaml'
|
|
/admin/activitypub/rules/{rid}:
|
|
$ref: 'write/admin/activitypub/rules/rid.yaml'
|
|
/admin/activitypub/rules/order:
|
|
$ref: 'write/admin/activitypub/rules/order.yaml'
|
|
/admin/activitypub/relays:
|
|
$ref: 'write/admin/activitypub/relays.yaml'
|
|
/admin/activitypub/relays/{url}:
|
|
$ref: 'write/admin/activitypub/relays/url.yaml'
|
|
/admin/activitypub/blocklists:
|
|
$ref: 'write/admin/activitypub/blocklists.yaml'
|
|
/admin/activitypub/blocklists/{url}:
|
|
$ref: 'write/admin/activitypub/blocklists/url.yaml'
|
|
/admin/activitypub/blocklists/{url}/refresh:
|
|
$ref: 'write/admin/activitypub/blocklists/url/refresh.yaml'
|
|
/files/:
|
|
$ref: 'write/files.yaml'
|
|
/files/folder:
|
|
$ref: 'write/files/folder.yaml' |