openapi: 3.0.0 info: title: nodebb version: 1.13.2 license: name: GPL-3.0 description: >- # Overview The following document outlines every Read API route available via NodeBB. Unlike the write API, the v1.x API was coded organically, and is **not** strictly RESTful. These shortcomings will be addressed in time as the APIs mature. ## Shortcomings The Read API is named because its primary use is by NodeBB itself when navigating between pages. Therefore, the routes almost universally always follow the same path as actual pages on NodeBB itself. There are also a small number of non-`GET` routes, which doesn't necessarily make sense in a Read API. These will be merged into the Write API in time. ## Authentication There are a multitude of ways to authenticate with the Read API. ### Cookie Authentication This default authentication behaviour of this API is via cookie jar to find a valid session. A valid login session is required for API calls that pertain to operations involving a logged-in user. For example, `/api/unread` is a route showing unread topics, and is not accessible by guest users. ### Bearer Authentication Both the Read API and Write API offers bearer authentication, as administered through the administration panel. * For NodeBB v1.x, this is provided by [`nodebb-plugin-write-api`](https://github.com/NodeBB/nodebb-plugin-write-api). The Write API plugin needs to be installed before authentication via bearer token is enabled on routes provided by the Read API. * For NodeBB v2.x+ (in development), the Write API is available in core, and bearer authentication is available out-of-the-box ### JSON Web Token (JWT) The Write API also consumes valid JWTs as payload bodies, when signed with a server-generated key. The same restrictions apply as above, with Bearer Authentication (re: NodeBB v1.x vs v2.x). tags: - name: home description: Routes used at the forum index only - name: categories description: Category hierarchy and navigation - name: topics - name: posts - name: users - name: authentication description: User authentication (e.g. login/registration) - name: groups description: User groups - name: admin description: Administrative Control Panel (ACP) routing - name: emails description: Email utilities - name: flags description: Reporting of content by users - name: notifications description: Real-time notifications - name: search - name: tags description: Disparate method of categorizing topics - name: shorthand description: Convenience and utility routes for accessing other part of the API paths: /api/: get: tags: - home description: > This route is used to populate the homepage of NodeBB. It is the main access point of the forum, and shows a list of categories for navigation purposes. summary: Get forum index data responses: "200": description: "" content: application/json: schema: allOf: - type: object properties: title: type: string description: The page title categories: description: A collection of category data objects type: array items: allOf: - $ref: components/schemas/CategoryObject.yaml#/CategoryObject - type: object properties: tagWhitelist: type: array items: type: string unread-class: type: string children: type: array items: allOf: - $ref: components/schemas/CategoryObject.yaml#/CategoryObject - type: object properties: tagWhitelist: type: array items: type: string unread-class: type: string children: type: array items: $ref: components/schemas/CategoryObject.yaml#/CategoryObject parent: allOf: - $ref: components/schemas/CategoryObject.yaml#/CategoryObject - type: object properties: tagWhitelist: type: array items: type: string unread-class: type: string posts: type: array items: type: object properties: pid: type: number timestamp: type: number content: type: string timestampISO: type: string description: An ISO 8601 formatted date string (complementing `timestamp`) user: type: object properties: uid: type: number description: A user identifier username: type: string description: A friendly name for a given user account userslug: type: string description: An URL-safe variant of the username (i.e. lower-cased, spaces removed, etc.) picture: nullable: true type: string icon:text: type: string description: A single-letter representation of a username. This is used in the auto-generated icon given to users without an avatar icon:bgColor: type: string description: A six-character hexadecimal colour code assigned to the user. This value is used in conjunction with `icon:text` for the user's auto-generated icon example: "#f44336" index: type: number cid: type: number description: A category identifier parentCid: type: number description: The category identifier for the category that is the immediate ancestor of the current category topic: type: object properties: slug: type: string title: type: string imageClass: type: string timesClicked: type: number posts: type: array items: type: object properties: pid: type: number timestamp: type: number content: type: string timestampISO: type: string description: An ISO 8601 formatted date string (complementing `timestamp`) user: type: object properties: uid: type: number description: A user identifier username: type: string description: A friendly name for a given user account userslug: type: string description: An URL-safe variant of the username (i.e. lower-cased, spaces removed, etc.) picture: nullable: true type: string icon:text: type: string description: A single-letter representation of a username. This is used in the auto-generated icon given to users without an avatar icon:bgColor: type: string description: A six-character hexadecimal colour code assigned to the user. This value is used in conjunction with `icon:text` for the user's auto-generated icon example: "#f44336" index: type: number cid: type: number description: A category identifier parentCid: type: number description: The category identifier for the category that is the immediate ancestor of the current category topic: type: object properties: slug: type: string title: type: string teaser: type: object properties: url: type: string timestampISO: type: string description: An ISO 8601 formatted date string (complementing `timestamp`) pid: type: number topic: type: object properties: slug: type: string title: type: string imageClass: type: string - $ref: components/schemas/CommonProps.yaml#/CommonProps /api/admin/dashboard: get: tags: - admin summary: Get administrative dashboard responses: "200": description: A JSON object containing dashboard data content: application/json: schema: allOf: - type: object properties: version: type: string lookupFailed: type: boolean latestVersion: type: string nullable: true upgradeAvailable: type: boolean nullable: true currentPrerelease: type: boolean notices: type: array items: type: object properties: done: type: boolean doneText: type: string notDoneText: type: string tooltip: type: string link: type: string required: - done stats: type: array items: type: object properties: yesterday: type: number today: type: number lastweek: type: number thisweek: type: number lastmonth: type: number thismonth: type: number alltime: type: number dayIncrease: type: string dayTextClass: type: string weekIncrease: type: string weekTextClass: type: string monthIncrease: type: string monthTextClass: type: string name: type: string canRestart: type: boolean lastrestart: nullable: true type: object properties: uid: type: number description: A user identifier ip: type: string timestamp: type: number user: $ref: components/schemas/UserObject.yaml#/UserObject timestampISO: type: string description: An ISO 8601 formatted date string (complementing `timestamp`) - $ref: components/schemas/CommonProps.yaml#/CommonProps /api/admin/settings/languages: get: tags: - admin summary: Get language settings responses: "200": description: A JSON object containing available languages and settings content: application/json: schema: allOf: - type: object properties: languages: type: array items: type: object properties: name: type: string description: Localised name of the language code: type: string description: A language code (similar to ISO-639) dir: type: string description: Directionality of the language enum: [ltr, rtl] selected: type: boolean description: Denotes the currently selected default system language on the forum autoDetectLang: type: integer description: Whether the forum will attempt to guess language based on browser's `Accept-Language` header - $ref: components/schemas/CommonProps.yaml#/CommonProps /api/admin/settings/sounds: get: tags: - admin summary: Get sound settings responses: "200": description: A JSON object containing available sounds and settings content: application/json: schema: allOf: - type: object properties: notification-sound: type: array items: type: object properties: name: type: string sounds: type: array items: type: object properties: name: type: string value: type: string selected: type: boolean chat-incoming-sound: type: array items: type: object properties: name: type: string sounds: type: array items: type: object properties: name: type: string value: type: string selected: type: boolean chat-outgoing-sound: type: array items: type: object properties: name: type: string sounds: type: array items: type: object properties: name: type: string value: type: string selected: type: boolean - $ref: components/schemas/CommonProps.yaml#/CommonProps /api/admin/settings/navigation: get: tags: - admin summary: Get navigation bar settings responses: "200": description: A JSON object containing navigation settings content: application/json: schema: allOf: - type: object properties: enabled: type: array items: type: object properties: route: type: string description: Relative URL to the page the navigation item goes to title: type: string description: Tooltip text enabled: type: boolean iconClass: type: string description: A FontAwesome icon string textClass: type: string description: HTML class applied to the text label for this navigation item text: type: string description: Label text for this navigation item order: type: integer description: Ordinality of this item, lower value appears earlier groups: type: array items: type: object properties: displayName: type: string selected: type: boolean index: type: integer description: Seemingly identical to order, but an integer instead of a string selected: type: boolean available: type: array items: type: object properties: id: type: string description: Unique ID that will be added to the navigation element's `id` property in the DOM route: type: string description: Relative URL to the page the navigation item goes to title: type: string description: Tooltip text enabled: type: boolean iconClass: type: string description: A FontAwesome icon string textClass: type: string description: HTML class applied to the text label for this navigation item text: type: string description: Label text for this navigation item core: type: boolean description: Whether the navigation item is provided by core or not (a plugin) groups: type: array items: type: object properties: name: type: string displayName: type: string properties: type: object properties: targetBlank: type: boolean groups: type: array items: type: object properties: name: type: string displayName: type: string navigation: type: array description: A clone of `enabled` - $ref: components/schemas/CommonProps.yaml#/CommonProps /api/admin/settings/homepage: get: tags: - admin summary: Get homepage settings responses: "200": description: "" content: application/json: schema: allOf: - type: object properties: routes: type: array items: type: object properties: route: type: string name: type: string - $ref: components/schemas/CommonProps.yaml#/CommonProps /api/admin/settings/social: get: tags: - admin summary: Get post social sharing settings responses: "200": description: "A JSON object containing post social sharing settings" content: application/json: schema: allOf: - type: object properties: posts: type: array items: type: object properties: id: type: string name: type: string class: type: string description: A FontAwesome icon string activated: type: boolean - $ref: components/schemas/CommonProps.yaml#/CommonProps /api/admin/manage/categories: get: tags: - admin summary: Get category management settings responses: "200": description: "" content: application/json: schema: $ref: components/schemas/CommonProps.yaml#/CommonProps "/api/admin/manage/categories/{category_id}": get: tags: - admin summary: Get category settings parameters: - name: category_id in: path required: true schema: type: string example: 1 responses: "200": description: "" content: application/json: schema: allOf: - type: object properties: category: allOf: - $ref: components/schemas/CategoryObject.yaml#/CategoryObject - type: object properties: tagWhitelist: type: array items: type: string unread-class: type: string parent: $ref: components/schemas/CategoryObject.yaml#/CategoryObject allCategories: type: array items: type: object properties: text: type: string value: type: number selected: type: boolean customClasses: type: array items: type: string - $ref: components/schemas/CommonProps.yaml#/CommonProps "/api/admin/manage/categories/{category_id}/analytics": get: tags: - admin summary: Get category anayltics parameters: - name: category_id in: path required: true schema: type: string example: 1 responses: "200": description: "" content: application/json: schema: allOf: - type: object properties: name: type: string analytics: type: object properties: pageviews:hourly: type: array items: type: number pageviews:daily: type: array items: type: number topics:daily: type: array items: type: number posts:daily: type: array items: type: number - $ref: components/schemas/CommonProps.yaml#/CommonProps "/api/admin/manage/privileges/{cid}": get: tags: - admin summary: Get category privileges parameters: - name: cid in: path required: true schema: type: string example: 1 responses: "200": description: "" content: application/json: schema: allOf: - type: object properties: privileges: type: object properties: labels: type: object properties: users: type: array items: type: object properties: name: type: string groups: type: array items: type: object properties: name: type: string users: type: array items: type: object properties: name: type: string nameEscaped: type: string privileges: type: object additionalProperties: type: boolean description: Each privilege will have a key in this object groups: type: array items: type: object properties: name: type: string nameEscaped: type: string privileges: type: object additionalProperties: type: boolean description: Each privilege will have a key in this object isPrivate: type: boolean columnCountUser: type: number columnCountUserOther: type: number columnCountGroup: type: number columnCountGroupOther: type: number categories: type: array items: type: object properties: cid: type: number description: A category identifier name: type: string icon: type: string selected: type: boolean level: type: string parentCid: type: number description: The category identifier for the category that is the immediate ancestor of the current category color: type: string bgColor: type: string imageClass: type: string required: - cid - name - icon - selected selectedCategory: type: object properties: cid: type: number description: A category identifier name: type: string level: type: string icon: type: string parentCid: type: number description: The category identifier for the category that is the immediate ancestor of the current category color: type: string bgColor: type: string imageClass: type: string selected: type: boolean cid: type: number description: A category identifier - $ref: components/schemas/CommonProps.yaml#/CommonProps /api/admin/manage/tags: get: tags: - admin summary: Get tag settings responses: "200": description: "A JSON object containing tag settings" content: application/json: schema: allOf: - type: object properties: tags: type: array items: type: object properties: value: type: string description: The tag name score: type: number description: The number of topics containing this tag valueEscaped: type: string color: type: string description: Six-character hexadecimal string (with `#` prepended) example: "#ff0000" bgColor: type: string description: Six-character hexadecimal string (with `#` prepended) example: "#ff0000" - $ref: components/schemas/CommonProps.yaml#/CommonProps /api/admin/manage/users: get: tags: - admin summary: Get users responses: "200": description: "" content: application/json: schema: allOf: - type: object properties: users: type: array items: $ref: components/schemas/UserObject.yaml#/UserObjectACP page: type: number pageCount: type: number resultsPerPage: type: number latest: type: boolean search_display: type: string requireEmailConfirmation: type: number inviteOnly: type: boolean adminInviteOnly: type: boolean - $ref: components/schemas/Pagination.yaml#/Pagination - $ref: components/schemas/CommonProps.yaml#/CommonProps /api/admin/manage/users/search: get: tags: - admin summary: Get users via search term responses: "200": description: "" content: application/json: schema: allOf: - type: object properties: search_display: type: string users: type: array items: $ref: components/schemas/UserObject.yaml#/UserObjectACP - $ref: components/schemas/CommonProps.yaml#/CommonProps /api/admin/manage/users/latest: get: tags: - admin summary: Get latest users responses: "418": description: "TODO: A proper response needs to be added. It is not really a teapot | Replace this responses block with the block from /manage/users/latest" /api/admin/manage/users/not-validated: get: tags: - admin summary: Get non-verified users responses: "418": description: "TODO: A proper response needs to be added. It is not really a teapot | Replace this responses block with the block from /manage/users/latest" /api/admin/manage/users/no-posts: get: tags: - admin summary: Get users with no posts responses: "418": description: "TODO: A proper response needs to be added. It is not really a teapot | Replace this responses block with the block from /manage/users/latest" /api/admin/manage/users/top-posters: get: tags: - admin summary: Get users with the most posts responses: "418": description: "TODO: A proper response needs to be added. It is not really a teapot | Replace this responses block with the block from /manage/users/latest" /api/admin/manage/users/most-reputation: get: tags: - admin summary: Get users with the most reputation responses: "418": description: "TODO: A proper response needs to be added. It is not really a teapot | Replace this responses block with the block from /manage/users/latest" /api/admin/manage/users/inactive: get: tags: - admin summary: Get inactive users responses: "418": description: "TODO: A proper response needs to be added. It is not really a teapot | Replace this responses block with the block from /manage/users/latest" /api/admin/manage/users/flagged: get: tags: - admin summary: Get flagged users responses: "418": description: "TODO: A proper response needs to be added. It is not really a teapot | Replace this responses block with the block from /manage/users/latest" /api/admin/manage/users/banned: get: tags: - admin summary: Get banned users responses: "418": description: "TODO: A proper response needs to be added. It is not really a teapot | Replace this responses block with the block from /manage/users/latest" /api/admin/manage/registration: get: tags: - admin summary: Get registration queue/invites responses: "200": description: "A JSON object containing the registration queue and invites" content: application/json: schema: allOf: - type: object properties: registrationQueueCount: type: number users: type: array items: type: object properties: username: type: string email: type: string ip: type: string timestampISO: type: string usernameEscaped: type: string ipMatch: type: array items: type: object properties: username: type: string description: A friendly name for a given user account userslug: type: string description: An URL-safe variant of the username (i.e. lower-cased, spaces removed, etc.) picture: type: string uid: type: number description: A user identifier icon:text: type: string description: A single-letter representation of a username. This is used in the auto-generated icon given to users without an avatar icon:bgColor: type: string description: A six-character hexadecimal colour code assigned to the user. This value is used in conjunction with `icon:text` for the user's auto-generated icon example: "#f44336" customActions: type: array items: type: object properties: title: type: string id: type: string class: type: string icon: type: string customHeaders: type: array invites: type: array items: type: object properties: uid: type: number invitations: type: array items: type: object properties: email: type: string - $ref: components/schemas/Pagination.yaml#/Pagination - $ref: components/schemas/CommonProps.yaml#/CommonProps /api/admin/manage/admins-mods: get: tags: - admin summary: Get administrators and moderators responses: "200": description: "A JSON object containing administrators and moderators globally and per-category" content: application/json: schema: allOf: - type: object properties: admins: $ref: components/schemas/GroupObject.yaml#/GroupFullObject globalMods: $ref: components/schemas/GroupObject.yaml#/GroupFullObject categories: type: array items: type: object properties: cid: type: number name: type: string level: type: number example: 0 icon: type: string description: A FontAwesome icon string parentCid: type: number description: The parent category's identifier color: type: string description: A six-character hexadecimal colour code bgColor: type: string description: A six-character hexadecimal colour code imageClass: type: string depth: type: number description: The depth of the category relative to the forum root (`0` is root level) moderators: type: array items: $ref: components/schemas/UserObject.yaml#/UserObjectSlim allPrivileges: type: array items: type: string description: A simple array containing user privilege names (used client-side when giving mod privilege) - $ref: components/schemas/CommonProps.yaml#/CommonProps /api/admin/manage/groups: get: tags: - admin summary: Get user groups responses: "200": description: "" content: application/json: schema: allOf: - type: object properties: groups: type: array items: type: object properties: name: type: string description: type: string deleted: oneOf: - type: number - type: string hidden: type: number system: type: number userTitle: type: string icon: type: string labelColor: type: string slug: type: string createtime: type: number memberCount: type: number private: type: number cover:url: type: string cover:position: type: string userTitleEnabled: type: number disableJoinRequests: type: number disableLeave: type: number nameEncoded: type: string displayName: type: string textColor: type: string createtimeISO: type: string cover:thumb:url: type: string ownerUid: type: number required: - name - description - hidden - system - userTitle - icon - labelColor - slug - createtime - memberCount - private - cover:url - cover:position - userTitleEnabled - disableJoinRequests - disableLeave - nameEncoded - displayName - textColor - createtimeISO - cover:thumb:url yourid: type: number - $ref: components/schemas/Pagination.yaml#/Pagination - $ref: components/schemas/CommonProps.yaml#/CommonProps "/api/admin/manage/groups/{name}": get: tags: - admin summary: Get user group details parameters: - name: name in: path required: true schema: type: string example: administrators responses: "200": description: "" content: application/json: schema: allOf: - type: object properties: group: $ref: components/schemas/GroupObject.yaml#/GroupFullObject groupNames: type: array items: type: object properties: encodedName: type: string displayName: type: string selected: type: boolean allowPrivateGroups: type: number maximumGroupNameLength: type: number maximumGroupTitleLength: type: number - $ref: components/schemas/CommonProps.yaml#/CommonProps /api/admin/manage/uploads: get: tags: - admin summary: Get uploaded files parameters: - in: query name: dir schema: type: string description: Path of the folder, relative to `public/uploads/` example: / responses: "200": description: "A JSON object containing uploaded files" content: application/json: schema: allOf: - type: object properties: currentFolder: type: string description: Path of the folder, relative to `public/uploads/` showPids: type: boolean description: Whether or not the post identifiers should be shown (this is `true` only for `public/uploads/files/`, as that is where post uploads go) files: type: array items: type: object properties: name: type: string path: type: string description: Path relative to `currentFolder` url: type: string description: Relative URL ready to be combined with `config.relative_path` on the client-side or templates fileCount: type: number description: For directories, the number of files inside size: type: number description: The size of the file/directory sizeHumanReadable: type: string isDirectory: type: boolean isFile: type: boolean mtime: type: number description: Last modified time of the file, down to the microsecond (expressed as a UNIX timestamp) - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - $ref: components/schemas/Pagination.yaml#/Pagination - $ref: components/schemas/CommonProps.yaml#/CommonProps /api/admin/manage/digest: get: tags: - admin summary: Get system digest info/settings responses: "200": description: "A JSON object containing recent digest sends and settings" content: application/json: schema: allOf: - type: object properties: title: type: string delivery: type: array items: type: object properties: username: type: string description: A friendly name for a given user account picture: nullable: true type: string uid: type: number description: A user identifier icon:text: type: string description: A single-letter representation of a username. This is used in the auto-generated icon given to users without an avatar icon:bgColor: type: string description: A six-character hexadecimal colour code assigned to the user. This value is used in conjunction with `icon:text` for the user's auto-generated icon example: "#f44336" lastDelivery: type: string setting: type: boolean default: type: string required: - title - delivery - $ref: components/schemas/Pagination.yaml#/Pagination - $ref: components/schemas/CommonProps.yaml#/CommonProps "/api/admin/settings/{term}": get: tags: - admin summary: Get system settings parameters: - name: term in: path required: true schema: type: string example: general responses: "200": description: "" content: application/json: schema: allOf: - type: object properties: {} additionalProperties: type: object description: Most of the settings pages have their values loaded on the client-side, so the settings are not exposed server-side. - $ref: components/schemas/CommonProps.yaml#/CommonProps "/api/admin/appearance/{term}": get: tags: - admin summary: Get appearance settings parameters: - name: term in: path required: true schema: type: string example: themes responses: "200": description: "" content: application/json: schema: $ref: components/schemas/CommonProps.yaml#/CommonProps /api/admin/extend/plugins: get: tags: - admin summary: Get system plugin settings responses: "200": description: "" content: application/json: schema: allOf: - type: object properties: installed: type: array items: type: object properties: latest: type: string description: type: string name: type: string updated: type: string url: type: string numInstalls: type: number isCompatible: type: boolean id: type: string installed: type: boolean active: type: boolean isTheme: type: boolean error: type: boolean version: type: string license: type: object properties: name: type: string text: type: string nullable: true outdated: type: boolean settingsRoute: type: string required: - latest - description - name - id - installed - active - isTheme - error - version - license - outdated installedCount: type: number activeCount: type: number inactiveCount: type: number upgradeCount: type: number download: type: array items: type: object properties: name: type: string updated: type: string description: type: string latest: type: string url: type: string numInstalls: type: number isCompatible: type: boolean id: type: string installed: type: boolean active: type: boolean required: - name - updated - latest - url - numInstalls - isCompatible - id - installed - active incompatible: type: array items: type: object properties: latest: type: string description: type: string name: type: string updated: type: string url: type: string numInstalls: type: number isCompatible: type: boolean id: type: string installed: type: boolean active: type: boolean required: - name - updated - latest - url - numInstalls - isCompatible - id - installed - active submitPluginUsage: type: number version: type: string - $ref: components/schemas/CommonProps.yaml#/CommonProps /api/admin/extend/widgets: get: tags: - admin summary: Get widget settings responses: "200": description: "" content: application/json: schema: allOf: - type: object properties: templates: type: array items: type: object properties: template: type: string areas: type: array items: type: object properties: name: type: string location: type: string areas: type: array items: type: object properties: name: type: string template: type: string location: type: string data: type: array items: type: object properties: widget: type: string data: type: object properties: html: type: string cid: type: string title: type: string container: type: string groups: type: array items: {} groupsHideFrom: type: array items: {} hide-mobile: type: string numTags: type: string numUsers: type: string text: type: string parseAsPost: type: string numTopics: type: string availableWidgets: type: array items: type: object properties: widget: type: string name: type: string description: type: string content: type: string - $ref: components/schemas/CommonProps.yaml#/CommonProps /api/admin/extend/rewards: get: tags: - admin summary: Get rewards settings responses: "200": description: "A JSON object containing rewards and their settings" content: application/json: schema: allOf: - type: object properties: active: type: array items: type: object properties: condition: type: string conditional: type: string value: type: number rid: type: string claimable: type: string id: type: string disabled: type: boolean rewards: type: array items: additionalProperties: {} description: Reward-specific properties conditions: type: array items: type: object properties: name: type: string condition: type: string conditionals: type: array items: type: object properties: name: type: string conditional: type: string rewards: type: array items: type: object properties: rid: type: string name: type: string inputs: type: array items: type: object properties: type: type: string name: type: string label: type: string values: type: array items: type: object properties: name: type: string value: type: string - $ref: components/schemas/CommonProps.yaml#/CommonProps /api/admin/advanced/database: get: tags: - admin summary: Get database information responses: "200": description: "A JSON object with database status information" content: application/json: schema: properties: {} additionalProperties: type: object description: Each database configured will have an entry here with information about its runtime status /api/admin/advanced/events: get: tags: - admin summary: Get event log parameters: - in: query name: type schema: type: string description: Event name to filter by example: config-change - in: query name: start schema: type: string description: Start date to filter by example: '' - in: query name: end schema: type: string description: End date to filter by example: '' - in: query name: perPage schema: type: string description: Limit the number of events returned per page example: 20 responses: "200": description: "A JSON object containing " content: application/json: schema: allOf: - type: object properties: events: type: array items: type: object properties: type: type: string additionalProperties: description: Each individual event as added by core/plugins can append their own metadata related to the event - $ref: components/schemas/Pagination.yaml#/Pagination - type: object properties: types: type: array items: type: object properties: value: type: string name: type: string selected: type: boolean query: additionalProperties: description: An object containing the query string parameters, if any - $ref: components/schemas/CommonProps.yaml#/CommonProps /api/admin/advanced/hooks: get: tags: - admin summary: Get active plugin hooks responses: "200": description: "A JSON object containing all hooks with active listeners" content: application/json: schema: allOf: - type: object properties: hooks: type: array items: type: object properties: hookName: type: string description: The name of the hook (also the name used in code) methods: type: array items: type: object properties: id: type: string description: Plugin listening to this hook priority: type: number description: Priority level, lower priorities are executed earlier method: type: string description: Stringified method for examination index: type: string description: Internal counter used for DOM element ids index: type: string description: Internal counter used for DOM element ids count: type: number description: The number of listeners subscribed to this hook - $ref: components/schemas/CommonProps.yaml#/CommonProps /api/admin/advanced/logs: get: tags: - admin summary: Get server-side log output responses: "200": description: "A JSON object containing the server-side log" content: application/json: schema: allOf: - type: object properties: data: type: string description: Output of the server-side log file - $ref: components/schemas/CommonProps.yaml#/CommonProps /api/admin/advanced/errors: get: tags: - admin summary: Get server-side errors responses: "200": description: "A JSON object containing server-side errors" content: application/json: schema: allOf: - type: object properties: not-found: type: array items: type: object properties: value: type: string description: Path to the requested URL that returned a 404 score: type: number description: The number of times that URL was requested analytics: type: object properties: not-found: type: array description: 404 responses groups by day, from 6 days ago, to present day items: type: number toobusy: type: array description: 503 responses groups by day, from 6 days ago, to present day items: type: number - $ref: components/schemas/CommonProps.yaml#/CommonProps /api/admin/advanced/errors/export: get: tags: - admin summary: Export errors (.csv) responses: "200": description: "A CSV file containing server-side errors" content: text/csv: schema: type: string format: binary /api/admin/advanced/cache: get: tags: - admin summary: Get system cache info responses: "200": description: "" content: application/json: schema: allOf: - type: object properties: postCache: type: object properties: length: type: number max: type: number nullable: true itemCount: type: number percentFull: type: number avgPostSize: type: number hits: type: string misses: type: string hitRatio: type: string groupCache: type: object properties: length: type: number max: type: number itemCount: type: number percentFull: type: number hits: type: string misses: type: string hitRatio: type: string localCache: type: object properties: length: type: number max: type: number itemCount: type: number percentFull: type: number dump: type: boolean hits: type: string misses: type: string hitRatio: type: string objectCache: type: object properties: length: type: number max: type: number itemCount: type: number percentFull: type: number hits: type: string misses: type: string hitRatio: type: string required: - postCache - groupCache - localCache - $ref: components/schemas/CommonProps.yaml#/CommonProps /api/admin/development/logger: get: tags: - admin summary: Get system logger settings responses: "200": description: "" content: application/json: schema: $ref: components/schemas/CommonProps.yaml#/CommonProps /api/admin/development/info: get: tags: - admin summary: Get process/system information responses: "200": description: "A JSON object containing process and system information" content: application/json: schema: allOf: - type: object properties: info: type: array items: type: object properties: process: type: object properties: port: description: An array containing the port numbers configured to be used by NodeBB processes oneOf: - type: array items: oneOf: - type: string - type: number - type: string - type: number pid: type: number description: Process id title: type: number description: Executable version: type: number description: NodeBB version memoryUsage: type: object properties: rss: type: number heapTotal: type: number heapUsed: type: number external: type: number arrayBuffers: type: number humanReadable: type: number required: - rss - heapTotal - heapUsed - external - humanReadable uptime: type: number cpuUsage: type: object properties: user: type: string system: type: string os: type: object properties: hostname: type: string type: type: string platform: type: string arch: type: string release: type: string load: type: string description: CPU load git: type: object properties: hash: type: string branch: type: string stats: type: object properties: onlineGuestCount: type: number onlineRegisteredCount: type: number socketCount: type: number users: type: object properties: categories: type: number recent: type: number unread: type: number topics: type: number category: type: number topics: type: array id: type: string infoJSON: type: string description: "`info`, but stringified" host: type: string description: Server hostname port: description: An array containing the port numbers configured to be used by NodeBB processes oneOf: - type: array items: oneOf: - type: string - type: number - type: string - type: number nodeCount: type: number description: The number of NodeBB application processes currently running timeout: type: number ip: type: string loggedIn: type: boolean relative_path: type: string - $ref: components/schemas/CommonProps.yaml#/CommonProps /api/admin/users/csv: get: tags: - admin summary: Get users export (.csv) parameters: - in: header name: referer schema: type: string required: true example: /admin/manage/users responses: "200": description: "A CSV file containing all registered users" content: text/csv: schema: type: string format: binary /api/admin/analytics: get: tags: - admin summary: Get site analytics parameters: - in: query name: units schema: type: string enum: [hours, days] description: Whether to display dashboard data segmented daily or hourly example: days - in: query name: until schema: type: number description: A UNIX timestamp denoting the end of the analytics reporting period example: '' - in: query name: count schema: type: number description: The number of entries to return (e.g. if `units` is `hourly`, and `count` is `24`, the result set will contain 24 hours' worth of analytics) example: 20 responses: "200": description: "A JSON object containing analytics data" content: application/json: schema: type: object properties: query: additionalProperties: description: The query string passed in result: type: object properties: uniquevisitors: type: array items: type: number pageviews: type: array items: type: number pageviews:registered: type: array items: type: number pageviews:bot: type: array items: type: number pageviews:guest: type: array items: type: number /api/admin/category/uploadpicture: post: tags: - admin summary: Update category picture (via image upload) requestBody: required: true content: multipart/form-data: schema: type: object properties: cid: type: number description: Category identifier whose picture will be set after successful upload example: 1 files: type: array items: type: string format: binary required: - cid - files responses: "200": description: "Image uploaded" content: application/json: schema: type: object properties: name: type: string description: The filename url: type: string description: URL of the uploaded image for use client-side /api/admin/uploadfavicon: post: tags: - admin summary: Upload favicon requestBody: required: true content: multipart/form-data: schema: type: object properties: files: type: array items: type: string format: binary required: - files responses: "200": description: "Image uploaded" content: application/json: schema: type: object properties: name: type: string description: The filename url: type: string description: URL of the uploaded image for use client-side /api/admin/uploadTouchIcon: post: tags: - admin summary: Upload Touch Icon requestBody: required: true content: multipart/form-data: schema: type: object properties: files: type: array items: type: string format: binary required: - files responses: "200": description: "Image uploaded" content: application/json: schema: type: object properties: name: type: string description: The filename url: type: string description: URL of the uploaded image for use client-side /api/admin/uploadlogo: post: tags: - admin summary: Upload site logo requestBody: required: true content: multipart/form-data: schema: type: object properties: files: type: array items: type: string format: binary required: - files responses: "200": description: "Image uploaded" content: application/json: schema: type: object properties: name: type: string description: The filename url: type: string description: URL of the uploaded image for use client-side /api/admin/uploadOgImage: post: tags: - admin summary: Upload site-wide Open Graph Image requestBody: required: true content: multipart/form-data: schema: type: object properties: files: type: array items: type: string format: binary required: - files responses: "200": description: "Image uploaded" content: application/json: schema: type: object properties: name: type: string description: The filename url: type: string description: URL of the uploaded image for use client-side /api/admin/upload/sound: post: tags: - admin summary: Upload sound file requestBody: required: true content: multipart/form-data: schema: type: object properties: files: type: array items: type: string format: binary required: - files responses: "200": description: "Sound uploaded" content: application/json: schema: type: object properties: {} /api/admin/upload/file: post: tags: - admin summary: Upload a file requestBody: required: true content: multipart/form-data: schema: type: object properties: folder: type: string description: The folder to upload the files to (relative to `public/uploads/`) files: type: array items: type: string format: binary required: - files responses: "200": description: "File uploaded" content: application/json: schema: type: object properties: name: type: string description: The filename url: type: string description: URL of the uploaded file for use client-side /api/admin/uploadDefaultAvatar: post: tags: - admin summary: Upload default avatar requestBody: required: true content: multipart/form-data: schema: type: object properties: files: type: array items: type: string format: binary required: - files responses: "200": description: "Image uploaded" content: application/json: schema: type: object properties: name: type: string description: The filename url: type: string description: URL of the uploaded image for use client-side /api/config: get: tags: - home summary: Get forum settings description: This route retrieves forum settings and user-specific settings for client-side options on the forum. responses: "200": description: "" content: application/json: schema: type: object properties: relative_path: type: string upload_url: type: string siteTitle: type: string browserTitle: type: string titleLayout: type: string showSiteTitle: type: boolean minimumTitleLength: type: number maximumTitleLength: type: number minimumPostLength: type: number maximumPostLength: type: number minimumTagsPerTopic: type: number maximumTagsPerTopic: type: number minimumTagLength: type: number maximumTagLength: type: number useOutgoingLinksPage: type: boolean allowGuestHandles: type: boolean allowTopicsThumbnail: type: boolean usePagination: type: boolean disableChat: type: boolean disableChatMessageEditing: type: boolean maximumChatMessageLength: type: number socketioTransports: type: array items: type: string socketioOrigins: type: string websocketAddress: type: string maxReconnectionAttempts: type: number reconnectionDelay: type: number topicsPerPage: type: number postsPerPage: type: number maximumFileSize: type: number theme:id: type: string theme:src: type: string defaultLang: type: string userLang: type: string loggedIn: type: boolean uid: type: number description: A user identifier cache-buster: type: string requireEmailConfirmation: type: boolean topicPostSort: type: string categoryTopicSort: type: string csrf_token: type: string searchEnabled: type: boolean bootswatchSkin: type: string enablePostHistory: type: boolean notificationAlertTimeout: type: number timeagoCutoff: type: number timeagoCodes: type: array items: type: string cookies: type: object properties: enabled: type: boolean message: type: string dismiss: type: string link: type: string link_url: type: string acpLang: type: string openOutgoingLinksInNewTab: type: boolean topicSearchEnabled: type: boolean hideSubCategories: type: boolean hideCategoryLastPost: type: boolean enableQuickReply: type: boolean /api/users: get: tags: - users summary: Get users parameters: - in: query name: section schema: type: string enum: ['joindate', 'online', 'sort-posts', 'sort-reputation', 'banned', 'flagged'] required: false description: Allows filtering of the user list via pre-defined sections example: 'joindate' - in: query name: term schema: type: string required: false description: Allows for searching of user list example: '' responses: "200": description: "" content: application/json: schema: allOf: - type: object properties: users: type: array items: type: object properties: uid: type: number description: A user identifier username: type: string description: A friendly name for a given user account userslug: type: string description: An URL-safe variant of the username (i.e. lower-cased, spaces removed, etc.) picture: nullable: true type: string status: type: string postcount: type: number reputation: type: number email:confirmed: type: number description: Whether the user has confirmed their email address or not lastonline: type: number flags: nullable: true banned: type: number banned:expire: type: number joindate: type: number description: A UNIX timestamp representing the moment the user's account was created icon:text: type: string description: A single-letter representation of a username. This is used in the auto-generated icon given to users without an avatar icon:bgColor: type: string description: A six-character hexadecimal colour code assigned to the user. This value is used in conjunction with `icon:text` for the user's auto-generated icon example: "#f44336" joindateISO: type: string lastonlineISO: type: string banned_until: type: number banned_until_readable: type: string administrator: type: boolean userCount: type: number title: type: string isAdminOrGlobalMod: type: boolean isAdmin: type: boolean isGlobalMod: type: boolean displayUserSearch: type: boolean section_joindate: type: boolean maximumInvites: type: number inviteOnly: type: boolean adminInviteOnly: type: boolean invites: type: number showInviteButton: type: boolean reputation:disabled: type: number - $ref: components/schemas/Pagination.yaml#/Pagination - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - $ref: components/schemas/CommonProps.yaml#/CommonProps "/api/user/uid/{uid}": get: tags: - users summary: Get user by uid description: This route retrieves a user's public profile data. If the calling user is the same as the profile, then it will also return data the user elected to hide (e.g. email/fullname) parameters: - name: uid in: path required: true schema: type: string example: 1 responses: "200": description: "" content: application/json: schema: $ref: components/schemas/UserObject.yaml#/UserObject "/api/user/username/{username}": get: tags: - users summary: Get user by username description: This route retrieves a user's public profile data. If the calling user is the same as the profile, then it will also return data the user elected to hide (e.g. email/fullname) parameters: - name: username in: path required: true schema: type: string example: admin responses: "200": description: "" content: application/json: schema: $ref: components/schemas/UserObject.yaml#/UserObject "/api/user/email/{email}": get: tags: - users summary: Get user by email description: This route retrieves a user's public profile data. If the calling user is the same as the profile, then it will also return data the user elected to hide (e.g. email/fullname) parameters: - name: email in: path required: true schema: type: string example: 'test@example.org' responses: "200": description: "" content: application/json: schema: $ref: components/schemas/UserObject.yaml#/UserObject "/api/user/uid/{userslug}/export/posts": get: tags: - users summary: Export a user's posts (.csv) parameters: - name: userslug in: path required: true schema: type: string example: admin responses: "200": description: "A CSV file containing a user's posts" content: text/csv: schema: type: string format: binary "/api/user/uid/{userslug}/export/uploads": get: tags: - users summary: Export a user's uploads (.zip) parameters: - name: userslug in: path required: true schema: type: string example: admin responses: "200": description: Successful export of user uploads content: application/zip: schema: type: string format: binary "/api/user/uid/{userslug}/export/profile": get: tags: - users summary: Export a user's profile data (.csv) parameters: - name: userslug in: path required: true schema: type: string example: admin responses: "200": description: "A CSV file containing the user profile" content: text/csv: schema: type: string format: binary "/api/post/pid/{id}": get: tags: - shorthand summary: Get post data parameters: - name: id in: path required: true schema: type: number example: 1 responses: "200": description: "A JSON object containing post data" content: application/json: schema: type: object properties: uid: type: number tid: type: number timestamp: type: number content: type: string pid: type: number downvotes: type: number upvotes: type: number deleted: type: number deleterUid: type: number edited: type: number votes: type: number timestampISO: type: string editedISO: type: string upvoted: type: boolean downvoted: type: boolean "/api/topic/tid/{id}": get: tags: - shorthand summary: Get topic data parameters: - name: id in: path required: true schema: type: string example: 1 responses: "200": description: "A JSON object containing topic data" content: application/json: schema: type: object properties: tid: type: number uid: type: number cid: type: number mainPid: type: number teaserPid: type: number nullable: true title: type: string slug: type: string timestamp: type: number lastposttime: type: number postcount: type: number viewcount: type: number deleted: type: number locked: type: number pinned: type: number upvotes: type: number downvotes: type: number deleterUid: type: number titleRaw: type: string timestampISO: type: string lastposttimeISO: type: string votes: type: number "/api/category/cid/{id}": get: tags: - shorthand summary: Get category data parameters: - name: id in: path required: true schema: type: string example: 1 responses: "200": description: "A JSON object containing topic data" content: application/json: schema: type: object properties: cid: type: number name: type: number description: type: string descriptionParsed: type: string icon: type: string bgColor: type: string color: type: string slug: type: string parentCid: type: number topic_count: type: number post_count: type: number disabled: type: number order: type: number link: type: string numRecentReplies: type: number class: type: string imageClass: type: string isSection: type: number totalPostCount: type: number totalTopicCount: type: number /api/categories: get: tags: - categories summary: Get a list of categories description: > This route retrieve the list of categories currently available to the accessing user. It doesn't necessarily mean that the user can *enter* the category, as that is a separate privilege. Specifically, this route will return all categories that grant the calling user the "Find Category" privilege. Subcategories are also returned, nested under a category's `children` property. responses: "200": description: A list of category objectscurrently available to the accessing user content: application/json: schema: allOf: - type: object properties: title: description: The page title type: string categories: description: A collection of category data objects type: array items: allOf: - $ref: components/schemas/CategoryObject.yaml#/CategoryObject - type: object properties: tagWhitelist: type: array items: type: string unread-class: type: string children: type: array items: allOf: - $ref: components/schemas/CategoryObject.yaml#/CategoryObject - type: object properties: tagWhitelist: type: array items: type: string unread-class: type: string children: type: array items: $ref: components/schemas/CategoryObject.yaml#/CategoryObject parent: allOf: - $ref: components/schemas/CategoryObject.yaml#/CategoryObject - type: object properties: tagWhitelist: type: array items: type: string unread-class: type: string posts: type: array items: type: object properties: pid: type: number timestamp: type: number content: type: string timestampISO: type: string description: An ISO 8601 formatted date string (complementing `timestamp`) user: type: object properties: uid: type: number description: A user identifier username: type: string description: A friendly name for a given user account userslug: type: string description: An URL-safe variant of the username (i.e. lower-cased, spaces removed, etc.) picture: nullable: true type: string icon:text: type: string description: A single-letter representation of a username. This is used in the auto-generated icon given to users without an avatar icon:bgColor: type: string description: A six-character hexadecimal colour code assigned to the user. This value is used in conjunction with `icon:text` for the user's auto-generated icon example: "#f44336" index: type: number cid: type: number description: A category identifier parentCid: type: number description: The category identifier for the category that is the immediate ancestor of the current category topic: type: object properties: slug: type: string title: type: string imageClass: type: string timesClicked: type: number posts: type: array items: type: object properties: pid: type: number timestamp: type: number content: type: string timestampISO: type: string description: An ISO 8601 formatted date string (complementing `timestamp`) user: type: object properties: uid: type: number description: A user identifier username: type: string description: A friendly name for a given user account userslug: type: string description: An URL-safe variant of the username (i.e. lower-cased, spaces removed, etc.) picture: nullable: true type: string icon:text: type: string description: A single-letter representation of a username. This is used in the auto-generated icon given to users without an avatar icon:bgColor: type: string description: A six-character hexadecimal colour code assigned to the user. This value is used in conjunction with `icon:text` for the user's auto-generated icon example: "#f44336" index: type: number cid: type: number description: A category identifier parentCid: type: number description: The category identifier for the category that is the immediate ancestor of the current category topic: type: object properties: slug: type: string title: type: string teaser: type: object properties: url: type: string timestampISO: type: string description: An ISO 8601 formatted date string (complementing `timestamp`) pid: type: number topic: type: object properties: slug: type: string title: type: string imageClass: type: string - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - $ref: components/schemas/CommonProps.yaml#/CommonProps "/api/categories/{cid}/moderators": get: tags: - categories summary: Get mods for a category description: > This route returns an array of uids that correspond to the moderators for the category in question. parameters: - name: cid description: The category identifier for the category you wish to look up in: path required: true schema: type: number example: 1 responses: "200": description: An array of moderators for the requested category content: application/json: schema: type: object properties: moderators: type: array example: moderators: - 1 - 2 - 3 "/api/topic/{topic_id}/{slug}/{post_index}": get: tags: - topics summary: Get topic data parameters: - name: topic_id in: path required: true schema: type: string example: 1 - name: slug description: This parameter is not required. If omitted, the request will be automatically redirected with the proper topic slug. in: path required: true schema: type: string example: test-topic - name: post_index description: This parameter is not required. If omitted, the request will presume that you want the first post. The API response is largely unaffected by this parameter, it is used client-side (to send the user to the requested post), and changes the meta/link tags in the server-side generated HTML. in: path required: true schema: type: string example: 1 responses: "200": description: "" content: application/json: schema: allOf: - type: object properties: tid: type: number description: A topic identifier uid: type: number description: A user identifier cid: type: number description: A category identifier title: type: string slug: type: string timestamp: type: number lastposttime: type: number postcount: type: number viewcount: type: number mainPid: type: number description: The post id of the first post in this topic (also called the "original post") teaserPid: type: number nullable: true upvotes: type: number downvotes: type: number deleted: type: number locked: type: number pinned: type: number description: Whether or not this particular topic is pinned to the top of the category deleterUid: type: number titleRaw: type: string timestampISO: type: string description: An ISO 8601 formatted date string (complementing `timestamp`) lastposttimeISO: type: string votes: type: number tags: type: array items: type: object properties: value: type: string valueEscaped: type: string color: type: string bgColor: type: string score: type: number posts: type: array items: type: object properties: pid: type: number uid: type: number description: A user identifier tid: type: number description: A topic identifier content: type: string timestamp: type: number votes: type: number deleted: type: number upvotes: type: number downvotes: type: number deleterUid: type: number edited: type: number timestampISO: type: string description: An ISO 8601 formatted date string (complementing `timestamp`) editedISO: type: string index: type: number user: type: object properties: uid: type: number description: A user identifier username: type: string description: A friendly name for a given user account userslug: type: string description: An URL-safe variant of the username (i.e. lower-cased, spaces removed, etc.) reputation: type: number postcount: type: number topiccount: type: number picture: type: string nullable: true signature: type: string banned: type: number banned:expire: type: number status: type: string lastonline: type: number groupTitle: nullable: true type: string groupTitleArray: type: array items: type: string icon:text: type: string description: A single-letter representation of a username. This is used in the auto-generated icon given to users without an avatar icon:bgColor: type: string description: A six-character hexadecimal colour code assigned to the user. This value is used in conjunction with `icon:text` for the user's auto-generated icon example: "#f44336" lastonlineISO: type: string banned_until: type: number banned_until_readable: type: string selectedGroups: type: array items: type: object properties: name: type: string slug: type: string labelColor: type: string textColor: type: string icon: type: string userTitle: type: string custom_profile_info: type: array items: type: object properties: content: type: string description: HTML that is injected into `topic.tpl` of themes that support custom profile info editor: nullable: true bookmarked: type: boolean upvoted: type: boolean downvoted: type: boolean replies: type: object properties: hasMore: type: boolean users: type: array items: type: object properties: username: type: string description: A friendly name for a given user account userslug: type: string description: An URL-safe variant of the username (i.e. lower-cased, spaces removed, etc.) picture: type: string uid: type: number description: A user identifier icon:text: type: string description: A single-letter representation of a username. This is used in the auto-generated icon given to users without an avatar icon:bgColor: type: string description: A six-character hexadecimal colour code assigned to the user. This value is used in conjunction with `icon:text` for the user's auto-generated icon example: "#f44336" administrator: type: boolean text: type: string count: type: number selfPost: type: boolean display_edit_tools: type: boolean display_delete_tools: type: boolean display_moderator_tools: type: boolean display_move_tools: type: boolean display_post_menu: type: boolean category: $ref: components/schemas/CategoryObject.yaml#/CategoryObject tagWhitelist: type: array items: type: string thread_tools: type: array items: type: object properties: class: type: string title: type: string icon: type: string isFollowing: type: boolean isNotFollowing: type: boolean isIgnoring: type: boolean bookmark: nullable: true postSharing: type: array items: type: object properties: id: type: string name: type: string class: type: string activated: type: boolean deleter: nullable: true merger: nullable: true related: type: array items: $ref: components/schemas/TopicObject.yaml#/TopicObject unreplied: type: boolean icons: type: array items: type: string description: HTML that is rendered by the theme privileges: type: object properties: topics:reply: type: boolean topics:read: type: boolean topics:tag: type: boolean topics:delete: type: boolean posts:edit: type: boolean posts:history: type: boolean posts:delete: type: boolean posts:view_deleted: type: boolean read: type: boolean purge: type: boolean view_thread_tools: type: boolean editable: type: boolean deletable: type: boolean view_deleted: type: boolean isAdminOrMod: type: boolean disabled: type: number tid: type: string uid: type: number description: A user identifier topicStaleDays: type: number reputation:disabled: type: number downvote:disabled: type: number feeds:disableRSS: type: number bookmarkThreshold: type: number necroThreshold: type: number postEditDuration: type: number postDeleteDuration: type: number scrollToMyPost: type: boolean allowMultipleBadges: type: boolean privateUploads: type: boolean rssFeedUrl: type: string postIndex: type: number loggedInUser: $ref: components/schemas/UserObject.yaml#/UserObject - $ref: components/schemas/Pagination.yaml#/Pagination - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - $ref: components/schemas/CommonProps.yaml#/CommonProps /api/recent: get: tags: - topics summary: Get recent topics description: Returns a list of topics sorted by timestamp. responses: "200": description: An array of topic objects sorted by timestamp. content: application/json: schema: allOf: - type: object properties: nextStart: type: number topicCount: type: number topics: type: array items: $ref: components/schemas/TopicObject.yaml#/TopicObject tids: type: array items: type: number canPost: type: boolean categories: type: array items: type: object properties: cid: type: number description: A category identifier name: type: string level: type: string icon: type: string parentCid: type: number description: The category identifier for the category that is the immediate ancestor of the current category color: type: string bgColor: type: string selected: type: boolean imageClass: type: string allCategoriesUrl: type: string selectedCategory: type: object properties: icon: type: string name: type: string bgColor: type: string nullable: true selectedCids: type: array items: type: number feeds:disableRSS: type: number rssFeedUrl: type: string title: type: string filters: type: array items: type: object properties: name: type: string url: type: string selected: type: boolean filter: type: string selectedFilter: type: object properties: name: type: string url: type: string selected: type: boolean filter: type: string terms: type: array items: type: object properties: name: type: string url: type: string selected: type: boolean term: type: string selectedTerm: type: object properties: name: type: string url: type: string selected: type: boolean term: type: string - $ref: components/schemas/Pagination.yaml#/Pagination - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - $ref: components/schemas/CommonProps.yaml#/CommonProps "/api/recent/posts/{term}": get: tags: - posts summary: Get recent posts parameters: - name: term in: path required: true schema: type: string example: daily responses: "200": description: "" content: application/json: schema: $ref: components/schemas/PostsObject.yaml#/PostsObject /api/unread: get: tags: - topics summary: Get unread topics description: Returns a list of the current user's unread topics, sorted by the last post's timestamp. responses: "200": description: An array of unread topic objects sorted by the last post's timestamp. content: application/json: schema: allOf: - type: object properties: showSelect: type: boolean nextStart: type: number topics: type: array items: type: object properties: tid: type: number description: A topic identifier uid: type: number description: A user identifier cid: type: number description: A category identifier mainPid: type: number description: The post id of the first post in this topic (also called the "original post") title: type: string slug: type: string timestamp: type: number lastposttime: type: number postcount: type: number viewcount: type: number teaserPid: type: number upvotes: type: number downvotes: type: number deleted: type: number locked: type: number pinned: type: number description: Whether or not this particular topic is pinned to the top of the category titleRaw: type: string timestampISO: type: string description: An ISO 8601 formatted date string (complementing `timestamp`) lastposttimeISO: type: string votes: type: number category: type: object properties: cid: type: number description: A category identifier name: type: string slug: type: string icon: type: string image: nullable: true imageClass: nullable: true type: string bgColor: type: string color: type: string disabled: type: number user: type: object properties: uid: type: number description: A user identifier username: type: string description: A friendly name for a given user account fullname: type: string userslug: type: string description: An URL-safe variant of the username (i.e. lower-cased, spaces removed, etc.) reputation: type: number postcount: type: number picture: nullable: true type: string signature: nullable: true type: string banned: type: number status: type: string icon:text: type: string description: A single-letter representation of a username. This is used in the auto-generated icon given to users without an avatar icon:bgColor: type: string description: A six-character hexadecimal colour code assigned to the user. This value is used in conjunction with `icon:text` for the user's auto-generated icon example: "#f44336" banned_until_readable: type: string teaser: type: object properties: pid: type: number uid: type: number description: A user identifier timestamp: type: number tid: type: number description: A topic identifier content: type: string timestampISO: type: string description: An ISO 8601 formatted date string (complementing `timestamp`) user: type: object properties: uid: type: number description: A user identifier username: type: string description: A friendly name for a given user account userslug: type: string description: An URL-safe variant of the username (i.e. lower-cased, spaces removed, etc.) picture: nullable: true type: string icon:text: type: string description: A single-letter representation of a username. This is used in the auto-generated icon given to users without an avatar icon:bgColor: type: string description: A six-character hexadecimal colour code assigned to the user. This value is used in conjunction with `icon:text` for the user's auto-generated icon example: "#f44336" index: type: number tags: type: array items: type: object properties: value: type: string valueEscaped: type: string color: type: string bgColor: type: string score: type: number isOwner: type: boolean ignored: type: boolean unread: type: boolean bookmark: nullable: true unreplied: type: boolean icons: type: array items: type: string index: type: number isQuestion: nullable: true topicCount: type: number title: type: string pageCount: type: number categories: type: array items: type: object properties: cid: type: number description: A category identifier name: type: string level: type: string icon: type: string parentCid: type: number description: The category identifier for the category that is the immediate ancestor of the current category color: type: string bgColor: type: string selected: type: boolean imageClass: type: string allCategoriesUrl: type: string selectedCids: type: array items: type: number filters: type: array items: type: object properties: name: type: string url: type: string selected: type: boolean filter: type: string selectedFilter: type: object properties: name: type: string url: type: string selected: type: boolean filter: type: string - $ref: components/schemas/Pagination.yaml#/Pagination - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - $ref: components/schemas/CommonProps.yaml#/CommonProps /api/unread/total: get: tags: - topics summary: Get number of unread topics responses: "200": description: "Success" content: text/plain: schema: type: number "/api/topic/teaser/{topic_id}": get: tags: - topics summary: Get a topic's teaser post parameters: - name: topic_id in: path required: true schema: type: string example: 1 responses: "200": description: "A JSON object containing the teaser post for a topic" content: application/json: schema: $ref: components/schemas/PostsObject.yaml#/PostsObject "/api/topic/pagination/{topic_id}": get: tags: - topics summary: Get topic pagination data description: This route retrieves pagination data for a given topic. It is used mainly client-side, as it return data necessary to update a pagination block client-side. parameters: - name: topic_id in: path required: true schema: type: string example: 1 responses: "200": description: "" content: application/json: schema: $ref: components/schemas/Pagination.yaml#/Pagination /api/post/upload: post: tags: - posts summary: Upload a file to a specific post description: Provided by NodeBB core and used mainly by the composer, this route allows you to upload an image or file to a post. responses: "200": description: "" content: application/json: schema: type: array items: type: object properties: name: type: string url: type: string text/plain: schema: type: array items: type: object properties: name: type: string url: type: string "403": description: "" content: application/json: schema: type: string example: Forbidden text/plain: schema: type: string example: Forbidden "500": description: "" content: application/json: schema: type: object properties: path: type: string error: type: string text/plain: schema: type: object properties: path: type: string error: type: string /api/topic/thumb/upload: post: tags: - topics summary: Upload topic thumb requestBody: required: true content: multipart/form-data: schema: type: object properties: files: type: array items: type: string format: binary required: - files responses: "200": description: "Image uploaded" content: application/json: schema: type: object properties: name: type: string description: The filename url: type: string description: URL of the uploaded image for use client-side path: type: string description: Path to the file in the local file system /api/login: get: tags: - authentication summary: /api/login responses: "200": description: "" content: application/json: schema: allOf: - type: object properties: loginFormEntry: type: array items: type: object properties: label: type: string description: A label for the added block html: type: string description: HTML to render on the login page styleName: type: string description: Custom identifier (value is added to `input[id]` and `label[for]`) alternate_logins: type: boolean authentication: type: array items: type: object properties: name: type: string url: type: string callbackURL: type: string icon: type: string scope: type: string prompt: type: string allowRegistration: type: boolean allowLoginWith: type: string title: type: string allowPasswordReset: type: boolean allowLocalLogin: type: boolean - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - $ref: components/schemas/CommonProps.yaml#/CommonProps /api/register: get: tags: - authentication summary: /api/register responses: "200": description: "" content: application/json: schema: allOf: - type: object properties: register_window:spansize: type: string alternate_logins: type: boolean authentication: type: array items: type: object properties: name: type: string url: type: string callbackURL: type: string icon: type: string scope: type: string prompt: type: string minimumUsernameLength: type: number maximumUsernameLength: type: number minimumPasswordLength: type: number minimumPasswordStrength: type: number regFormEntry: type: array items: type: object properties: label: type: string html: type: string styleName: type: string title: type: string - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - $ref: components/schemas/CommonProps.yaml#/CommonProps # /api/register/complete: # get: # tags: # - authentication # summary: /api/register/complete # responses: # "200": # description: "" # content: # application/json: # schema: # allOf: # - type: object # properties: # title: # type: string # errors: # type: array # items: {} # sections: # type: array # items: # type: string # - $ref: components/schemas/CommonProps.yaml#/CommonProps /api/search: get: tags: - search summary: Get search results responses: "200": description: "" content: application/json: schema: allOf: - type: object properties: posts: $ref: components/schemas/PostsObject.yaml#/PostsObject matchCount: type: number pageCount: type: number time: type: string multiplePages: type: boolean search_query: type: string term: type: string categories: type: array items: type: object properties: value: oneOf: - type: string - type: number text: type: string categoriesCount: type: number expandSearch: type: boolean showAsPosts: type: boolean showAsTopics: type: boolean title: type: string searchDefaultSortBy: type: string required: - posts - matchCount - pageCount - time - multiplePages - search_query - categories - categoriesCount - expandSearch - showAsPosts - showAsTopics - title - searchDefaultSortBy - $ref: components/schemas/Pagination.yaml#/Pagination - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - $ref: components/schemas/CommonProps.yaml#/CommonProps "/api/reset": get: tags: - authentication summary: Get user password reset (step 1) responses: "200": description: "A JSON object containing the 1st step of the user password reset flow" content: application/json: schema: allOf: - type: object properties: code: type: string nullable: true title: type: string - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - $ref: components/schemas/CommonProps.yaml#/CommonProps "/api/reset/{code}": get: tags: - authentication summary: Get user password reset (step 2) parameters: - name: code in: path required: true schema: type: string example: testCode responses: "200": description: "A JSON object containing the 2nd step of the user password reset flow" content: application/json: schema: allOf: - type: object properties: valid: type: boolean code: type: string minimumPasswordLength: type: number minimumPasswordStrength: type: number title: type: string - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - $ref: components/schemas/CommonProps.yaml#/CommonProps "/api/email/unsubscribe/{token}": # TODO: Need GET route here as well post: tags: - emails summary: Unsubscribe user from email type parameters: - name: token in: path required: true schema: type: string example: testToken responses: "200": description: "Successfully unsubscribed" "500": description: "Server-side error (likely token verification failure)" "/api/post/{pid}": get: tags: - shorthand summary: Access a specific post description: This route comes in handy when all you have is the `pid`, and you want to redirect users to the canonical URL for the topic, with the appropriate topic slug and post index. parameters: - name: pid in: path required: true schema: type: string example: 1 responses: "200": description: "Canonical URL of topic" content: text/plain: schema: type: string /api/flags: get: tags: - flags summary: Get flags list responses: "200": description: "" content: application/json: schema: allOf: - type: object properties: flags: type: array items: type: object properties: state: type: string flagId: type: number type: type: string targetId: oneOf: - type: string - type: number description: type: string uid: type: number description: A user identifier datetime: type: number reporter: type: object properties: username: type: string description: A friendly name for a given user account picture: nullable: true type: string icon:bgColor: type: string description: A six-character hexadecimal colour code assigned to the user. This value is used in conjunction with `icon:text` for the user's auto-generated icon example: "#f44336" icon:text: type: string description: A single-letter representation of a username. This is used in the auto-generated icon given to users without an avatar labelClass: type: string target_readable: type: string datetimeISO: type: string assignee: type: string nullable: true analytics: type: array items: type: number categories: type: object properties: {} additionalProperties: type: string description: All categories will be listed here, with the `cid` as the key, and the category name as the value hasFilter: type: boolean filters: type: object properties: page: type: number perPage: type: number title: type: string - $ref: components/schemas/Pagination.yaml#/Pagination - $ref: components/schemas/CommonProps.yaml#/CommonProps "/api/flags/{flagId}": get: tags: - flags summary: /api/flags/{flagId} parameters: - name: flagId in: path required: true schema: type: string example: 1 responses: "200": description: "" content: application/json: schema: allOf: - type: object properties: state: type: string flagId: type: number type: type: string targetId: type: number description: type: string uid: type: number description: A user identifier datetime: type: number datetimeISO: type: string target_readable: type: string target: type: object properties: {} additionalProperties: description: Properties change depending on the target type (user, post, etc.) assignee: type: number nullable: true filters: type: object properties: page: type: number perPage: type: number history: type: array items: type: object properties: uid: type: number description: A user identifier fields: type: object additionalProperties: {} meta: type: array items: type: object properties: key: type: string value: type: string labelClass: type: string enum: ['default', 'primary', 'success', 'info', 'danger'] required: - key datetime: type: number datetimeISO: type: string user: type: object properties: username: type: string description: A friendly name for a given user account userslug: type: string description: An URL-safe variant of the username (i.e. lower-cased, spaces removed, etc.) picture: nullable: true uid: type: number description: A user identifier icon:text: type: string description: A single-letter representation of a username. This is used in the auto-generated icon given to users without an avatar icon:bgColor: type: string description: A six-character hexadecimal colour code assigned to the user. This value is used in conjunction with `icon:text` for the user's auto-generated icon example: "#f44336" required: - uid - datetime - datetimeISO - user notes: type: array items: type: object properties: uid: type: number content: type: string datetime: type: number datetimeISO: type: string user: type: object properties: username: type: string description: A friendly name for a given user account userslug: type: string description: An URL-safe variant of the username (i.e. lower-cased, spaces removed, etc.) picture: type: string uid: type: number description: A user identifier icon:text: type: string description: A single-letter representation of a username. This is used in the auto-generated icon given to users without an avatar icon:bgColor: type: string description: A six-character hexadecimal colour code assigned to the user. This value is used in conjunction with `icon:text` for the user's auto-generated icon example: "#f44336" reporter: type: object properties: username: type: string description: A friendly name for a given user account userslug: type: string description: An URL-safe variant of the username (i.e. lower-cased, spaces removed, etc.) picture: nullable: true reputation: type: number uid: type: number description: A user identifier icon:text: type: string description: A single-letter representation of a username. This is used in the auto-generated icon given to users without an avatar icon:bgColor: type: string description: A six-character hexadecimal colour code assigned to the user. This value is used in conjunction with `icon:text` for the user's auto-generated icon example: "#f44336" type_path: type: string assignees: type: array items: $ref: components/schemas/UserObject.yaml#/UserObject type_bool: type: object properties: post: type: boolean user: type: boolean empty: type: boolean title: type: string categories: type: object additionalProperties: type: string - $ref: components/schemas/CommonProps.yaml#/CommonProps /api/post-queue: get: tags: - admin summary: Get flag data responses: "200": description: "" content: application/json: schema: allOf: - type: object properties: title: type: string posts: type: array items: allOf: - type: object properties: id: type: string uid: type: number description: A user identifier type: type: string data: type: object properties: title: type: string content: type: string thumb: type: string cid: oneOf: - type: number - type: string tags: type: array items: {} uid: type: number description: A user identifier req: type: object properties: uid: type: number description: A user identifier ip: type: string host: type: string protocol: type: string secure: type: boolean url: type: string path: type: string headers: type: object properties: x-real-ip: type: string x-forwarded-for: type: string x-forwarded-proto: type: string host: type: string x-nginx-proxy: type: string connection: type: string accept: type: string user-agent: type: string sec-fetch-site: type: string sec-fetch-mode: type: string referer: type: string accept-encoding: type: string accept-language: type: string cookie: type: string timestamp: type: number fromQueue: type: boolean timestampISO: type: string description: An ISO 8601 formatted date string (complementing `timestamp`) rawContent: type: string tid: type: number description: A topic identifier toPid: nullable: true user: type: object properties: username: type: string description: A friendly name for a given user account userslug: type: string description: An URL-safe variant of the username (i.e. lower-cased, spaces removed, etc.) picture: nullable: true type: string uid: type: number description: A user identifier icon:text: type: string description: A single-letter representation of a username. This is used in the auto-generated icon given to users without an avatar icon:bgColor: type: string description: A six-character hexadecimal colour code assigned to the user. This value is used in conjunction with `icon:text` for the user's auto-generated icon example: "#f44336" topic: type: object properties: cid: type: number title: type: string titleRaw: type: string - $ref: components/schemas/CategoryObject.yaml#/CategoryObject - $ref: components/schemas/Pagination.yaml#/Pagination - $ref: components/schemas/CommonProps.yaml#/CommonProps /api/ip-blacklist: get: tags: - admin summary: Get IP blacklist settings responses: "418": description: "TODO: A proper response needs to be added. It is not really a teapot | Copy response from corresponding admin route" /api/registration-queue: get: tags: - admin summary: Get registration queue responses: "418": description: "TODO: A proper response needs to be added. It is not really a teapot | Copy response from corresponding admin route" /api/tags: get: tags: - tags summary: Get tags description: Returns a list of tags sorted by the most topics responses: "200": description: "" content: application/json: schema: allOf: - type: object properties: tags: type: array description: An array of tags sorted by the most topics items: type: object properties: value: type: string description: The raw tag score: type: number description: Number of topics tagged by this tag valueEscaped: type: string description: This is the escaped tag value, equal to validator.escape(value) color: type: string bgColor: type: string displayTagSearch: type: boolean nextStart: type: number title: type: string - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - $ref: components/schemas/CommonProps.yaml#/CommonProps "/api/tags/{tag}": get: tags: - tags summary: Get tag data description: Returns a list of topics that are tagged with {tag} parameters: - name: tag description: The tag used to retrieve the topics in: path required: true schema: type: string example: test - name: page description: Page number used in pagination in: query required: false schema: type: number example: '' responses: "200": description: "" content: application/json: schema: allOf: - type: object properties: topics: type: array description: An array of topics that are all tagged with {tag} items: type: object properties: tid: type: number description: A topic identifier uid: type: number description: A user identifier cid: type: number description: A category identifier mainPid: type: number description: The post id of the first post in this topic (also called the "original post") title: type: string slug: type: string timestamp: type: number lastposttime: type: number postcount: type: number viewcount: type: number teaserPid: oneOf: - type: number - type: string deleted: type: number locked: type: number pinned: type: number description: Whether or not this particular topic is pinned to the top of the category upvotes: type: number downvotes: type: number titleRaw: type: string timestampISO: type: string description: An ISO 8601 formatted date string (complementing `timestamp`) lastposttimeISO: type: string votes: type: number category: type: object properties: cid: type: number description: A category identifier name: type: string slug: type: string icon: type: string image: nullable: true imageClass: nullable: true type: string bgColor: type: string color: type: string disabled: type: number user: type: object properties: uid: type: number description: A user identifier username: type: string description: A friendly name for a given user account userslug: type: string description: An URL-safe variant of the username (i.e. lower-cased, spaces removed, etc.) reputation: type: number postcount: type: number picture: nullable: true type: string signature: nullable: true type: string banned: type: number status: type: string icon:text: type: string description: A single-letter representation of a username. This is used in the auto-generated icon given to users without an avatar icon:bgColor: type: string description: A six-character hexadecimal colour code assigned to the user. This value is used in conjunction with `icon:text` for the user's auto-generated icon example: "#f44336" banned_until_readable: type: string fullname: type: string teaser: type: object properties: pid: type: number uid: type: number description: A user identifier timestamp: type: number tid: type: number description: A topic identifier content: type: string timestampISO: type: string description: An ISO 8601 formatted date string (complementing `timestamp`) user: type: object properties: uid: type: number description: A user identifier username: type: string description: A friendly name for a given user account userslug: type: string description: An URL-safe variant of the username (i.e. lower-cased, spaces removed, etc.) picture: nullable: true type: string icon:text: type: string description: A single-letter representation of a username. This is used in the auto-generated icon given to users without an avatar icon:bgColor: type: string description: A six-character hexadecimal colour code assigned to the user. This value is used in conjunction with `icon:text` for the user's auto-generated icon example: "#f44336" index: type: number tags: type: array items: type: object properties: value: type: string valueEscaped: type: string color: type: string bgColor: type: string score: type: number isOwner: type: boolean ignored: type: boolean unread: type: boolean bookmark: nullable: true unreplied: type: boolean icons: type: array items: {} index: type: number thumb: type: string isQuestion: nullable: true type: number isSolved: type: number tag: type: string title: type: string categories: type: array items: type: object properties: cid: type: number description: A category identifier name: type: string level: type: string icon: type: string parentCid: type: number description: The category identifier for the category that is the immediate ancestor of the current category color: type: string bgColor: type: string selected: type: boolean imageClass: type: string rssFeedUrl: type: string required: - topics - tag - title - categories - $ref: components/schemas/Pagination.yaml#/Pagination - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - $ref: components/schemas/CommonProps.yaml#/CommonProps /api/popular: get: tags: - topics summary: Get popular topics description: Returns a list of topics sorted by most replies. In an event of a tie breaker, the topic with the most views. Can be filtered by All Time, Day, Week, or Month. responses: "200": description: An array of topic objects sorted by most replies and views. content: application/json: schema: allOf: - type: object properties: nextStart: type: number topicCount: type: number topics: type: array items: $ref: components/schemas/TopicObject.yaml#/TopicObject tids: type: array items: type: number canPost: type: boolean categories: type: array items: type: object properties: cid: type: number description: A category identifier name: type: string level: type: string icon: type: string parentCid: type: number description: The category identifier for the category that is the immediate ancestor of the current category color: type: string bgColor: type: string selected: type: boolean imageClass: type: string allCategoriesUrl: type: string selectedCategory: type: object properties: icon: type: string name: type: string bgColor: type: string nullable: true selectedCids: type: array items: type: number feeds:disableRSS: type: number rssFeedUrl: type: string title: type: string filters: type: array items: type: object properties: name: type: string url: type: string selected: type: boolean filter: type: string selectedFilter: type: object properties: name: type: string url: type: string selected: type: boolean filter: type: string terms: type: array items: type: object properties: name: type: string url: type: string selected: type: boolean term: type: string selectedTerm: type: object properties: name: type: string url: type: string selected: type: boolean term: type: string - $ref: components/schemas/Pagination.yaml#/Pagination - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - $ref: components/schemas/CommonProps.yaml#/CommonProps /api/top: get: tags: - topics summary: Get top topics description: Returns a list of topics sorted by most upvotes. responses: "200": description: An array of topic objects sorted by most upvotes. content: application/json: schema: allOf: - type: object properties: nextStart: type: number topicCount: type: number topics: type: array items: $ref: components/schemas/TopicObject.yaml#/TopicObject tids: type: array items: type: number canPost: type: boolean categories: type: array items: type: object properties: cid: type: number description: A category identifier name: type: string level: type: string icon: type: string parentCid: type: number description: The category identifier for the category that is the immediate ancestor of the current category color: type: string bgColor: type: string selected: type: boolean imageClass: type: string allCategoriesUrl: type: string selectedCategory: type: object properties: cid: type: number description: A category identifier name: type: string level: type: string icon: type: string parentCid: type: number description: The category identifier for the category that is the immediate ancestor of the current category color: type: string bgColor: type: string selected: type: boolean nullable: true selectedCids: type: array items: type: number feeds:disableRSS: type: number rssFeedUrl: type: string title: type: string filters: type: array items: type: object properties: name: type: string url: type: string selected: type: boolean filter: type: string selectedFilter: type: object properties: name: type: string url: type: string selected: type: boolean filter: type: string terms: type: array items: type: object properties: name: type: string url: type: string selected: type: boolean term: type: string selectedTerm: type: object properties: name: type: string url: type: string selected: type: boolean term: type: string - $ref: components/schemas/Pagination.yaml#/Pagination - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - $ref: components/schemas/CommonProps.yaml#/CommonProps "/api/category/{category_id}/{slug}/{topic_index}": get: tags: - categories summary: Get a single category description: This route retrieves a single category's data, along with its children and the topics created inside of the category. parameters: - name: category_id in: path required: true schema: type: string example: 1 - name: slug description: This parameter is not required. If omitted, the request will be automatically redirected with the proper category slug. in: path required: true schema: type: string example: test - name: topic_index description: This parameter is not required. If omitted, the request will presume that you want the first post. The API response is largely unaffected by this parameter, it is used client-side (to send the user to the requested post), and changes the meta/link tags in the server-side generated HTML. in: path required: true schema: type: string example: 1 responses: "200": description: "" content: application/json: schema: allOf: - $ref: components/schemas/CategoryObject.yaml#/CategoryObject - type: object properties: tagWhitelist: type: array items: type: string unread-class: type: string children: type: array items: $ref: components/schemas/CategoryObject.yaml#/CategoryObject topics: type: array items: $ref: components/schemas/TopicObject.yaml#/TopicObject nextStart: type: number isWatched: type: boolean isNotWatched: type: boolean isIgnored: type: boolean title: type: string privileges: type: object properties: topics:create: type: boolean topics:read: type: boolean topics:tag: type: boolean read: type: boolean cid: type: string uid: type: number description: A user identifier editable: type: boolean view_deleted: type: boolean isAdminOrMod: type: boolean showSelect: type: boolean rssFeedUrl: type: string feeds:disableRSS: type: number reputation:disabled: type: number - $ref: components/schemas/Pagination.yaml#/Pagination - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - $ref: components/schemas/CommonProps.yaml#/CommonProps /api/me: get: tags: - shorthand summary: Access your profile description: This shorthand is useful if you want to link to pages in your own account profile, but do not want (or have) the userslug. It is also especially useful as a means to instruct users on how to do things, as you can easily redirect them to their own profile pages. responses: "200": description: "" content: application/json: schema: $ref: components/schemas/UserObject.yaml#/UserObjectFull /api/me/*: get: tags: - shorthand summary: Access your own profile's sub-pages description: >- This shorthand is useful if you want to link to pages in your own account profile, but do not want (or have) the `userslug`. It is also especially useful as a means to instruct users on how to do things, as you can easily redirect them to their own profile pages. responses: "200": description: "Canonical URL to your requested profile page" "/api/uid/{uid}/*": get: tags: - shorthand summary: Access a user's profile pages description: >- This particular shorthand is useful if you are looking to redirect to a user's profile (or other associated pages), but do not know or want to retrieve their userslug, which is part of the canonical url. For example, to go to `uid` 15's list of topics made, you can navigate to `/api/uid/15/topics`, which will send you to the appropriate canonical URL for that user's topics. parameters: - name: uid in: path required: true schema: type: string example: 1 responses: "200": description: "Canonical URL of user profile page" "/api/user/{userslug}": get: tags: - users summary: Get user profile parameters: - name: userslug in: path required: true schema: type: string example: admin responses: "200": description: "" content: application/json: schema: allOf: - $ref: components/schemas/UserObject.yaml#/UserObjectFull - type: object properties: posts: $ref: components/schemas/PostsObject.yaml#/PostsObject latestPosts: $ref: components/schemas/PostsObject.yaml#/PostsObject bestPosts: $ref: components/schemas/PostsObject.yaml#/PostsObject hasPrivateChat: type: number title: type: string allowCoverPicture: type: boolean selectedGroup: type: array items: type: object properties: name: type: string slug: type: string createtime: type: number userTitle: type: string description: type: string memberCount: type: number deleted: type: string hidden: type: number system: type: number private: type: number ownerUid: type: number icon: type: string labelColor: type: string cover:url: type: string cover:position: type: string userTitleEnabled: type: number disableJoinRequests: type: number disableLeave: type: number nameEncoded: type: string displayName: type: string textColor: type: string createtimeISO: type: string cover:thumb:url: type: string - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - $ref: components/schemas/CommonProps.yaml#/CommonProps "/api/user/{userslug}/following": get: tags: - users summary: Get followed users parameters: - name: userslug in: path required: true schema: type: string example: admin - name: page in: query schema: type: number example: '' responses: "200": description: "" content: application/json: schema: allOf: - $ref: components/schemas/UserObject.yaml#/UserObjectFull - type: object properties: title: type: string users: type: array items: type: object properties: uid: type: number description: A user identifier username: type: string description: A friendly name for a given user account userslug: type: string description: An URL-safe variant of the username (i.e. lower-cased, spaces removed, etc.) picture: nullable: true type: string status: type: string postcount: type: number reputation: type: number email:confirmed: type: number description: Whether the user has confirmed their email address or not lastonline: type: number flags: nullable: true banned: type: number banned:expire: type: number joindate: type: number description: A UNIX timestamp representing the moment the user's account was created icon:text: type: string description: A single-letter representation of a username. This is used in the auto-generated icon given to users without an avatar icon:bgColor: type: string description: A six-character hexadecimal colour code assigned to the user. This value is used in conjunction with `icon:text` for the user's auto-generated icon example: "#f44336" joindateISO: type: string lastonlineISO: type: string banned_until: type: number banned_until_readable: type: string administrator: type: boolean - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - $ref: components/schemas/Pagination.yaml#/Pagination - $ref: components/schemas/CommonProps.yaml#/CommonProps "/api/user/{userslug}/followers": get: tags: - users summary: Get followers parameters: - name: userslug in: path required: true schema: type: string example: admin - name: page in: query schema: type: number example: '' responses: "200": description: "" content: application/json: schema: allOf: - $ref: components/schemas/UserObject.yaml#/UserObjectFull - type: object properties: title: type: string users: type: array items: type: object properties: uid: type: number description: A user identifier username: type: string description: A friendly name for a given user account userslug: type: string description: An URL-safe variant of the username (i.e. lower-cased, spaces removed, etc.) picture: nullable: true type: string status: type: string postcount: type: number reputation: type: number email:confirmed: type: number description: Whether the user has confirmed their email address or not lastonline: type: number flags: nullable: true banned: type: number banned:expire: type: number joindate: type: number description: A UNIX timestamp representing the moment the user's account was created icon:text: type: string description: A single-letter representation of a username. This is used in the auto-generated icon given to users without an avatar icon:bgColor: type: string description: A six-character hexadecimal colour code assigned to the user. This value is used in conjunction with `icon:text` for the user's auto-generated icon example: "#f44336" joindateISO: type: string lastonlineISO: type: string banned_until: type: number banned_until_readable: type: string administrator: type: boolean - $ref: components/schemas/Pagination.yaml#/Pagination - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - $ref: components/schemas/CommonProps.yaml#/CommonProps "/api/user/{userslug}/categories": get: tags: - users summary: Get user's watched categories description: This route retrieves the list of categories and their watch states parameters: - name: userslug in: path required: true schema: type: string example: admin responses: "200": description: "" content: application/json: schema: allOf: - $ref: components/schemas/UserObject.yaml#/UserObjectFull - type: object properties: categories: type: array items: type: object properties: cid: type: number description: A category identifier name: type: string level: type: string icon: type: string parentCid: type: number description: The category identifier for the category that is the immediate ancestor of the current category color: type: string bgColor: type: string descriptionParsed: type: string depth: type: number slug: type: string isIgnored: type: boolean isWatched: type: boolean isNotWatched: type: boolean imageClass: type: string title: type: string - $ref: components/schemas/CommonProps.yaml#/CommonProps "/api/user/{userslug}/posts": get: tags: - users summary: Get a user's posts parameters: - name: userslug in: path required: true schema: type: string example: admin responses: "200": description: "" content: application/json: schema: allOf: - $ref: components/schemas/UserObject.yaml#/UserObjectFull - type: object properties: posts: $ref: components/schemas/PostsObject.yaml#/PostsObject nextStart: type: number noItemsFoundKey: type: string title: type: string showSort: type: boolean sortOptions: type: array items: type: object properties: url: type: string name: type: string selected: type: boolean - $ref: components/schemas/Pagination.yaml#/Pagination - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - $ref: components/schemas/CommonProps.yaml#/CommonProps "/api/user/{userslug}/topics": get: tags: - users summary: Get a user's topics parameters: - name: userslug in: path required: true schema: type: string example: admin responses: "200": description: "" content: application/json: schema: allOf: - $ref: components/schemas/UserObject.yaml#/UserObjectFull - type: object properties: topics: type: array items: $ref: components/schemas/TopicObject.yaml#/TopicObject nextStart: type: number noItemsFoundKey: type: string title: type: string showSort: type: boolean sortOptions: type: array items: type: object properties: url: type: string name: type: string selected: type: boolean - $ref: components/schemas/Pagination.yaml#/Pagination - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - $ref: components/schemas/CommonProps.yaml#/CommonProps "/api/user/{userslug}/best": get: tags: - users summary: Get a user's best performing topics parameters: - name: userslug in: path required: true schema: type: string example: admin responses: "200": description: "" content: application/json: schema: allOf: - $ref: components/schemas/UserObject.yaml#/UserObjectFull - type: object properties: posts: $ref: components/schemas/PostsObject.yaml#/PostsObject nextStart: type: number noItemsFoundKey: type: string title: type: string showSort: type: boolean sortOptions: type: array items: type: object properties: url: type: string name: type: string selected: type: boolean - $ref: components/schemas/Pagination.yaml#/Pagination - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - $ref: components/schemas/CommonProps.yaml#/CommonProps "/api/user/{userslug}/groups": get: tags: - users summary: Get user's groups parameters: - name: userslug in: path required: true schema: type: string example: admin responses: "200": description: "" content: application/json: schema: allOf: - $ref: components/schemas/UserObject.yaml#/UserObjectFull - type: object properties: title: type: string template: type: object properties: name: type: string account/groups: type: boolean - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - $ref: components/schemas/CommonProps.yaml#/CommonProps "/api/user/{userslug}/bookmarks": get: tags: - users summary: Get user's bookmarks parameters: - name: userslug in: path required: true schema: type: string example: admin responses: "200": description: "" content: application/json: schema: allOf: - $ref: components/schemas/UserObject.yaml#/UserObjectFull - type: object properties: posts: $ref: components/schemas/PostsObject.yaml#/PostsObject nextStart: type: number noItemsFoundKey: type: string title: type: string showSort: type: boolean sortOptions: type: array items: type: object properties: url: type: string name: type: string selected: type: boolean - $ref: components/schemas/Pagination.yaml#/Pagination - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - $ref: components/schemas/CommonProps.yaml#/CommonProps "/api/user/{userslug}/watched": get: tags: - users summary: Get user's watched topics parameters: - name: userslug in: path required: true schema: type: string example: admin responses: "200": description: "" content: application/json: schema: allOf: - $ref: components/schemas/UserObject.yaml#/UserObject - type: object properties: aboutmeParsed: type: string age: type: number emailClass: type: string ips: type: array items: type: string isBlocked: type: boolean blocksCount: type: number yourid: type: number theirid: type: number isTargetAdmin: type: boolean isAdmin: type: boolean isGlobalModerator: type: boolean isModerator: type: boolean isAdminOrGlobalModerator: type: boolean isAdminOrGlobalModeratorOrModerator: type: boolean isSelfOrAdminOrGlobalModerator: type: boolean canEdit: type: boolean canBan: type: boolean canChangePassword: type: boolean isSelf: type: boolean isFollowing: type: boolean hasPrivateChat: type: number showHidden: type: boolean groups: type: array items: type: object properties: name: type: string slug: type: string createtime: type: number userTitle: type: string description: type: string memberCount: type: number deleted: oneOf: - type: string - type: number hidden: type: number system: type: number private: type: number ownerUid: type: number icon: type: string labelColor: type: string userTitleEnabled: type: number disableJoinRequests: type: number disableLeave: type: number nameEncoded: type: string displayName: type: string textColor: type: string createtimeISO: type: string cover:thumb:url: type: string cover:url: type: string cover:position: type: string disableSignatures: type: boolean reputation:disabled: type: boolean downvote:disabled: type: boolean profile_links: type: array items: type: object properties: id: type: string route: type: string name: type: string visibility: type: object properties: self: type: boolean other: type: boolean moderator: type: boolean globalMod: type: boolean admin: type: boolean canViewInfo: type: boolean public: type: boolean icon: type: string sso: type: array items: type: object properties: associated: type: boolean url: type: string deauthUrl: type: string name: type: string icon: type: string websiteLink: type: string websiteName: type: string moderationNote: type: string username:disableEdit: type: boolean email:disableEdit: type: boolean topics: type: array items: $ref: components/schemas/TopicObject.yaml#/TopicObject nextStart: type: number noItemsFoundKey: type: string title: type: string showSort: type: boolean sortOptions: type: array items: type: object properties: url: type: string name: type: string selected: type: boolean - $ref: components/schemas/Pagination.yaml#/Pagination - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - $ref: components/schemas/CommonProps.yaml#/CommonProps "/api/user/{userslug}/ignored": get: tags: - users summary: Get user's ignored topics parameters: - name: userslug in: path required: true schema: type: string example: admin responses: "200": description: "" content: application/json: schema: allOf: - $ref: components/schemas/UserObject.yaml#/UserObjectFull - type: object properties: topics: type: array items: $ref: components/schemas/TopicObject.yaml#/TopicObject nextStart: type: number noItemsFoundKey: type: string title: type: string showSort: type: boolean sortOptions: type: array items: type: object properties: url: type: string name: type: string selected: type: boolean - $ref: components/schemas/Pagination.yaml#/Pagination - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - $ref: components/schemas/CommonProps.yaml#/CommonProps "/api/user/{userslug}/upvoted": get: tags: - users summary: Get user's upvoted posts parameters: - name: userslug in: path required: true schema: type: string example: admin responses: "200": description: "" content: application/json: schema: allOf: - $ref: components/schemas/UserObject.yaml#/UserObjectFull - type: object properties: posts: $ref: components/schemas/PostsObject.yaml#/PostsObject nextStart: type: number noItemsFoundKey: type: string description: Translation key for message notifying user that there were no posts found title: type: string showSort: type: boolean sortOptions: type: array items: type: object properties: url: type: string name: type: string selected: type: boolean required: - posts - nextStart - noItemsFoundKey - title - $ref: components/schemas/Pagination.yaml#/Pagination - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - $ref: components/schemas/CommonProps.yaml#/CommonProps "/api/user/{userslug}/downvoted": get: tags: - users summary: Get user's downvoted posts parameters: - name: userslug in: path required: true schema: type: string example: admin responses: "200": description: "" content: application/json: schema: allOf: - $ref: components/schemas/UserObject.yaml#/UserObjectFull - type: object properties: posts: $ref: components/schemas/PostsObject.yaml#/PostsObject nextStart: type: number noItemsFoundKey: type: string description: Translation key for message notifying user that there were no posts found title: type: string showSort: type: boolean sortOptions: type: array items: type: object properties: url: type: string name: type: string selected: type: boolean required: - posts - nextStart - noItemsFoundKey - title - $ref: components/schemas/Pagination.yaml#/Pagination - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - $ref: components/schemas/CommonProps.yaml#/CommonProps "/api/user/{userslug}/edit": get: tags: - users summary: Get user profile for editing parameters: - name: userslug in: path required: true schema: type: string example: admin responses: "200": description: "" content: application/json: schema: allOf: - $ref: components/schemas/UserObject.yaml#/UserObjectFull - type: object properties: maximumSignatureLength: type: number maximumAboutMeLength: type: number maximumProfileImageSize: type: number allowProfilePicture: type: boolean allowCoverPicture: type: boolean allowProfileImageUploads: type: number allowedProfileImageExtensios: type: string allowMultipleBadges: type: boolean allowAccountDelete: type: boolean allowWebsite: type: boolean allowAboutMe: type: boolean allowSignature: type: boolean profileImageDimension: type: number defaultAvatar: type: string groupSelectSize: type: number title: type: string editButtons: type: array items: type: object properties: link: type: string description: A relative path to the page linked to text: type: string description: Button label - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - $ref: components/schemas/CommonProps.yaml#/CommonProps "/api/user/{userslug}/edit/username": get: tags: - users summary: Get configs for username editing parameters: - name: userslug in: path required: true schema: type: string example: admin responses: "200": description: "" content: application/json: schema: allOf: - $ref: components/schemas/UserObject.yaml#/UserObjectFull - type: object properties: hasPassword: type: boolean title: type: string - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - $ref: components/schemas/CommonProps.yaml#/CommonProps "/api/user/{userslug}/edit/email": get: tags: - users summary: Get configs for email editing parameters: - name: userslug in: path required: true schema: type: string example: admin responses: "200": description: "" content: application/json: schema: allOf: - $ref: components/schemas/UserObject.yaml#/UserObjectFull - type: object properties: hasPassword: type: boolean title: type: string - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - $ref: components/schemas/CommonProps.yaml#/CommonProps "/api/user/{userslug}/edit/password": get: tags: - users summary: Get configs for password editing parameters: - name: userslug in: path required: true schema: type: string example: admin responses: "200": description: "" content: application/json: schema: allOf: - $ref: components/schemas/UserObject.yaml#/UserObjectFull - type: object properties: hasPassword: type: boolean minimumPasswordLength: type: number minimumPasswordStrength: type: number title: type: string - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - $ref: components/schemas/CommonProps.yaml#/CommonProps "/api/user/{userslug}/info": get: tags: - users summary: Get user moderation info description: Administrators and Global Moderators get access to the `/info` page, which shows some backend data that is useful from a moderation point-of-view (such as IP addresses, recent bans, moderation history, etc). parameters: - name: userslug in: path required: true schema: type: string example: admin responses: "200": description: "" content: application/json: schema: allOf: - $ref: components/schemas/UserObject.yaml#/UserObjectFull - type: object properties: history: type: object properties: flags: type: array items: type: object properties: pid: type: number timestamp: type: number timestampISO: type: string description: An ISO 8601 formatted date string (complementing `timestamp`) timestampReadable: type: string additionalProperties: description: Contextual data is added to this object (such as topic data, etc.) bans: type: array items: type: object properties: uid: type: number timestamp: type: number expire: type: number fromUid: type: number user: type: object properties: username: type: string description: A friendly name for a given user account userslug: type: string description: An URL-safe variant of the username (i.e. lower-cased, spaces removed, etc.) picture: type: string uid: type: number description: A user identifier icon:text: type: string description: A single-letter representation of a username. This is used in the auto-generated icon given to users without an avatar icon:bgColor: type: string description: A six-character hexadecimal colour code assigned to the user. This value is used in conjunction with `icon:text` for the user's auto-generated icon example: "#f44336" until: type: number untilReadable: type: string timestampReadable: type: string timestampISO: type: string reason: type: string sessions: type: array items: type: object properties: ip: type: string uuid: type: string datetime: type: number platform: type: string browser: type: string version: type: string current: type: boolean datetimeISO: type: string usernames: type: array items: type: object properties: value: type: string timestamp: type: number timestampISO: type: string description: An ISO 8601 formatted date string (complementing `timestamp`) emails: type: array items: type: object properties: value: type: string timestamp: type: number timestampISO: type: string description: An ISO 8601 formatted date string (complementing `timestamp`) moderationNotes: type: array items: type: object properties: uid: type: number note: type: string timestamp: type: number timestampISO: type: string user: type: object properties: username: type: string description: A friendly name for a given user account userslug: type: string description: An URL-safe variant of the username (i.e. lower-cased, spaces removed, etc.) picture: type: string uid: type: number description: A user identifier icon:text: type: string description: A single-letter representation of a username. This is used in the auto-generated icon given to users without an avatar icon:bgColor: type: string description: A six-character hexadecimal colour code assigned to the user. This value is used in conjunction with `icon:text` for the user's auto-generated icon example: "#f44336" title: type: string - $ref: components/schemas/Pagination.yaml#/Pagination - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - $ref: components/schemas/CommonProps.yaml#/CommonProps "/api/user/{userslug}/settings": get: tags: - users summary: Get user's settings parameters: - name: userslug in: path required: true schema: type: string example: admin responses: "200": description: "" content: application/json: schema: allOf: - $ref: components/schemas/UserObject.yaml#/UserObjectFull - type: object properties: settings: type: object properties: showemail: type: boolean usePagination: type: boolean topicsPerPage: type: number postsPerPage: type: number topicPostSort: type: string openOutgoingLinksInNewTab: type: boolean dailyDigestFreq: type: string showfullname: type: boolean followTopicsOnCreate: type: boolean followTopicsOnReply: type: boolean restrictChat: type: boolean topicSearchEnabled: type: boolean categoryTopicSort: type: string userLang: type: string bootswatchSkin: type: string homePageRoute: type: string scrollToMyPost: type: boolean notificationSound: type: string incomingChatSound: type: string outgoingChatSound: type: string notificationType_new-chat: type: string notificationType_new-reply: type: string notificationType_post-edit: type: string sendChatNotifications: nullable: true sendPostNotifications: nullable: true notificationType_upvote: type: string notificationType_new-topic: type: string notificationType_follow: type: string notificationType_group-invite: type: string upvoteNotifFreq: type: string notificationType_mention: type: string acpLang: type: string notificationType_new-register: type: string notificationType_post-queue: type: string notificationType_new-post-flag: type: string notificationType_new-user-flag: type: string categoryWatchState: type: string notificationType_group-request-membership: type: string uid: type: number description: A user identifier required: - showemail - usePagination - topicsPerPage - postsPerPage - topicPostSort - openOutgoingLinksInNewTab - dailyDigestFreq - showfullname - followTopicsOnCreate - followTopicsOnReply - restrictChat - topicSearchEnabled - categoryTopicSort - userLang - bootswatchSkin - homePageRoute - scrollToMyPost - notificationType_new-chat - notificationType_new-reply - notificationType_upvote - notificationType_new-topic - notificationType_follow - notificationType_group-invite - upvoteNotifFreq - acpLang - notificationType_new-register - notificationType_post-queue - notificationType_new-post-flag - notificationType_new-user-flag - categoryWatchState - notificationType_group-request-membership - uid languages: type: array items: type: object properties: name: type: string code: type: string dir: type: string selected: type: boolean acpLanguages: type: array items: type: object properties: name: type: string code: type: string dir: type: string selected: type: boolean notification-sound: type: array items: type: object properties: name: type: string sounds: type: array items: type: object properties: name: type: string value: type: string selected: type: boolean notificationSound: type: array items: type: object properties: name: type: string selected: type: boolean chat-incoming-sound: type: array items: type: object properties: name: type: string sounds: type: array items: type: object properties: name: type: string value: type: string selected: type: boolean incomingChatSound: type: array items: type: object properties: name: type: string selected: type: boolean chat-outgoing-sound: type: array items: type: object properties: name: type: string sounds: type: array items: type: object properties: name: type: string value: type: string selected: type: boolean outgoingChatSound: type: array items: type: object properties: name: type: string selected: type: boolean customSettings: type: array items: type: object properties: {} additionalProperties: {} homePageRoutes: type: array items: type: object properties: route: type: string name: type: string selected: type: boolean notificationSettings: type: array items: type: object properties: name: type: string label: type: string none: type: boolean notification: type: boolean email: type: boolean notificationemail: type: boolean disableEmailSubscriptions: type: number dailyDigestFreqOptions: type: array items: type: object properties: value: type: string name: type: string selected: type: boolean bootswatchSkinOptions: type: array items: type: object properties: name: type: string value: type: string selected: type: boolean upvoteNotifFreq: type: array items: type: object properties: name: type: string selected: type: boolean categoryWatchState: type: object properties: watching: type: boolean disableCustomUserSkins: type: number allowUserHomePage: type: number hideFullname: type: number hideEmail: type: number inTopicSearchAvailable: type: boolean maxTopicsPerPage: type: number maxPostsPerPage: type: number title: type: string - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - $ref: components/schemas/CommonProps.yaml#/CommonProps "/api/user/{userslug}/uploads": get: tags: - users summary: Get user's uploads parameters: - name: userslug in: path required: true schema: type: string example: admin responses: "200": description: "" content: application/json: schema: allOf: - $ref: components/schemas/UserObject.yaml#/UserObjectFull - type: object properties: uploads: type: array items: type: object properties: name: type: string url: type: string privateUploads: type: boolean title: type: string - $ref: components/schemas/Pagination.yaml#/Pagination - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - $ref: components/schemas/CommonProps.yaml#/CommonProps "/api/user/{userslug}/consent": get: tags: - users summary: Get user's GDPR consent settings parameters: - name: userslug in: path required: true schema: type: string example: admin responses: "200": description: "" content: application/json: schema: allOf: - $ref: components/schemas/UserObject.yaml#/UserObjectFull - type: object properties: gdpr_consent: type: boolean digest: type: object properties: frequency: type: string enabled: type: boolean title: type: string - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - $ref: components/schemas/CommonProps.yaml#/CommonProps "/api/user/{userslug}/blocks": get: tags: - users summary: Get user's blocks parameters: - name: userslug in: path required: true schema: type: string example: admin responses: "200": description: "" content: application/json: schema: allOf: - $ref: components/schemas/UserObject.yaml#/UserObjectFull - type: object properties: users: type: array items: $ref: components/schemas/UserObject.yaml#/UserObjectSlim title: type: string - $ref: components/schemas/Pagination.yaml#/Pagination - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - $ref: components/schemas/CommonProps.yaml#/CommonProps "/api/user/{userslug}/sessions": get: tags: - users summary: Get user's active sessions parameters: - name: userslug in: path required: true schema: type: string example: admin responses: "200": description: "" content: application/json: schema: allOf: - $ref: components/schemas/UserObject.yaml#/UserObjectFull - type: object properties: sessions: type: array items: type: object properties: ip: type: string uuid: type: string datetime: type: number platform: type: string browser: type: string version: type: string current: type: boolean datetimeISO: type: string title: type: string - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - $ref: components/schemas/CommonProps.yaml#/CommonProps "/api/user/{userslug}/session/{uuid}": delete: tags: - users summary: Revoke a user session parameters: - name: userslug in: path required: true schema: type: string example: admin - name: uuid in: path required: true schema: type: string example: testuuid responses: "200": description: User session revoked /api/notifications: get: tags: - notifications summary: Get notifications responses: "200": description: "" content: application/json: schema: allOf: - type: object properties: notifications: type: array items: type: object properties: type: type: string bodyShort: type: string bodyLong: type: string pid: oneOf: - type: number - type: string tid: type: number description: A topic identifier path: type: string nid: type: string from: type: number mergeId: type: string topicTitle: type: string importance: type: number datetime: type: number datetimeISO: type: string user: type: object properties: username: type: string description: A friendly name for a given user account userslug: type: string description: An URL-safe variant of the username (i.e. lower-cased, spaces removed, etc.) picture: type: string uid: type: number description: A user identifier icon:text: type: string description: A single-letter representation of a username. This is used in the auto-generated icon given to users without an avatar icon:bgColor: type: string description: A six-character hexadecimal colour code assigned to the user. This value is used in conjunction with `icon:text` for the user's auto-generated icon example: "#f44336" image: type: string read: type: boolean readClass: type: string subject: type: string filters: type: array items: type: object additionalProperties: {} regularFilters: type: array items: type: object properties: name: type: string filter: type: string selected: type: boolean required: - name - filter moderatorFilters: type: array items: type: object properties: name: type: string filter: type: string selectedFilter: type: object properties: name: type: string filter: type: string selected: type: boolean title: type: string - $ref: components/schemas/Pagination.yaml#/Pagination - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - $ref: components/schemas/CommonProps.yaml#/CommonProps "/api/user/{userslug}/chats/{roomid}": get: tags: - users summary: Get chat room parameters: - name: userslug in: path required: true schema: type: string example: admin - name: roomid in: path required: true schema: type: string example: 1 responses: "200": description: "" content: application/json: schema: allOf: - type: object properties: owner: type: number roomId: type: number roomName: type: string messages: type: array items: type: object properties: content: type: string timestamp: type: number fromuid: type: number roomId: type: string deleted: type: boolean system: type: boolean edited: type: number timestampISO: type: string description: An ISO 8601 formatted date string (complementing `timestamp`) editedISO: type: string messageId: type: number fromUser: type: object properties: uid: type: number description: A user identifier username: type: string description: A friendly name for a given user account userslug: type: string description: An URL-safe variant of the username (i.e. lower-cased, spaces removed, etc.) picture: type: string nullable: true status: type: string banned: type: boolean icon:text: type: string description: A single-letter representation of a username. This is used in the auto-generated icon given to users without an avatar icon:bgColor: type: string description: A six-character hexadecimal colour code assigned to the user. This value is used in conjunction with `icon:text` for the user's auto-generated icon example: "#f44336" banned_until_readable: type: string deleted: type: boolean self: type: number newSet: type: boolean index: type: number cleanedContent: type: string isOwner: type: boolean isOwner: type: boolean users: type: array items: type: object properties: uid: type: number description: A user identifier username: type: string description: A friendly name for a given user account picture: type: string nullable: true status: type: string icon:text: type: string description: A single-letter representation of a username. This is used in the auto-generated icon given to users without an avatar icon:bgColor: type: string description: A six-character hexadecimal colour code assigned to the user. This value is used in conjunction with `icon:text` for the user's auto-generated icon example: "#f44336" isOwner: type: boolean canReply: type: boolean groupChat: type: boolean usernames: type: string maximumUsersInChatRoom: type: number maximumChatMessageLength: type: number showUserInput: type: boolean isAdminOrGlobalMod: type: boolean rooms: type: array items: type: object properties: owner: oneOf: - type: number - type: string roomId: type: number roomName: type: string users: type: array items: type: object properties: uid: type: number description: A user identifier username: type: string description: A friendly name for a given user account userslug: type: string description: An URL-safe variant of the username (i.e. lower-cased, spaces removed, etc.) picture: nullable: true type: string status: type: string lastonline: type: number icon:text: type: string description: A single-letter representation of a username. This is used in the auto-generated icon given to users without an avatar icon:bgColor: type: string description: A six-character hexadecimal colour code assigned to the user. This value is used in conjunction with `icon:text` for the user's auto-generated icon example: "#f44336" lastonlineISO: type: string groupChat: type: boolean unread: type: boolean teaser: type: object properties: fromuid: type: number content: type: string timestamp: type: number timestampISO: type: string description: An ISO 8601 formatted date string (complementing `timestamp`) user: type: object properties: uid: type: number description: A user identifier username: type: string description: A friendly name for a given user account userslug: type: string description: An URL-safe variant of the username (i.e. lower-cased, spaces removed, etc.) picture: nullable: true type: string status: type: string lastonline: type: number icon:text: type: string description: A single-letter representation of a username. This is used in the auto-generated icon given to users without an avatar icon:bgColor: type: string description: A six-character hexadecimal colour code assigned to the user. This value is used in conjunction with `icon:text` for the user's auto-generated icon example: "#f44336" lastonlineISO: type: string nullable: true lastUser: type: object properties: uid: type: number description: A user identifier username: type: string description: A friendly name for a given user account userslug: type: string description: An URL-safe variant of the username (i.e. lower-cased, spaces removed, etc.) picture: nullable: true type: string status: type: string lastonline: type: number icon:text: type: string description: A single-letter representation of a username. This is used in the auto-generated icon given to users without an avatar icon:bgColor: type: string description: A six-character hexadecimal colour code assigned to the user. This value is used in conjunction with `icon:text` for the user's auto-generated icon example: "#f44336" lastonlineISO: type: string usernames: type: string nextStart: type: number title: type: string uid: type: number description: A user identifier userslug: type: string description: An URL-safe variant of the username (i.e. lower-cased, spaces removed, etc.) canViewInfo: type: boolean - $ref: components/schemas/CommonProps.yaml#/CommonProps "/api/chats/{roomid}": get: tags: - shorthand summary: Access a chat room description: Redirects a request to the proper chat page URL parameters: - name: roomid in: path required: true schema: type: string example: 1 responses: "200": description: "Chat identifier resolved" content: text/plain: schema: type: string description: A relative path to the canonical URL for that chat page /api/groups: get: tags: - groups summary: Get user groups responses: "200": description: "" content: application/json: schema: allOf: - type: object properties: groups: type: array items: type: object properties: name: type: string description: type: string deleted: oneOf: - type: number - type: string hidden: type: number system: type: number userTitle: type: string icon: type: string labelColor: type: string createtime: type: number slug: type: string memberCount: type: number private: type: number userTitleEnabled: type: number disableJoinRequests: type: number disableLeave: type: number nameEncoded: type: string displayName: type: string textColor: type: string createtimeISO: type: string cover:thumb:url: type: string cover:url: type: string cover:position: type: string members: type: array items: type: object properties: uid: type: number description: A user identifier username: type: string description: A friendly name for a given user account picture: nullable: true type: string userslug: type: string description: An URL-safe variant of the username (i.e. lower-cased, spaces removed, etc.) icon:text: type: string description: A single-letter representation of a username. This is used in the auto-generated icon given to users without an avatar icon:bgColor: type: string description: A six-character hexadecimal colour code assigned to the user. This value is used in conjunction with `icon:text` for the user's auto-generated icon example: "#f44336" truncated: type: boolean ownerUid: type: number allowGroupCreation: type: boolean nextStart: type: number title: type: string - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - $ref: components/schemas/CommonProps.yaml#/CommonProps "/api/groups/{slug}": get: tags: - groups summary: Get user group details parameters: - name: slug in: path required: true schema: type: string example: administrators responses: "200": description: "" content: application/json: schema: allOf: - type: object properties: title: type: string group: $ref: components/schemas/GroupObject.yaml#/GroupFullObject posts: $ref: components/schemas/PostsObject.yaml#/PostsObject isAdmin: type: boolean isGlobalMod: type: boolean allowPrivateGroups: type: number - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - $ref: components/schemas/CommonProps.yaml#/CommonProps "/api/groups/{slug}/members": get: tags: - groups summary: Get user group members parameters: - name: slug in: path required: true schema: type: string example: administrators responses: "200": description: "" content: application/json: schema: allOf: - type: object properties: users: type: array - $ref: components/schemas/Pagination.yaml#/Pagination - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - $ref: components/schemas/CommonProps.yaml#/CommonProps