Ability: acf/create-custom-taxonomy

Creates a new custom taxonomy in ACF.
Description
Creates a new taxonomy using ACF’s taxonomy registration system. The taxonomy is registered with WordPress and optionally enabled for AI access.
Input
{
  "taxonomy": "product_category",
  "label": "Product Category",
  "plural_label": "Product Categories",
  "post_types": ["product"]
}
Required Properties
taxonomy
(string) The taxonomy key/slug. Must be lowercase alphanumeric with underscores or hyphens. Maximum 32 characters.
label
(string) The singular label for the taxonomy.
plural_label
(string) The plural label for the taxonomy.
post_types
(array) Array of post type slugs to associate with this taxonomy.
Optional Properties
description
(string) Description of the taxonomy.
public
(boolean) Whether the taxonomy is publicly accessible. Default: 
true
hierarchical
(boolean) Whether the taxonomy supports parent/child relationships (like categories). Default: 
false (flat like tags)
show_in_rest
(boolean) Whether to expose in the REST API. Required for block editor and AI abilities. Default: 
true
rest_base
(string) Custom REST API base path. Defaults to taxonomy key.
show_admin_column
(boolean) Whether to show a column in the post list table. Default: 
false
allow_ai_access
(boolean) Whether to allow AI access to this taxonomy. Default: 
true
ai_description
(string) Description to help AI understand the purpose of this taxonomy.
Output
{
  "success": true,
  "taxonomy": {
    "taxonomy": "product_category",
    "label": "Product Category",
    "plural_label": "Product Categories",
    "hierarchical": false,
    "public": true,
    "post_types": ["product"],
    "show_in_rest": true,
    "allow_ai_access": true
  },
  "message": "Custom taxonomy 'product_category' created successfully."
}
Annotations
Annotation
Value
readonly
false
destructive
false
idempotent
false
Permissions
Requires the ACF capability (default: 
manage_options).
Example
Create a hierarchical Event Category taxonomy:
{
  "taxonomy": "event_category",
  "label": "Event Category",
  "plural_label": "Event Categories",
  "description": "Categories for organizing events",
  "post_types": ["event"],
  "hierarchical": true,
  "show_admin_column": true,
  "allow_ai_access": true,
  "ai_description": "Hierarchical categories for event types (conferences, workshops, meetups)"
}
Response:
{
  "success": true,
  "taxonomy": {
    "taxonomy": "event_category",
    "label": "Event Category",
    "plural_label": "Event Categories",
    "description": "Categories for organizing events",
    "hierarchical": true,
    "public": true,
    "post_types": ["event"],
    "show_in_rest": true,
    "show_admin_column": true,
    "allow_ai_access": true,
    "ai_description": "Hierarchical categories for event types (conferences, workshops, meetups)"
  },
  "message": "Custom taxonomy 'event_category' created successfully."
}
Errors
Error
Cause
Invalid taxonomy key
Key contains invalid characters or exceeds 32 characters
Taxonomy already exists
A taxonomy with this key is already registered
Missing required field
taxonomy, 
label, 
plural_label, or 
post_types not provided
Invalid post type
One or more specified post types do not exist
Notes
Taxonomy keys must be unique across WordPress
Reserved taxonomy keys (
category, 
post_tag, etc.) cannot be used
The taxonomy is immediately registered and available in the admin
Dynamic abilities (query, create, view, update, delete) are registered for taxonomies with 
show_in_rest and 
allow_ai_access enabled
Set 
hierarchical: true for category-like taxonomies with parent/child support
Set 
hierarchical: false for tag-like flat taxonomies