Vanilla Forums Categories API
The Categories API from Vanilla Forums — 6 operation(s) for categories.
OpenAPI Specification
openapi: 3.0.3
info:
description: API access to your community.
title: Vanilla Addons Categories API
version: '2.0'
servers:
- url: https://open.vanillaforums.com/api/v2
tags:
- name: Categories
paths:
/categories:
get:
parameters:
- name: categoryID
description: Filter by a range or CSV of category IDs.
in: query
schema:
$ref: '#/components/schemas/RangeExpression'
- description: Parent category ID.
in: query
name: parentCategoryID
schema:
type: integer
- description: Parent category URL code.
in: query
name: parentCategoryCode
schema:
type: string
- description: Only list categories followed by the current user.
in: query
name: followed
required: false
schema:
type: boolean
- description: List the categories followed by the given UserID
in: query
name: followedUserID
schema:
type: integer
- description: The maximum tree depth to return when getting a tree structure. This parameter is incompatible with a flat structure.
in: query
name: maxDepth
schema:
type: integer
default: 2
- name: archived
description: 'Filter by archived status of a category. True for archived only. False for no archived categories.
'
in: query
required: false
schema:
type: boolean
- description: Only list featured categories.
in: query
name: featured
required: false
schema:
type: boolean
- description: Page number. See [Pagination](https://docs.vanillaforums.com/apiv2/#pagination). This parameter is incompatible with a tree structure.
in: query
name: page
schema:
type: integer
minimum: 1
- description: Desired number of items per page. This parameter is incompatible with a tree structure.
in: query
name: limit
schema:
type: integer
maximum: 100
minimum: 1
- name: sort
description: Sort the results.
in: query
schema:
type: string
enum:
- categoryID
- -categoryID
- name
- -name
- dateFollowed
- -dateFollowed
- name: expand
description: 'Expand associated records using one or more valid field names. A value of "all" will expand all expandable fields.
'
in: query
schema:
type: array
items:
type: string
enum:
- all
- lastPost
- preferences
- permissions
- defaultStatus
- lastPost.insertUser
- lastPost.insertUser.ssoID
- lastPost.insertUser.roles
- lastPost.insertUser.profileFields
- lastPost.insertUser.extended
- description: 'Filter categories by site section ID (ex. subcommunity).
The subcommunity ID or folder can be used if you use [smart IDs](https://success.vanillaforums.com/kb/articles/46-smart-ids).
The query looks like:
```
siteSectionID=$subcommunityID:{id|folder}
```
example: "$subcommunityID:en".'
in: query
name: siteSectionID
schema:
type: string
- description: Whether to include the parent category when used with parentCategoryID, parentCategoryCode, or siteSectionID.
in: query
name: includeParentCategory
required: false
schema:
type: boolean
- description: Format of the output as flat or tree.
in: query
name: outputFormat
schema:
type: string
enum:
- flat
- tree
- description: 'Layout View Type.
'
in: query
name: layoutViewType
required: false
schema:
minLength: 1
type: string
- description: Filter by allowed post type ID
in: query
name: postTypeID
required: false
schema:
type: string
- description: Allowed status for the post type ID filter.
in: query
name: postTypeStatus
required: false
schema:
type: string
enum:
- active
- inactive
- both
- description: Filter out categories that cannot be posted into
in: query
name: filterDiscussionsAdd
required: false
schema:
type: boolean
- name: fields
in: query
style: form
description: Only return fields with these keys from the output. Use dot notation for nested fields.
schema:
type: array
items:
type: string
responses:
'200':
content:
application/json:
schema:
items:
properties:
categoryID:
description: The ID of the category.
type: integer
children:
items:
properties:
categoryID:
description: The ID of the category.
type: integer
children:
items:
type: string
type: array
countAllComments:
description: Total of all comments in a category and its children.
type: integer
countAllDiscussions:
description: Total of all discussions in a category and its children.
type: integer
countCategories:
description: Total number of child categories.
type: integer
countComments:
description: Total comments in the category.
type: integer
countDiscussions:
description: Total discussions in the category.
type: integer
countFollowers:
description: Total followers in the category.
type: integer
customPermissions:
description: Are custom permissions set for this category?
type: boolean
depth:
type: integer
description:
description: The description of the category.
minLength: 0
nullable: true
type: string
displayAs:
type: string
default: discussions
description: The display style of the category.
enum:
- categories
- discussions
- flat
- heading
minLength: 1
followed:
description: Is the category being followed by the current user?
type: boolean
isArchived:
description: The archived state of this category.
type: boolean
name:
description: The name of the category.
minLength: 1
type: string
parentCategoryID:
description: Parent category ID.
nullable: true
type: integer
url:
description: The URL to the category.
minLength: 1
type: string
urlcode:
description: The URL code of the category.
minLength: 1
type: string
allowedDiscussionTypes:
description: Allowed category discussion types.
items:
type: string
type: array
required:
- categoryID
- name
- description
- parentCategoryID
- customPermissions
- isArchived
- urlcode
- url
- displayAs
- countCategories
- countDiscussions
- countComments
- countFollowers
- countAllDiscussions
- countAllComments
- depth
- children
type: object
type: array
countAllComments:
description: Total of all comments in a category and its children.
type: integer
countAllDiscussions:
description: Total of all discussions in a category and its children.
type: integer
countCategories:
description: Total number of child categories.
type: integer
countComments:
description: Total comments in the category.
type: integer
countDiscussions:
description: Total discussions in the category.
type: integer
countFollowers:
description: Total followers in the category.
type: integer
customPermissions:
description: Are custom permissions set for this category?
type: boolean
depth:
type: integer
description:
description: The description of the category.
minLength: 0
nullable: true
type: string
displayAs:
type: string
default: discussions
description: The display style of the category.
enum:
- categories
- discussions
- flat
- heading
minLength: 1
followed:
description: Is the category being followed by the current user?
type: boolean
iconUrl:
description: The URL of the category's icon.
nullable: true
type: string
iconUrlSrcSet:
$ref: '#/components/schemas/SrcSet'
isArchived:
description: The archived state of this category.
type: boolean
name:
description: The name of the category.
minLength: 1
type: string
parentCategoryID:
description: Parent category ID.
nullable: true
type: integer
url:
description: The URL to the category.
minLength: 1
type: string
urlcode:
description: The URL code of the category.
minLength: 1
type: string
lastPost:
$ref: '#/components/schemas/PostFragment'
preferences:
$ref: '#/components/schemas/CategoryPreferences'
permissions:
$ref: '#/components/schemas/DiscussionPermissions'
defaultStatusID:
description: The default status ID of the category.
type: integer
required:
- categoryID
- name
- description
- parentCategoryID
- customPermissions
- isArchived
- urlcode
- url
- displayAs
- countCategories
- countDiscussions
- countComments
- countFollowers
- countAllDiscussions
- countAllComments
- depth
type: object
type: array
description: Success
tags:
- Categories
summary: List categories.
x-addon: vanilla
post:
responses:
'201':
content:
application/json:
schema:
properties:
categoryID:
description: The ID of the category.
type: integer
countAllComments:
description: Total of all comments in a category and its children.
type: integer
countAllDiscussions:
description: Total of all discussions in a category and its children.
type: integer
countCategories:
description: Total number of child categories.
type: integer
countComments:
description: Total comments in the category.
type: integer
countDiscussions:
description: Total discussions in the category.
type: integer
countFollowers:
description: Total followers in the category.
type: integer
customPermissions:
description: Are custom permissions set for this category?
type: boolean
description:
description: The description of the category.
minLength: 0
nullable: true
type: string
displayAs:
type: string
default: discussions
description: The display style of the category.
enum:
- categories
- discussions
- flat
- heading
minLength: 1
followed:
description: Is the category being followed by the current user?
type: boolean
isArchived:
description: The archived state of this category.
type: boolean
name:
description: The name of the category.
minLength: 1
type: string
parentCategoryID:
description: Parent category ID.
nullable: true
type: integer
url:
description: The URL to the category.
minLength: 1
type: string
urlcode:
description: The URL code of the category.
minLength: 1
type: string
ideationType:
description: Voting type used for ideation posts.
enum:
- up
- up-down
- false
x-addon: ideation
required:
- categoryID
- name
- description
- parentCategoryID
- customPermissions
- isArchived
- urlcode
- url
- displayAs
- countCategories
- countDiscussions
- countComments
- countFollowers
- countAllDiscussions
- countAllComments
type: object
description: Success
tags:
- Categories
requestBody:
$ref: '#/components/requestBodies/CategoryPost'
summary: Add a category.
x-addon: vanilla
/categories/search:
get:
parameters:
- name: query
description: 'Category name filter.
'
in: query
required: true
schema:
minLength: 1
type: string
- name: displayAs
description: The display style of the category.
in: query
required: false
schema:
type: array
items:
type: string
enum:
- Categories
- Discussions
- Flat
- Heading
style: form
- name: page
description: 'Page number. See [Pagination](https://docs.vanillaforums.com/apiv2/#pagination).
'
in: query
schema:
type: integer
default: 1
maximum: 100
minimum: 1
- name: limit
description: 'Desired number of items per page.
'
in: query
schema:
type: integer
default: 30
maximum: 200
minimum: 1
- name: expand
description: 'Expand associated records using one or more valid field names (all, parent, breadcrumbs).
A value of "all" will expand all expandable fields.
'
in: query
schema:
items:
enum:
- breadcrumbs
- parent
- all
type: string
- name: layoutViewType
description: 'Layout View Type.
'
in: query
required: false
schema:
minLength: 1
type: string
- description: Filter out categories that cannot be posted into
in: query
name: filterDiscussionsAdd
required: false
schema:
type: boolean
- description: Filter categories by site section ID (ex. subcommunity).
in: query
name: siteSectionID
schema:
type: string
- name: fields
in: query
style: form
description: Only return fields with these keys from the output. Use dot notation for nested fields.
schema:
type: array
items:
type: string
responses:
'200':
content:
application/json:
schema:
items:
properties:
categoryID:
description: The ID of the category.
type: integer
countAllComments:
description: Total of all comments in a category and its children.
type: integer
countAllDiscussions:
description: Total of all discussions in a category and its children.
type: integer
countCategories:
description: Total number of child categories.
type: integer
countComments:
description: Total comments in the category.
type: integer
countDiscussions:
description: Total discussions in the category.
type: integer
countFollowers:
description: Total followers in the category.
type: integer
customPermissions:
description: Are custom permissions set for this category?
type: boolean
description:
description: The description of the category.
minLength: 0
nullable: true
type: string
displayAs:
type: string
default: discussions
description: The display style of the category.
enum:
- categories
- discussions
- flat
- heading
minLength: 1
followed:
description: Is the category being followed by the current user?
type: boolean
isArchived:
description: The archived state of this category.
type: boolean
name:
description: The name of the category.
minLength: 1
type: string
parentCategoryID:
description: Parent category ID.
nullable: true
type: integer
url:
description: The URL to the category.
minLength: 1
type: string
urlcode:
description: The URL code of the category.
minLength: 1
type: string
breadcrumbs:
items:
properties:
name:
description: Breadcrumb element name.
minLength: 1
type: string
url:
description: Breadcrumb element url.
minLength: 1
type: string
required:
- name
- url
type: object
type: array
required:
- categoryID
- name
- description
- parentCategoryID
- customPermissions
- isArchived
- urlcode
- url
- displayAs
- countCategories
- countDiscussions
- countComments
- countFollowers
- countAllDiscussions
- countAllComments
type: object
type: array
description: Success
tags:
- Categories
summary: Search categories.
x-addon: vanilla
/categories/{id}:
delete:
parameters:
- description: 'The category ID.
'
in: path
name: id
required: true
schema:
type: integer
responses:
'204':
description: Success
tags:
- Categories
summary: Delete a category.
x-addon: vanilla
get:
parameters:
- description: 'The category ID.
'
in: path
name: id
required: true
schema:
type: integer
- name: expand
description: 'Expand associated records using one or more valid field names (all, parent, breadcrumbs).
A value of "all" will expand all expandable fields.
'
in: query
schema:
items:
enum:
- lastPost
- permissions
- all
- defaultStatus
- lastPost.insertUser
- lastPost.insertUser.ssoID
- lastPost.insertUser.roles
- lastPost.insertUser.profileFields
- lastPost.insertUser.extended
type: string
- name: fields
in: query
style: form
description: Only return fields with these keys from the output. Use dot notation for nested fields.
schema:
type: array
items:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CategorySchema'
description: Success
tags:
- Categories
summary: Get a category.
x-addon: vanilla
patch:
parameters:
- description: The category ID.
in: path
name: id
required: true
schema:
type: integer
responses:
'200':
content:
application/json:
schema:
properties:
categoryID:
description: The ID of the category.
type: integer
countAllComments:
description: Total of all comments in a category and its children.
type: integer
countAllDiscussions:
description: Total of all discussions in a category and its children.
type: integer
countCategories:
description: Total number of child categories.
type: integer
countComments:
description: Total comments in the category.
type: integer
countDiscussions:
description: Total discussions in the category.
type: integer
countFollowers:
description: Total followers in the category.
type: integer
customPermissions:
description: Are custom permissions set for this category?
type: boolean
description:
description: The description of the category.
minLength: 0
nullable: true
type: string
displayAs:
type: string
default: discussions
description: The display style of the category.
enum:
- categories
- discussions
- flat
- heading
minLength: 1
followed:
description: Is the category being followed by the current user?
type: boolean
isArchived:
description: The archived state of this category.
type: boolean
name:
description: The name of the category.
minLength: 1
type: string
parentCategoryID:
description: Parent category ID.
nullable: true
type: integer
url:
description: The URL to the category.
minLength: 1
type: string
urlcode:
description: The URL code of the category.
minLength: 1
type: string
required:
- categoryID
- name
- description
- parentCategoryID
- customPermissions
- isArchived
- urlcode
- url
- displayAs
- countCategories
- countDiscussions
- countComments
- countFollowers
- countAllDiscussions
- countAllComments
type: object
description: Success
tags:
- Categories
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CategoryPost'
required: true
summary: Update a category.
x-addon: vanilla
/categories/{id}/edit:
get:
parameters:
- description: 'The category ID.
'
in: path
name: id
required: true
schema:
type: integer
- name: fields
in: query
style: form
description: Only return fields with these keys from the output. Use dot notation for nested fields.
schema:
type: array
items:
type: string
responses:
'200':
content:
application/json:
schema:
properties:
categoryID:
description: The ID of the category.
type: integer
description:
description: The description of the category.
minLength: 0
nullable: true
type: string
displayAs:
type: string
default: discussions
description: The display style of the category.
enum:
- categories
- discussions
- flat
- heading
minLength: 1
name:
description: The name of the category.
minLength: 1
type: string
parentCategoryID:
description: Parent category ID.
nullable: true
type: integer
urlcode:
description: The URL code of the category.
minLength: 1
type: string
required:
- categoryID
- name
- parentCategoryID
- urlcode
- description
- displayAs
type: object
description: Success
tags:
- Categories
summary: Get a category for editing.
x-addon: vanilla
/categories/{id}/follow:
put:
parameters:
- in: path
name: id
required: true
schema:
type: integer
responses:
'200':
content:
application/json:
schema:
properties:
followed:
description: The category-follow status for the current user.
type: boolean
required:
- followed
type: object
description: Success
tags:
- Categories
requestBody:
content:
application/json:
schema:
properties:
followed:
description: The category-follow status for the current user.
type: boolean
required:
- followed
type: object
required: true
x-addon: vanilla
/categories/{id}/preferences/{userID}:
parameters:
- in: path
name: id
description: The category ID.
required: true
schema:
type: integer
x-addon: vanilla
- in: path
name: userID
required: true
schema:
type: integer
x-addon: vanilla
get:
tags:
- Categories
summary: List a user's category preferences.
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CategoryPreferences'
description: Success
x-addon: vanilla
parameters:
- name: fields
in: query
style:
# --- truncated at 32 KB (52 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/vanilla-forums/refs/heads/main/openapi/vanilla-forums-categories-api-openapi.yml