> For the complete documentation index, see [llms.txt](https://docs.vomevolunteer.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vomevolunteer.com/resources/categories/write-operations/create-categories.md).

# Create categories

This endpoint creates one or more categories in your organization. Use it when the categories do not exist in Vome yet.

<mark style="color:red;">A</mark> <mark style="color:red;">**title**</mark> <mark style="color:red;">is required on every category. Sending an</mark> <mark style="color:red;">**id**</mark> <mark style="color:red;">is rejected here; use</mark> <mark style="color:red;">**Upsert categories**</mark> <mark style="color:red;">if you want to create or update in one call.</mark>

#### Endpoint

```plaintext
POST api/categories/bulk-create/
```

#### Example Request Payload

```json
{
    "allow_partial": false,
    "categories": [
        {
            "title": "Community Outreach",
            "description": "Programs and roles related to outreach work.",
            "cover_image": "Volunteering",  // or "cover_image_id": "<uuid>"
            "site_links": [
                {
                    "site_id": "2b5b2f4e-9a1e-4a3f-9d21-0f0a2f5c77aa",
                    "permission": "read"  // or "edit"
                }
            ],
            "chat_enabled": true,
            "chat_announcement_only": false
        },
        {
            "title": "Food Programs"
        }
    ]
}
```

#### Fields

| Field                    | Required | Description                                                                  |
| ------------------------ | -------- | ---------------------------------------------------------------------------- |
| `title`                  | yes      | The category name.                                                           |
| `description`            | no       | Shown to users on the category.                                              |
| `cover_image`            | no       | The name of a cover, for example `Volunteering`.                             |
| `cover_image_id`         | no       | The ID of a cover, if you have it.                                           |
| `site_links`             | no       | Sites to link the category to.                                               |
| `chat_enabled`           | no       | Turns the category chat on. Leave it out to use your organization's default. |
| `chat_announcement_only` | no       | Limits the chat to announcements.                                            |

#### Choosing a cover

Every category gets artwork, because one without a cover renders as a blank tile. There are three ways it is decided, in order:

1. `cover_image_id`, when you have the ID.
2. `cover_image`, naming a cover. Matching ignores case and surrounding spaces.
3. Neither, in which case Vome's **Volunteering** cover is used, or the first cover available to your organization if that one is not there.

List what you can choose from with [Category Covers](https://docs.vomevolunteer.com/resources/categories/category-covers.md).

<mark style="color:red;">A</mark> <mark style="color:red;">**cover\_image**</mark> <mark style="color:red;">name that matches nothing is an error, not a fallback. The response lists the covers available to you, so a typo is easy to correct rather than silently producing the wrong artwork.</mark>

#### Behavior

* Leaving `chat_enabled` out applies your organization's setting for automatically enabling chat on new categories, exactly as creating a category in Vome does. Sending `true` or `false` always wins over that setting.
* Category titles do not have to be unique, so sending the same title twice creates two categories.
