> 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.md).

# Write Operations

Categories can be created and updated in bulk.

* **Create categories** adds new categories.
* **Update categories** changes existing ones, matched by ID.
* **Upsert categories** does both in one call.

Every write endpoint answers with the same shape. `errors` is keyed by the position of the entry in your request, starting at `1`.

```json
{
  "success": false,
  "processed": 1,
  "categories": [
    { "id": "7c2a91bb-...", "title": "Food Programs" }
  ],
  "errors": {
    "2": {
      "site_links": ["Site 9f1c... does not belong to this organization."]
    }
  }
}
```

<mark style="color:red;">By default, nothing is written unless every entry is valid, and the response is</mark> <mark style="color:red;">**400**</mark><mark style="color:red;">. Set</mark> <mark style="color:red;">**allow\_partial**</mark> <mark style="color:red;">to</mark> <mark style="color:red;">**true**</mark> <mark style="color:red;">to write the valid entries and have the rest reported back.</mark>

A request may carry at most 500 categories.
