# Creates a category

`POST /categories.json`

Authentication: no security requirement declared for this operation.

Request body: application/json

Type: any

- `name` (required)
  Type: string

- `color` (optional)
  Type: string
  
  Example:
  
  ```json
  "49d9e9"
  ```

- `text_color` (optional)
  Type: string
  
  Example:
  
  ```json
  "f0fcfd"
  ```

- `style_type` (optional)
  Type: string

- `emoji` (optional)
  Type: string

- `icon` (optional)
  Type: string

- `parent_category_id` (optional)
  Type: integer

- `allow_badges` (optional)
  Type: boolean

- `slug` (optional)
  Type: string

- `topic_featured_links_allowed` (optional)
  Type: boolean

- `permissions` (optional)
  Type: object
  
  - `everyone` (optional)
    Type: integer
    
    Example:
    
    ```json
    1
    ```
  
  - `staff` (optional)
    Type: integer
  
  Additional properties: true

- `search_priority` (optional)
  Type: integer

- `form_template_ids` (optional)
  Type: Array<any>
  
  Items:
    Type: any

- `category_localizations` (optional)
  Type: Array<object>
  
  Items:
    Type: object
    
    - `id` (optional)
      Type: integer
      
      The unique identifier for an existing localization.
      Must be included otherwise the record will be deleted.
    
    - `locale` (required)
      Type: string
      
      The locale for the localization, e.g., 'en',
      'zh_CN'. Locale should be in the list of SiteSetting.content_localization_supported_locales.
    
    - `name` (required)
      Type: string
      
      The name of the category in the specified locale.
    
    - `description` (optional)
      Type: string
      
      The description excerpt of the category in the
      specified locale.

Additional properties: false

Responses:

- 200: success response

Content type: application/json

Type: any

