> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maxicore.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Taxonomy abilities: categories, tags, and custom terms

> Create, update, assign, and bulk-manage taxonomy terms across any WordPress taxonomy — categories, tags, custom types, or WooCommerce product categories.

Taxonomy abilities let you manage terms in any registered WordPress taxonomy and control which terms are assigned to your posts, pages, and custom post types. You can assign terms one at a time, replace all terms in a taxonomy in a single call, or update terms across hundreds of posts at once with the bulk operation.

## All taxonomy abilities

| Ability                  | Description                                                                            | Capability                                   | Plan |
| ------------------------ | -------------------------------------------------------------------------------------- | -------------------------------------------- | ---- |
| `maxi/create-term`       | Create a new term in any taxonomy.                                                     | `manage_categories`                          | Lite |
| `maxi/get-term`          | Get a term by its ID.                                                                  | `read`                                       | Lite |
| `maxi/update-term`       | Update a term's name, slug, description, or parent.                                    | `manage_categories`                          | Lite |
| `maxi/delete-term`       | Delete a term.                                                                         | `manage_categories`                          | Lite |
| `maxi/list-terms`        | List terms with optional filters for parent, search query, and order.                  | `read`                                       | Lite |
| `maxi/assign-terms`      | Append terms to a post while keeping existing term assignments.                        | `edit_posts`                                 | Lite |
| `maxi/remove-terms`      | Remove specific terms from a post.                                                     | `edit_posts`                                 | Lite |
| `maxi/set-terms`         | Replace all terms on a post for a given taxonomy.                                      | `edit_posts`                                 | Lite |
| `maxi/bulk-update-terms` | Assign, append, or remove terms across up to 500 posts and 100 terms in a single call. | `edit_posts` or `edit_products` + per-object | Lite |

<Note>
  All taxonomy abilities work with any registered taxonomy: `category`, `post_tag`, `product_cat`, or any custom taxonomy on your site.
</Note>

## Key ability examples

### maxi/create-term

Create a new term. The `slug` is optional — if omitted, WordPress generates one from the name.

```json theme={null}
{
  "taxonomy": "category",
  "name": "Technology",
  "slug": "technology"
}
```

### maxi/assign-terms

Add terms to a post without removing any currently assigned terms. Pass term IDs.

```json theme={null}
{
  "object_id": 123,
  "taxonomy": "category",
  "terms": [45, 67]
}
```

### maxi/set-terms

Replace all terms on a post for a given taxonomy. Any terms not in the `terms` array are removed.

```json theme={null}
{
  "object_id": 123,
  "taxonomy": "category",
  "terms": [45]
}
```

<Tip>
  To clear all terms from a post in a taxonomy, use `maxi/set-terms` with an empty `terms` array: `"terms": []`.
</Tip>

### maxi/bulk-update-terms

Update terms across many posts at once. Accepts either a single `object_id` or an `object_ids` array. Use the `mode` field to control how terms are applied.

```json theme={null}
{
  "object_ids": [100, 101, 102],
  "taxonomy": "category",
  "terms": [45],
  "mode": "append"
}
```

<AccordionGroup>
  <Accordion title="Mode: replace">
    Replaces all existing terms in the taxonomy with the provided list. Pass an empty `terms` array to clear all terms from every object in the batch.
  </Accordion>

  <Accordion title="Mode: append">
    Adds the provided terms to each object while keeping any terms already assigned. No existing term assignments are removed.
  </Accordion>

  <Accordion title="Mode: remove">
    Removes only the specified terms from each object. Other term assignments are left untouched.
  </Accordion>
</AccordionGroup>

<Warning>
  `maxi/bulk-update-terms` supports up to 500 objects and 100 terms per call. Requests that exceed these limits are rejected.
</Warning>

## Yoast SEO integration

If the Yoast SEO plugin is active on your site, you can set SEO metadata on taxonomy terms using `maxi/set-yoast-term-seo`.

```json theme={null}
{
  "taxonomy": "category",
  "term_id": 45,
  "title": "Technology articles — My Site",
  "description": "Browse all posts in the Technology category."
}
```

This ability creates the `wpseo_taxonomy_meta` record if it does not exist and merges with any existing Yoast keys — it does not overwrite other Yoast settings like canonical or noindex. When the Yoast Indexables table is available, the matching row is synced automatically. The response includes `indexable_synced: true` when that sync succeeded.

<Info>
  `maxi/set-yoast-term-seo` requires the Yoast SEO plugin to be installed and active (`WPSEO_VERSION` must be defined). The ability returns an error if Yoast is not available.
</Info>