Ability: acf/custom-taxonomies

Documentation Ability: acf/custom-taxonomies

Last updated Mar 30, 2026

Overview

Lists all ACF-registered custom taxonomies.

Description

Returns an array of taxonomies that were created using ACF’s taxonomy registration feature. Includes taxonomies that have AI access enabled.

Input

This ability accepts no input parameters.

null

Output

{
  "custom_taxonomies": [
    {
      "taxonomy": "product_category",
      "label": "Product Category",
      "plural_label": "Product Categories",
      "description": "Categories for organizing products",
      "public": true,
      "hierarchical": true,
      "show_in_rest": true,
      "rest_base": "product-categories",
      "post_types": ["product"],
      "allow_ai_access": true,
      "ai_description": "Hierarchical categories for product organization"
    }
  ],
  "count": 1,
  "message": "Found 1 ACF custom taxonomy(s)."
}

Output Properties

custom_taxonomies (array) Array of taxonomy configuration objects.

count (integer) Total number of taxonomies returned.

message (string) Human-readable status message.

Taxonomy Properties

Property	Type	Description
taxonomy	string	Taxonomy key/slug (max 32 characters)
label	string	Singular label
plural_label	string	Plural label
description	string	Taxonomy description
public	boolean	Whether publicly accessible
hierarchical	boolean	Whether supports parent/child (like categories)
show_in_rest	boolean	Whether exposed in REST API
rest_base	string	REST API base path
post_types	array	Associated post type slugs
allow_ai_access	boolean	Whether AI access is enabled
ai_description	string	Description to help AI understand the purpose

Annotations

Annotation	Value
readonly	true
destructive	false
idempotent	true

Permissions

Requires the ACF capability (default: manage_options).

Example

List all custom taxonomies registered through ACF.

Response:

{
  "custom_taxonomies": [
    {
      "taxonomy": "event_category",
      "label": "Event Category",
      "plural_label": "Event Categories",
      "hierarchical": true,
      "public": true,
      "post_types": ["event"],
      "show_in_rest": true,
      "allow_ai_access": true,
      "ai_description": "Categories for classifying events by type"
    },
    {
      "taxonomy": "event_tag",
      "label": "Event Tag",
      "plural_label": "Event Tags",
      "hierarchical": false,
      "public": true,
      "post_types": ["event"],
      "show_in_rest": true,
      "allow_ai_access": true
    }
  ],
  "count": 2,
  "message": "Found 2 ACF custom taxonomy(s)."
}

Notes

• Only taxonomies registered through ACF are returned (not core or plugin taxonomies)
• Taxonomies must have show_in_rest enabled to be fully accessible via abilities
• Per-taxonomy abilities (query, create, view, update, delete) are registered dynamically for each taxonomy with AI access
• Hierarchical taxonomies support parent/child term relationships (like categories)
• Non-hierarchical taxonomies are flat (like tags)

Related

• Integrations: Ability: acf/custom-post-types
• Integrations: Ability: acf/create-custom-taxonomy
• Integrations: Ability: acf/create-custom-post-type
• Integrations: Ability: acf/field-groups
• Videos: Creating a Custom Taxonomy with ACF