- `category` (required)
  Type: object
  
  - `id` (required)
    Type: integer
  
  - `name` (required)
    Type: string
  
  - `color` (required)
    Type: string
  
  - `text_color` (required)
    Type: string
  
  - `style_type` (required)
    Type: string
  
  - `emoji` (required)
    Type: string; nullable
  
  - `icon` (required)
    Type: string; nullable
  
  - `slug` (required)
    Type: string
  
  - `locale` (optional)
    Type: string; nullable
  
  - `topic_count` (required)
    Type: integer
  
  - `post_count` (required)
    Type: integer
  
  - `position` (required)
    Type: integer
  
  - `description` (required)
    Type: string; nullable
  
  - `description_text` (required)
    Type: string; nullable
  
  - `description_excerpt` (required)
    Type: string; nullable
  
  - `topic_url` (required)
    Type: string; nullable
  
  - `read_restricted` (required)
    Type: boolean
  
  - `permission` (required)
    Type: integer; nullable
  
  - `notification_level` (required)
    Type: integer
  
  - `can_edit` (required)
    Type: boolean
  
  - `topic_template` (required)
    Type: string; nullable
  
  - `topic_title_placeholder` (required)
    Type: string; nullable
  
  - `form_template_ids` (optional)
    Type: Array<any>
    
    Items:
      Type: any
  
  - `has_children` (required)
    Type: boolean; nullable
  
  - `subcategory_count` (required)
    Type: integer; nullable
  
  - `sort_order` (required)
    Type: string; nullable
  
  - `sort_ascending` (required)
    Type: string; nullable
  
  - `show_subcategory_list` (required)
    Type: boolean
  
  - `num_featured_topics` (required)
    Type: integer
  
  - `default_view` (required)
    Type: string; nullable
  
  - `subcategory_list_style` (required)
    Type: string
  
  - `default_top_period` (required)
    Type: string
  
  - `default_list_filter` (required)
    Type: string
  
  - `minimum_required_tags` (required)
    Type: integer
  
  - `navigate_to_first_post_after_read` (required)
    Type: boolean
  
  - `custom_fields` (required)
    Type: object
    
    Additional properties: false
  
  - `allowed_tags` (optional)
    Type: Array<any>
    
    Items:
      Type: any
  
  - `allowed_tag_groups` (optional)
    Type: Array<any>
    
    Items:
      Type: any
  
  - `allow_global_tags` (optional)
    Type: boolean
  
  - `required_tag_groups` (required)
    Type: Array<object>
    
    Items:
      Type: object
      
      - `name` (required)
        Type: string
      
      - `min_count` (required)
        Type: integer
      
      Additional properties: false
  
  - `category_setting` (optional)
    Type: object
    
    - `auto_bump_cooldown_days` (optional)
      Type: integer
    
    - `num_auto_bump_daily` (optional)
      Type: integer; nullable
    
    - `require_reply_approval` (optional)
      Type: boolean; nullable
    
    - `require_topic_approval` (optional)
      Type: boolean; nullable
    
    - `nested_replies_default` (optional)
      Type: boolean; nullable
    
    - `topic_posting_review_mode` (optional)
      Type: string
    
    - `reply_posting_review_mode` (optional)
      Type: string
    
    Additional properties: false
  
  - `category_localizations` (optional)
    Type: Array<any>
    
    Items:
      Type: any
  
  - `read_only_banner` (required)
    Type: string; nullable
  
  - `permission_groups` (optional)
    Type: Array<object>
    
    Items:
      Type: object
      
      - `id` (required)
        Type: integer
      
      - `name` (required)
        Type: string
      
      Additional properties: false
  
  - `available_groups` (required)
    Type: Array<any>
    
    Items:
      Type: any
  
  - `auto_close_hours` (required)
    Type: string; nullable
  
  - `auto_close_based_on_last_post` (required)
    Type: boolean
  
  - `allow_unlimited_owner_edits_on_first_post` (required)
    Type: boolean
  
  - `default_slow_mode_seconds` (required)
    Type: string; nullable
  
  - `group_permissions` (required)
    Type: Array<object>
    
    Items:
      Type: object
      
      - `permission_type` (required)
        Type: integer
      
      - `group_name` (required)
        Type: string
      
      - `group_id` (required)
        Type: integer
      
      Additional properties: false
  
  - `email_in` (required)
    Type: string; nullable
  
  - `email_in_allow_strangers` (required)
    Type: boolean
  
  - `mailinglist_mirror` (required)
    Type: boolean
  
  - `all_topics_wiki` (required)
    Type: boolean
  
  - `can_delete` (required)
    Type: boolean
  
  - `allow_badges` (required)
    Type: boolean
  
  - `topic_featured_link_allowed` (required)
    Type: boolean
  
  - `search_priority` (required)
    Type: integer
  
  - `topic_posting_review_group_ids` (required)
    Type: Array<integer>
    
    Items:
      Type: integer
  
  - `reply_posting_review_group_ids` (required)
    Type: Array<integer>
    
    Items:
      Type: integer
  
  - `uploaded_logo` (required)
    Type: string; nullable
  
  - `uploaded_logo_dark` (required)
    Type: string; nullable
  
  - `uploaded_background` (required)
    Type: string; nullable
  
  - `uploaded_background_dark` (required)
    Type: string; nullable
  
  - `category_types` (optional)
    Type: object
  
  - `category_type_settings` (optional)
    Type: object
  
  - `available_category_types` (optional)
    Type: Array<object>
    
    Items:
      Type: object
      
      - `id` (required)
        Type: string
      
      - `name` (required)
        Type: string
      
      - `title` (required)
        Type: string
      
      - `description` (required)
        Type: string
      
      - `icon` (required)
        Type: string
      
      - `available` (required)
        Type: boolean
      
      - `visible` (required)
        Type: boolean
      
      - `configuration_schema` (required)
        Type: object
      
      Additional properties: false
  
  Additional properties: false

Additional properties: false

## Examples

### cURL

```bash
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"
    }
  ]
}'
```

### JavaScript

```javascript
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();
```

### Python

```python
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)
```