REST API

  • The REST API features below are still considered experimental and not officially supported.
  • Please be careful with all operations that change data. There will be no confirmation dialog. To be on the safe side, make a backup of your database before you start and test first with non-critical sample data.
  • POST and PUT requests are handled by WordPress interchangeably.
  • If you use a client like Postman or RESTED, send the attributes as URLencoded form data (Header: Content-Type application/x-www-form-urlencoded) and use Basic Auth with your application password, available in WP 5.6+ or via 3rd-party plugins (untested and unsupported).
  • Permissions to create or edit groups can be changed in the Tag Groups Settings (premium only).
  • Add the routes after your site URL. In GET requests you can simply add the arguments as parameters. Any returned data will be JSON-encoded, if applicable.

Enabling POST/PUT/DELETE

While all GET (retrieve) operations are available by default, all PUT/POST/DELETE (create, update, delete) operations are opt-in. You enable them by adding to your wp-config.php:

define( 'TAG_GROUPS_REST_API_EDITABLE', true );

Additionally you may have to authenticate, see below.

1. Retrieve one or more groups

Returns all groups or one group with its ID, label, position and terms.

Routes

/wp-json/tag-groups/v1/groups/

/wp-json/tag-groups/v1/groups/{id}/

Methods

GET

Arguments

ArgumentValuesDefaultDescription
taxonomycomma-separated listall that are selected for tag groups
hide_emptybooleanfalse
fieldsids, …ids
orderbyname, …name
orderASC, DESCASC
typeall, metaboxallIf you choose ‘metabox’, you see all groups that appear in the Tag Meta Box. (premium only)

2. Create or update a group

In order to use this endpoint you will need to authenticate as a user who has sufficient permissions.

For creating a new group you use 0 as ID.

Routes

/wp-json/tag-groups/v1/groups/{id}/

Methods

PUT, POST

Arguments

ArgumentValuesDefaultDescription
labelstringcannot be empty if you create a new group
positioninteger > 0after last existingThe position among the groups. The new group will be added at the end if you omit this argument.

3. Delete a group

In order to use this endpoint you will need to authenticate as a user who has sufficient permissions.

Routes

/wp-json/tag-groups/v1/groups/{id}/

Methods

DELETE

Arguments

not available

1. Retrieve one or more terms (tags)

Returns all terms or one term with its ID, label, position and terms.

Routes

/wp-json/tag-groups/v1/terms/

/wp-json/tag-groups/v1/terms/{id}/

Methods

GET

Arguments

ArgumentValuesDefaultDescription
taxonomycomma-separated list, or keyword “public”all enabledThis endpoint returns only taxonomies that are enabled in the Tag Groups (Premium) settings. The keyword “public”, however, makes it return all public taxonomies, including those that are not-enabled.
hide_emptybooleanfalse
fieldsids
groupIDrestrict terms to those belonging to a certain group
orderbyname
orderASC

2. Update the groups of a term (tag)

In order to use this endpoint you will need to authenticate as a user who has sufficient permissions.

Routes

/wp-json/tag-groups/v1/terms/{id}/

Methods

PUT, POST

Arguments

ArgumentValuesDescription
groupscomma-separated list of group IDsPlease note that groups will not be added but overwrite previous data.

1. Retrieve enabled taxonomies

Returns all taxonomies (slug and name) that are enabled for tag groups or for the Tag Meta Box (premium only).

Routes

/wp-json/tag-groups/v1/taxonomies/

Methods

GET

Arguments

ArgumentValuesDefaultDescription
typemetabox, enabledenabled

2. Update enabled taxonomies

Updates all taxonomies that are enabled for tag groups or for the Tag Meta Box (premium only).

In order to use this endpoint you will need to authenticate as a user who has sufficient permissions.

Routes

/wp-json/tag-groups/v1/taxonomies/

Methods

PUT, POST

Arguments

ArgumentValuesDescription
enabledcomma-separated list of taxonomy slugstaxonomies that are enabled for tag groups
metaboxcomma-separated list of taxonomy slugstaxonomies that are enabled for the Tag Meta Box (premium only)

Post Tags

Only available in the premium version.

These endpoints retrieve and update only tags in groups as used by this plugin. If you need to handle other post data you should use the built-in endpoints of WP.

1. Retrieve post tags

Only posts will appear that you are allowed to view.

The ID is a post ID. For each post the authenticated user’s (if applicable) permissions will be checked.

Routes

/wp-json/tag-groups/v1/post-tags/

/wp-json/tag-groups/v1/post-tags/{id}/

Methods

GET

Arguments

ArgumentValuesDescription
post_typestring (slug)usually “post_tag”

2. Update post tags

In order to use this endpoint you will need to authenticate as a user who has sufficient permissions.

The ID is a post ID. For each post the authenticated user’s permissions will be checked.

If you add a tag to a post and this tag is not yet assigned to the submitted group, then this group will be assigned.

Routes

/wp-json/tag-groups/v1/post-tags/{id}/

Methods

PUT, POST

Arguments

ArgumentValuesDescription
termsJSON-encoded arrayJSON-encoded array of group IDs as keys and an array of term IDs as each value. Use group ID 0 for unassigned tags. example: {“0″:[1235],”9”:[147]}
taxonomytaxonomy slug