Discourse Categories API
The Categories API from Discourse — 5 operation(s) for categories.
OpenAPI Specification
openapi: 3.1.0
info:
title: Discourse API Documentation Admin Categories API
x-logo:
url: https://docs.discourse.org/logo.svg
version: latest
description: 'This page contains the documentation on how to use Discourse through API calls.
> Note: For any endpoints not listed you can follow the
[reverse engineer the Discourse API](https://meta.discourse.org/t/-/20576)
guide to figure out how to use an API endpoint.
### Request Content-Type
The Content-Type for POST and PUT requests can be set to `application/x-www-form-urlencoded`,
`multipart/form-data`, or `application/json`.
### Endpoint Names and Response Content-Type
Most API endpoints provide the same content as their HTML counterparts. For example
the URL `/categories` serves a list of categories, the `/categories.json` API provides the
same information in JSON format.
Instead of sending API requests to `/categories.json` you may also send them to `/categories`
and add an `Accept: application/json` header to the request to get the JSON response.
Sending requests with the `Accept` header is necessary if you want to use URLs
for related endpoints returned by the API, such as pagination URLs.
These URLs are returned without the `.json` prefix so you need to add the header in
order to get the correct response format.
### Authentication
Some endpoints do not require any authentication, pretty much anything else will
require you to be authenticated.
To become authenticated you will need to create an API Key from the admin panel.
Once you have your API Key you can pass it in along with your API Username
as an HTTP header like this:
```
curl -X GET "http://127.0.0.1:3000/admin/users/list/active.json" \
-H "Api-Key: 714552c6148e1617aeab526d0606184b94a80ec048fc09894ff1a72b740c5f19" \
-H "Api-Username: system"
```
and this is how POST requests will look:
```
curl -X POST "http://127.0.0.1:3000/categories" \
-H "Content-Type: multipart/form-data;" \
-H "Api-Key: 714552c6148e1617aeab526d0606184b94a80ec048fc09894ff1a72b740c5f19" \
-H "Api-Username: system" \
-F "name=89853c20-4409-e91a-a8ea-f6cdff96aaaa" \
-F "color=49d9e9" \
-F "text_color=f0fcfd"
```
### Boolean values
If an endpoint accepts a boolean be sure to specify it as a lowercase
`true` or `false` value unless noted otherwise.
'
license:
name: MIT
url: https://docs.discourse.org/LICENSE.txt
servers:
- url: https://{defaultHost}
variables:
defaultHost:
default: discourse.example.com
tags:
- name: Categories
paths:
/categories.json:
post:
summary: Creates a category
tags:
- Categories
operationId: createCategory
parameters: []
responses:
'200':
description: success response
content:
application/json:
schema:
additionalProperties: false
properties:
category:
type: object
additionalProperties: false
properties:
id:
type: integer
name:
type: string
color:
type: string
text_color:
type: string
style_type:
type: string
emoji:
type:
- string
- 'null'
icon:
type:
- string
- 'null'
slug:
type: string
locale:
type:
- string
- 'null'
topic_count:
type: integer
post_count:
type: integer
position:
type: integer
description:
type:
- string
- 'null'
description_text:
type:
- string
- 'null'
description_excerpt:
type:
- string
- 'null'
topic_url:
type:
- string
- 'null'
read_restricted:
type: boolean
permission:
type:
- integer
- 'null'
notification_level:
type: integer
can_edit:
type: boolean
topic_template:
type:
- string
- 'null'
topic_title_placeholder:
type:
- string
- 'null'
form_template_ids:
type: array
items: {}
has_children:
type:
- boolean
- 'null'
subcategory_count:
type:
- integer
- 'null'
sort_order:
type:
- string
- 'null'
sort_ascending:
type:
- string
- 'null'
show_subcategory_list:
type: boolean
num_featured_topics:
type: integer
default_view:
type:
- string
- 'null'
subcategory_list_style:
type: string
default_top_period:
type: string
default_list_filter:
type: string
minimum_required_tags:
type: integer
navigate_to_first_post_after_read:
type: boolean
custom_fields:
type: object
additionalProperties: false
properties: {}
allowed_tags:
type: array
items: {}
allowed_tag_groups:
type: array
items: {}
allow_global_tags:
type: boolean
required_tag_groups:
type: array
items:
type: object
additionalProperties: false
properties:
name:
type: string
min_count:
type: integer
required:
- name
- min_count
category_setting:
type: object
additionalProperties: false
properties:
auto_bump_cooldown_days:
type: integer
num_auto_bump_daily:
type:
- integer
- 'null'
require_reply_approval:
type:
- boolean
- 'null'
require_topic_approval:
type:
- boolean
- 'null'
category_localizations:
type: array
items: {}
read_only_banner:
type:
- string
- 'null'
available_groups:
type: array
items: {}
auto_close_hours:
type:
- string
- 'null'
auto_close_based_on_last_post:
type: boolean
allow_unlimited_owner_edits_on_first_post:
type: boolean
default_slow_mode_seconds:
type:
- string
- 'null'
group_permissions:
type: array
items:
type: object
additionalProperties: false
properties:
permission_type:
type: integer
group_name:
type: string
group_id:
type: integer
required:
- permission_type
- group_name
- group_id
email_in:
type:
- string
- 'null'
email_in_allow_strangers:
type: boolean
mailinglist_mirror:
type: boolean
all_topics_wiki:
type: boolean
can_delete:
type: boolean
allow_badges:
type: boolean
topic_featured_link_allowed:
type: boolean
search_priority:
type: integer
uploaded_logo:
type:
- string
- 'null'
uploaded_logo_dark:
type:
- string
- 'null'
uploaded_background:
type:
- string
- 'null'
uploaded_background_dark:
type:
- string
- 'null'
category_types:
type: object
required:
- id
- name
- color
- text_color
- style_type
- emoji
- icon
- slug
- topic_count
- post_count
- position
- description
- description_text
- description_excerpt
- topic_url
- read_restricted
- permission
- notification_level
- can_edit
- topic_template
- topic_title_placeholder
- has_children
- subcategory_count
- sort_order
- sort_ascending
- show_subcategory_list
- num_featured_topics
- default_view
- subcategory_list_style
- default_top_period
- default_list_filter
- minimum_required_tags
- navigate_to_first_post_after_read
- custom_fields
- required_tag_groups
- read_only_banner
- available_groups
- auto_close_hours
- auto_close_based_on_last_post
- allow_unlimited_owner_edits_on_first_post
- default_slow_mode_seconds
- group_permissions
- email_in
- email_in_allow_strangers
- mailinglist_mirror
- all_topics_wiki
- can_delete
- allow_badges
- topic_featured_link_allowed
- search_priority
- uploaded_logo
- uploaded_logo_dark
- uploaded_background
- uploaded_background_dark
required:
- category
requestBody:
content:
application/json:
schema:
additionalProperties: false
properties:
name:
type: string
color:
type: string
example: 49d9e9
text_color:
type: string
example: f0fcfd
style_type:
type: string
emoji:
type: string
icon:
type: string
parent_category_id:
type: integer
allow_badges:
type: boolean
slug:
type: string
topic_featured_links_allowed:
type: boolean
permissions:
type: object
additionalProperties: true
properties:
everyone:
type: integer
example: 1
staff:
type: integer
search_priority:
type: integer
form_template_ids:
type: array
items: {}
category_localizations:
type: array
items:
type: object
properties:
id:
type: integer
description: 'The unique identifier for an existing localization.
Must be included otherwise the record will be deleted.'
locale:
type: string
description: 'The locale for the localization, e.g., ''en'',
''zh_CN''. Locale should be in the list of SiteSetting.content_localization_supported_locales.'
name:
type: string
description: The name of the category in the specified locale.
description:
type: string
description: 'The description excerpt of the category in the
specified locale.'
required:
- locale
- name
required:
- name
get:
summary: Retrieves a list of categories
tags:
- Categories
operationId: listCategories
parameters:
- name: include_subcategories
in: query
schema:
type: boolean
enum:
- true
responses:
'200':
description: success response
content:
application/json:
schema:
additionalProperties: false
properties:
category_list:
type: object
additionalProperties: false
properties:
can_create_category:
type: boolean
can_create_topic:
type: boolean
categories:
type: array
items:
type: object
additionalProperties: false
properties:
id:
type: integer
name:
type: string
color:
type: string
text_color:
type: string
style_type:
type: string
emoji:
type:
- string
- 'null'
icon:
type:
- string
- 'null'
slug:
type: string
topic_count:
type: integer
post_count:
type: integer
position:
type: integer
description:
type:
- string
- 'null'
description_text:
type:
- string
- 'null'
description_excerpt:
type:
- string
- 'null'
topic_url:
type:
- string
- 'null'
read_restricted:
type: boolean
permission:
type: integer
notification_level:
type: integer
can_edit:
type: boolean
topic_template:
type:
- string
- 'null'
topic_title_placeholder:
type:
- string
- 'null'
has_children:
type: boolean
subcategory_count:
type:
- integer
- 'null'
sort_order:
type:
- string
- 'null'
sort_ascending:
type:
- string
- 'null'
show_subcategory_list:
type: boolean
num_featured_topics:
type: integer
default_view:
type:
- string
- 'null'
subcategory_list_style:
type: string
default_top_period:
type: string
default_list_filter:
type: string
minimum_required_tags:
type: integer
navigate_to_first_post_after_read:
type: boolean
topics_day:
type: integer
topics_week:
type: integer
topics_month:
type: integer
topics_year:
type: integer
topics_all_time:
type: integer
is_uncategorized:
type: boolean
subcategory_ids:
type: array
items: {}
subcategory_list:
type:
- array
- 'null'
items: {}
uploaded_logo:
type:
- string
- 'null'
uploaded_logo_dark:
type:
- string
- 'null'
uploaded_background:
type:
- string
- 'null'
uploaded_background_dark:
type:
- string
- 'null'
required:
- id
- name
- color
- text_color
- style_type
- emoji
- icon
- slug
- topic_count
- post_count
- position
- description
- description_text
- description_excerpt
- topic_url
- read_restricted
- permission
- notification_level
- can_edit
- topic_template
- topic_title_placeholder
- has_children
- subcategory_count
- sort_order
- sort_ascending
- show_subcategory_list
- num_featured_topics
- default_view
- subcategory_list_style
- default_top_period
- default_list_filter
- minimum_required_tags
- navigate_to_first_post_after_read
- topics_day
- topics_week
- topics_month
- topics_year
- topics_all_time
- subcategory_ids
- uploaded_logo
- uploaded_logo_dark
- uploaded_background
- uploaded_background_dark
required:
- can_create_category
- can_create_topic
- categories
required:
- category_list
/categories/{id}.json:
put:
summary: Updates a category
tags:
- Categories
operationId: updateCategory
parameters:
- name: id
in: path
schema:
type: integer
required: true
responses:
'200':
description: success response
content:
application/json:
schema:
additionalProperties: false
properties:
success:
type: string
category:
type: object
additionalProperties: false
properties:
id:
type: integer
name:
type: string
color:
type: string
text_color:
type: string
style_type:
type: string
emoji:
type:
- string
- 'null'
icon:
type:
- string
- 'null'
slug:
type: string
locale:
type:
- string
- 'null'
topic_count:
type: integer
post_count:
type: integer
position:
type: integer
description:
type:
- string
- 'null'
description_text:
type:
- string
- 'null'
description_excerpt:
type:
- string
- 'null'
topic_url:
type:
- string
- 'null'
read_restricted:
type: boolean
permission:
type:
- integer
- 'null'
notification_level:
type: integer
can_edit:
type: boolean
topic_template:
type:
- string
- 'null'
topic_title_placeholder:
type:
- string
- 'null'
form_template_ids:
type: array
items: {}
has_children:
type:
- boolean
- 'null'
subcategory_count:
type:
- integer
- 'null'
sort_order:
type:
- string
- 'null'
sort_ascending:
type:
- string
- 'null'
show_subcategory_list:
type: boolean
num_featured_topics:
type: integer
default_view:
type:
- string
- 'null'
subcategory_list_style:
type: string
default_top_period:
type: string
default_list_filter:
type: string
minimum_required_tags:
type: integer
navigate_to_first_post_after_read:
type: boolean
custom_fields:
type: object
additionalProperties: false
properties: {}
allowed_tags:
type: array
items: {}
allowed_tag_groups:
type: array
items: {}
allow_global_tags:
type: boolean
required_tag_groups:
type: array
items:
type: object
additionalProperties: false
properties:
name:
type: string
min_count:
type: integer
required:
- name
- min_count
category_setting:
type: object
additionalProperties: false
properties:
auto_bump_cooldown_days:
type: integer
num_auto_bump_daily:
type:
- integer
- 'null'
require_reply_approval:
type:
- boolean
- 'null'
require_topic_approval:
type:
- boolean
- 'null'
category_localizations:
type: array
items: {}
read_only_banner:
type:
- string
- 'null'
available_groups:
type: array
items: {}
auto_close_hours:
type:
- string
- 'null'
auto_close_based_on_last_post:
type: boolean
allow_unlimited_owner_edits_on_first_post:
type: boolean
default_slow_mode_seconds:
type:
- string
- 'null'
group_permissions:
type: array
items:
type: object
additionalProperties: false
properties:
permission_type:
type: integer
group_name:
type: string
group_id:
type: integer
required:
- permission_type
- group_name
- group_id
email_in:
type:
- string
- 'null'
email_in_allow_strangers:
type: boolean
mailinglist_mirror:
type: boolean
all_topics_wiki:
type: boolean
can_delete:
type: boolean
allow_badges:
type: boolean
topic_featured_link_allowed:
type: boolean
search_priority:
type: integer
uploaded_logo:
type:
- string
- 'null'
uploaded_logo_dark:
type:
- string
- 'null'
uploaded_background:
type:
- string
- 'null'
uploaded_background_dark:
type:
- string
- 'null'
category_types:
# --- truncated at 32 KB (79 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/discourse/refs/heads/main/openapi/discourse-categories-api-openapi.yml