Welcome to the NZRT Wiki Podcast. Today we’re looking at Tags.

If you’ve spent any time in Flarum, our forum platform, you’ve probably noticed that every discussion sits inside some kind of category. That category system is powered by Tags. Tags are how Flarum organises discussions, controls who can see what, and manages permissions across the forum. Let’s walk through how they work.

First, let’s talk about the different types of tags you’ll encounter. There are four. The first is a primary tag — this is the main category for a discussion, and depending on how the Tags extension is configured, it may be required. You can’t post without one. The second type is a secondary tag, which is an optional extra label you can layer on top of the primary one. Think of it as a cross-reference or a way to flag a discussion as belonging to more than one topic area. Then you have parent tags, which are top-level grouping tags that sit above other tags. And finally, child tags are nested underneath a parent. So you might have a parent tag called something like Projects, with child tags underneath it for specific project areas.

Now let’s look at what makes up a tag — its fields. There are ten of them. First is the id, which is just a unique number that identifies the tag internally. Then there’s the name, which is the human-readable display name you see in the forum. The slug is the URL-friendly version of that name — it’s what appears in the web address when you filter by a tag. The description is an optional text field where you can explain what the tag is for. Colour is a hex colour string, so you can give each tag its own visual identity in the forum interface. Icon lets you assign a FontAwesome icon class to the tag. Position controls the sort order — lower numbers appear first. Then there are two visibility-related fields: isRestricted, which flags whether the tag is limited to specific user groups, and isHidden, which hides the tag entirely from guests who aren’t logged in. Finally, the parent field is a relationship field — if a tag is a child tag, this field points to its parent.

On the topic of permissions, tags in Flarum aren’t just organisational — they can actually control access. You can set per-tag permission overrides through the Admin panel under Permissions. This is really useful if you want to lock down certain areas of the forum so only specific groups can post to them, or even just view them. It gives you fine-grained control without having to create entirely separate forum spaces.

Managing tags is done through the Admin area. You go to Admin, then Tags, and from there you can create new tags, edit existing ones, and reorder them. Reordering is drag and drop. And if you want to nest a tag as a child under a parent, you just drag it onto the parent tag. It’s a pretty visual interface once you’re in there.

Now let’s talk about the API. If you’re working with tags programmatically — for example, in an agent script or integration — you’ll want to know how to retrieve the tag list. You make a GET request to the tags endpoint on the API. In practice, that means calling the API address with the path ending in api/tags, and you include an authorisation header with your token. What comes back is the full list of all tags in one go. There’s no pagination here — you get everything in a single response, which makes it straightforward to parse and work with. If you’re building something that needs to look up a tag ID by its slug, or populate a dropdown of available tags, this is the call you want.

One practical thing to keep in mind: when you’re creating or tagging a discussion through the API, you’ll often need the tag’s slug for human-readable references, but the actual API calls for things like patching or associating tags with discussions typically need the numeric ID. So it’s worth keeping a mapping of slug to ID handy. In fact, the NZRT operations documentation maintains that exact list for the tags we use regularly.

That’s the Tags system in a nutshell. They’re more than just labels — they’re the backbone of how Flarum structures content, manages visibility, and enforces permissions across the forum. Whether you’re an admin setting things up in the interface or a developer working through the API, understanding tag types, fields, and how permissions layer onto them will save you a lot of guesswork.

That’s it for this episode of the NZRT Wiki Podcast. Thanks for listening.