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`)
showSystemControls:
type: boolean
- $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:
allOf:
- type : object
properties:
categories:
type: array
items:
type: object
properties:
cid:
type: number
description: A category identifier
name:
type: string
disabled:
type: number
icon:
type: string
link:
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
backgroundImage:
type: string
nullable: true
imageClass:
type: string
children:
type: array
description: Array of children categories
- $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
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
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
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
keys:
type: object
properties:
users:
type: array
items:
type: string
groups:
type: array
items:
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
group:
type: string
- $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
matchCount:
type: number
query:
type: string
uidQuery:
type: string
usernameQuery:
type: string
emailQuery:
type: string
ipQuery:
type: string
pageCount:
type: number
resultsPerPage:
type: number
timing:
type: number
users:
type: array
items:
$ref: components/schemas/UserObject.yaml#/UserObjectACP
- $ref: components/schemas/CommonProps.yaml#/CommonProps
- $ref: components/schemas/Pagination.yaml#/Pagination
/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
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
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
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
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
nodebb:
type: object
properties:
isPrimary:
type: boolean
isCluster:
type: boolean
runJobs:
type: boolean
jobsDisabled:
type: boolean
git:
type: object
properties:
hash:
type: string
hashShort:
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/groups/{groupname}/csv:
get:
tags:
- admin
summary: Get members of a group (.csv)
parameters:
- in: header
name: referer
schema:
type: string
required: true
example: /admin/manage/groups
responses:
"200":
description: "A CSV file containing all users in the group"
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
assetBaseUrl:
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
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
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 (.json)
parameters:
- name: userslug
in: path
required: true
schema:
type: string
example: admin
responses:
"200":
description: "A JSON file containing the user profile"
content:
text/json:
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
flagId:
type: number
description: The flag identifier, if this particular post has been flagged before
replies:
type: number
"/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
minTags:
type: number
maxTags:
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
flagId:
type: number
description: The flag identifier, if this particular post has been flagged before
category:
$ref: components/schemas/CategoryObject.yaml#/CategoryObject
tagWhitelist:
type: array
items:
type: string
minTags:
type: number
maxTags:
type: number
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
showSelect:
type: boolean
showTopicTools:
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
icon:
type: string
selectedFilter:
type: object
properties:
name:
type: string
url:
type: string
selected:
type: boolean
filter:
type: string
icon:
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
showTopicTools:
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
icon:
type: string
selectedFilter:
type: object
properties:
name:
type: string
url:
type: string
selected:
type: boolean
filter:
type: string
icon:
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
privileges:
type: object
properties:
search:users:
type: boolean
search:content:
type: boolean
search:tags:
type: boolean
required:
- posts
- matchCount
- pageCount
- time
- multiplePages
- search_query
- categories
- categoriesCount
- expandSearch
- showAsPosts
- showAsTopics
- title
- searchDefaultSortBy
- permissions
- $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
heat:
type: number
description: The number of reports that make up this flag
flagId:
type: number
type:
type: string
targetId:
oneOf:
- type: string
- type: number
targetUid:
type: number
datetime:
type: number
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
sort:
type: string
title:
type: string
- $ref: components/schemas/Pagination.yaml#/Pagination
- $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs
- $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
targetUid:
type: number
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
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"
reports:
type: array
items:
type: object
properties:
value:
type: string
timestamp:
type: number
timestampISO:
type: string
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
filters:
type: object
properties:
page:
type: number
perPage:
type: number
privileges:
type: object
properties: {}
additionalProperties:
description: "A list of global and admin privileges, and whether the calling user has (or has inherited) them"
type: boolean
- $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs
- $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
allCategories:
type: array
items:
type: object
properties:
bgColor:
type: string
cid:
type: number
color:
type: string
disabled:
type: number
disabledClass:
type: boolean
icon:
type: string
imageClass:
type: string
level:
type: string
link:
type: string
name:
type: string
parentCid:
type: number
slug:
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/Breadcrumbs.yaml#/Breadcrumbs
- $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
showSelect:
type: boolean
showTopicTools:
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
icon:
type: string
selectedFilter:
type: object
properties:
name:
type: string
url:
type: string
selected:
type: boolean
filter:
type: string
icon:
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
showSelect:
type: boolean
showTopicTools:
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
icon:
type: string
selectedFilter:
type: object
properties:
name:
type: string
url:
type: string
selected:
type: boolean
filter:
type: string
icon:
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
showTopicTools:
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:
bodyShort:
type: string
path:
type: string
nid:
type: string
from:
type: number
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
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"
image:
type: string
nullable: true
read:
type: boolean
readClass:
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