Creates a category

POST

https://discourse.example.com/categories.json

Creates a category

curl -X POST 'https://discourse.example.com/categories.json' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "name": "string",
  "color": "49d9e9",
  "text_color": "f0fcfd",
  "style_type": "string",
  "emoji": "string",
  "icon": "string",
  "parent_category_id": 0,
  "allow_badges": true,
  "slug": "string",
  "topic_featured_links_allowed": true,
  "permissions": {
    "everyone": 1,
    "staff": 0
  },
  "search_priority": 0,
  "form_template_ids": [],
  "category_localizations": [
    {
      "id": 0,
      "locale": "string",
      "name": "string",
      "description": "string"
    }
  ]
}'

const body = `{
  "name": "string",
  "color": "49d9e9",
  "text_color": "f0fcfd",
  "style_type": "string",
  "emoji": "string",
  "icon": "string",
  "parent_category_id": 0,
  "allow_badges": true,
  "slug": "string",
  "topic_featured_links_allowed": true,
  "permissions": {
    "everyone": 1,
    "staff": 0
  },
  "search_priority": 0,
  "form_template_ids": [],
  "category_localizations": [
    {
      "id": 0,
      "locale": "string",
      "name": "string",
      "description": "string"
    }
  ]
}`;

const response = await fetch('https://discourse.example.com/categories.json', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "name": "string",
  "color": "49d9e9",
  "text_color": "f0fcfd",
  "style_type": "string",
  "emoji": "string",
  "icon": "string",
  "parent_category_id": 0,
  "allow_badges": true,
  "slug": "string",
  "topic_featured_links_allowed": true,
  "permissions": {
    "everyone": 1,
    "staff": 0
  },
  "search_priority": 0,
  "form_template_ids": [],
  "category_localizations": [
    {
      "id": 0,
      "locale": "string",
      "name": "string",
      "description": "string"
    }
  ]
}'''

response = requests.post(
    'https://discourse.example.com/categories.json',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "name": "string",
  "color": "49d9e9",
  "text_color": "f0fcfd",
  "style_type": "string",
  "emoji": "string",
  "icon": "string",
  "parent_category_id": 0,
  "allow_badges": true,
  "slug": "string",
  "topic_featured_links_allowed": true,
  "permissions": {
    "everyone": 1,
    "staff": 0
  },
  "search_priority": 0,
  "form_template_ids": [],
  "category_localizations": [
    {
      "id": 0,
      "locale": "string",
      "name": "string",
      "description": "string"
    }
  ]
}

200

{
  "category": {
    "id": 0,
    "name": "string",
    "color": "string",
    "text_color": "string",
    "style_type": "string",
    "emoji": "string",
    "icon": "string",
    "slug": "string",
    "locale": "string",
    "topic_count": 0,
    "post_count": 0,
    "position": 0,
    "description": "string",
    "description_text": "string",
    "description_excerpt": "string",
    "topic_url": "string",
    "read_restricted": true,
    "permission": 0,
    "notification_level": 0,
    "can_edit": true,
    "topic_template": "string",
    "topic_title_placeholder": "string",
    "form_template_ids": [],
    "has_children": true,
    "subcategory_count": 0,
    "sort_order": "string",
    "sort_ascending": "string",
    "show_subcategory_list": true,
    "num_featured_topics": 0,
    "default_view": "string",
    "subcategory_list_style": "string",
    "default_top_period": "string",
    "default_list_filter": "string",
    "minimum_required_tags": 0,
    "navigate_to_first_post_after_read": true,
    "custom_fields": {},
    "allowed_tags": [],
    "allowed_tag_groups": [],
    "allow_global_tags": true,
    "required_tag_groups": [
      {
        "name": "string",
        "min_count": 0
      }
    ],
    "category_setting": {
      "auto_bump_cooldown_days": 0,
      "num_auto_bump_daily": 0,
      "require_reply_approval": true,
      "require_topic_approval": true,
      "nested_replies_default": true,
      "topic_posting_review_mode": "string",
      "reply_posting_review_mode": "string"
    },
    "category_localizations": [],
    "read_only_banner": "string",
    "permission_groups": [
      {
        "id": 0,
        "name": "string"
      }
    ],
    "available_groups": [],
    "auto_close_hours": "string",
    "auto_close_based_on_last_post": true,
    "allow_unlimited_owner_edits_on_first_post": true,
    "default_slow_mode_seconds": "string",
    "group_permissions": [
      {
        "permission_type": 0,
        "group_name": "string",
        "group_id": 0
      }
    ],
    "email_in": "string",
    "email_in_allow_strangers": true,
    "mailinglist_mirror": true,
    "all_topics_wiki": true,
    "can_delete": true,
    "allow_badges": true,
    "topic_featured_link_allowed": true,
    "search_priority": 0,
    "topic_posting_review_group_ids": [
      0
    ],
    "reply_posting_review_group_ids": [
      0
    ],
    "uploaded_logo": "string",
    "uploaded_logo_dark": "string",
    "uploaded_background": "string",
    "uploaded_background_dark": "string",
    "category_types": {},
    "category_type_settings": {},
    "available_category_types": [
      {
        "id": "string",
        "name": "string",
        "title": "string",
        "description": "string",
        "icon": "string",
        "available": true,
        "visible": true,
        "configuration_schema": {}
      }
    ]
  }
}

Body

application/json

namestringrequired

colorstring

Example

49d9e9

text_colorstring

Example

f0fcfd

style_typestring

emojistring

iconstring

parent_category_idinteger

allow_badgesboolean

slugstring

topic_featured_links_allowedboolean

permissionsobject

Show child attributes

everyoneinteger

Example

staffinteger

search_priorityinteger

form_template_idsArray<any>

category_localizationsArray<object>

Show child attributes

idinteger

The unique identifier for an existing localization. Must be included otherwise the record will be deleted.

localestringrequired

The locale for the localization, e.g., 'en', 'zh_CN'. Locale should be in the list of SiteSetting.content_localization_supported_locales.

namestringrequired

The name of the category in the specified locale.

descriptionstring

The description excerpt of the category in the specified locale.

Response

200OKany

success response

Response fields application/json

categoryobjectrequired

Show child attributes

idintegerrequired

namestringrequired

colorstringrequired

text_colorstringrequired

style_typestringrequired

emojistring | nullrequired

iconstring | nullrequired

slugstringrequired

localestring | null

topic_countintegerrequired

post_countintegerrequired

positionintegerrequired

descriptionstring | nullrequired

description_textstring | nullrequired

description_excerptstring | nullrequired

topic_urlstring | nullrequired

read_restrictedbooleanrequired

permissioninteger | nullrequired

notification_levelintegerrequired

can_editbooleanrequired

topic_templatestring | nullrequired

topic_title_placeholderstring | nullrequired

form_template_idsArray<any>

has_childrenboolean | nullrequired

subcategory_countinteger | nullrequired

sort_orderstring | nullrequired

sort_ascendingstring | nullrequired

show_subcategory_listbooleanrequired

num_featured_topicsintegerrequired

default_viewstring | nullrequired

subcategory_list_stylestringrequired

default_top_periodstringrequired

default_list_filterstringrequired

minimum_required_tagsintegerrequired

navigate_to_first_post_after_readbooleanrequired

custom_fieldsobjectrequired

allowed_tagsArray<any>

allowed_tag_groupsArray<any>

allow_global_tagsboolean

required_tag_groupsArray<object>required

Show child attributes

namestringrequired

min_countintegerrequired

category_settingobject

Show child attributes

auto_bump_cooldown_daysinteger

num_auto_bump_dailyinteger | null

require_reply_approvalboolean | null

require_topic_approvalboolean | null

nested_replies_defaultboolean | null

topic_posting_review_modestring

reply_posting_review_modestring

category_localizationsArray<any>

read_only_bannerstring | nullrequired

permission_groupsArray<object>

Show child attributes

idintegerrequired

namestringrequired

available_groupsArray<any>required

auto_close_hoursstring | nullrequired

auto_close_based_on_last_postbooleanrequired

allow_unlimited_owner_edits_on_first_postbooleanrequired

default_slow_mode_secondsstring | nullrequired

group_permissionsArray<object>required

Show child attributes

permission_typeintegerrequired

group_namestringrequired

group_idintegerrequired

email_instring | nullrequired

email_in_allow_strangersbooleanrequired

mailinglist_mirrorbooleanrequired

all_topics_wikibooleanrequired

can_deletebooleanrequired

allow_badgesbooleanrequired

topic_featured_link_allowedbooleanrequired

search_priorityintegerrequired

topic_posting_review_group_idsArray<integer>required

reply_posting_review_group_idsArray<integer>required

uploaded_logostring | nullrequired

uploaded_logo_darkstring | nullrequired

uploaded_backgroundstring | nullrequired

uploaded_background_darkstring | nullrequired

category_typesobject

category_type_settingsobject

available_category_typesArray<object>

Show child attributes

idstringrequired

namestringrequired

titlestringrequired

descriptionstringrequired

iconstringrequired

availablebooleanrequired

visiblebooleanrequired

configuration_schemaobjectrequired

Docs by Sourcey